Repository guide

The shared Cosmik foundation: the approved Cosmik marks, baseline semantic tokens, Inter and IBM Plex Mono, a framework-neutral controls layer, practical guidance, interactive references and the tools product families use to build on it. The kit defines reusable principles and tokens independently of any website, application layout or framework. Its examples demonstrate components and states, not a proposed product design.

Product families live in their own repositories and build on a pinned release of this one: cosmiklabs/brand-hplx and cosmiklabs/brand-tectra. See product families.

Version: 0.16.1 (v0.16.1, prepared 26 October 2026; untagged until released). Consume an immutable release tag; working-tree changes are unreleased until tagged. See CHANGELOG.md.

Start here#

Open specimens/components.html in a browser; it works offline. It demonstrates the baseline and the shared controls in light and dark modes with neutral component examples. It does not prescribe a consumer's information architecture. Interact with examples as well as reading them: source validity alone does not prove a usable interface.

HTML reference#

A complete HTML reference is generated from the current Markdown guide, tokens and asset manifest, including live type and color exhibits, accepted asset downloads, local guide search, a token reference and the interactive component examples. The Markdown remains authoritative; the HTML is rebuilt rather than maintained as a second copy of the rules.

Run npm run dev:reference for the local preview. The GitHub Pages workflow builds and publishes only generated site/ output when enabled. See the HTML reference instructions for editing, offline use, validation and first-time Pages setup.

What lives here#

Use a family's kit, from its own repository, for its product. If family content is presented inside a Cosmik organisation surface, that enclosing identity stays baseline. Family JSON and Rust outputs include the baseline values; browser integration loads the baseline CSS before the scoped family CSS.

Approved artwork does not settle product availability or commercial terms. The voice guide describes the company and its messaging; each family guide sets its own product presentation and constraints.

Consume a release#

Pin an exact vX.Y.Z tag. Never depend on main for production assets.

• Vendor files: copy the generated outputs and assets you use, along with required fonts and their licence notices. Verify their SHA-256 values against asset-manifest.json from the same tag. Or use scripts/vendor.mjs, which copies the release's distribution set and writes a lock that vendor.mjs verify checks. Products take their family's product brand repository the same way; it carries this foundation with its own lock. See vendoring a release.

• Git submodule: pin its checkout to the exact tag or commit, not a moving branch. Keep the checked-in submodule pointer with the consumer change.

• Git subtree: import a tagged release when files need to live directly in the consumer's history.

Canonical entry points and asset status are in asset-manifest.json. Retired assets and superseded guides are recoverable from Git history. Keep application components outside the vendored kit. Web and native examples explain token, theme, font and motion integration.

Repository map#

Working on the kit#

Requires Node.js 22 or later. No package installation is needed for the repository scripts. Read AGENTS.md and governance before editing. Edit token and artwork sources, not their generated outputs. Guidance, specimens, tests and scripts are hand-maintained. Preserve approved originals and font notices.

npm run build                # regenerate baseline outputs and refresh permitted manifest hashes
npm run check                # contrast, integrity and regression checks
npm test                     # regression tests alone
npm run check:browser        # interactive references in Chromium
npm run check:reproducible   # rebuild from a clean commit; fail on generated drift

Set BRAND_BROWSER to an installed Chromium executable when running browser checks. Set BRAND_SCREENSHOTS to retain browser review images. Inspect those images and exercise the changed flows; passing assertions are not a visual design review. CI runs reproducibility, repository and browser checks. .gitattributes keeps text LF so hashes represent the same committed bytes across platforms. Release steps and consumer migration belong in governance.

See specimen validation for what has actually run and what remains manual. Browser zoom, assistive technologies and other engines need appropriate review; the reference cannot certify a consuming product.

Fonts and rights#

Inter and IBM Plex Mono are bundled under SIL OFL 1.1. Use the supplied files and preserve fonts/licenses/ notices when redistributing fonts. Provenance is recorded in the manifest. A family's own typefaces, such as HPLX's Spectral headings, are bundled and licensed in its repository. No typeface match or rights clearance for the original Cosmik wordmark is asserted.

LICENSE.md covers tooling, token data and written guidance under MIT, with separate restrictions for marks and artwork, and separate font licences. A code licence does not grant unrestricted use of the identity. The organisation profile is maintained in the separate .github repository.