design

Why it exists

Every system in the family has a surface — a README, a UI, a wordmark, a diagram. Left to each repo, those surfaces drift: the same blue diverges into five blues, alt text gets copy-pasted and goes stale, a figure embed in one doc no longer matches its source. design owns the seam the others are drawn against. It is not a system of its own and not a deployable runtime; it ships a vocabulary, a component library, and a conformance toolchain that the substance systems consume as published packages.

A concrete example

A figure — say a light/dark wordmark pair — is registered once in a per-repo docs/figures.json manifest, with its alt text and canonical home living in exactly one place. Instead of hand-written <picture> blocks duplicated across the README, the brand docs, and the token guide, each embed is a <!-- design:figure id=… --> sentinel that design figure sync fills in. design figure catalog generates the figure index from the same manifest. design doctor folds the --check gates into its report, so a drifted embed fails CI rather than rotting silently. design dogfoods this on itself: the flagship repo is the worked example.

What it unlocks

Because the look is single-sourced, the rest of the family can speak it without re-deriving it. The @bitspark/design package publishes the tokens (tokens.css + base.css), the brand rules, and the README styleguide; @bitspark/ui is the generic Svelte component library drawn against those tokens. The loupe toolchain gates components visually — loupe run checks a component manifest against design lenses (contrast, alignment, gap rhythm, occlusion, focus-ring clipping), and loupe gallery builds the interactive gallery. The consumer frontends — ontos, logos, stele, and thesmos — render their own surfaces against this one vocabulary. design declares no upstream dependencies: it sits at the infrastructure layer, orthogonal to the substance.

What's next

The vocabulary is published as @bitspark/design at 0.5.0 — tokens, brand, and the styleguide are stable and in use. The frontier is still filling in: the loupe lenses, the component library, and the family roster. One known gap is explicit: design figure sync and docs lint auto-scan only README.md and docs/**, so sentinel blocks in out-of-root pages like the token and brand guides are synced but not yet CI-gated. Extending the scan surface so those pages can't silently drift is tracked separately.