DESIGN:OS — a multi-runtime design CLI. The host model writes the HTML; DESIGN:OS supplies
the taste: a knowledge/ core the model reads directly, a deterministic ui kernel that
does every non-LLM transform, and a quality gate the model cannot talk past.
Road: One of the six ways a project's design system enters the store (E1–E6 on the workflow map). A road is named by its evidence source, not its command — the Figma road, the code road, the URL road. Avoid: path, entry point, on-ramp (reserve "on-ramp" for the whole onboarding journey)
Code road: The E2 road — compiling a design system from an existing codebase's own evidence: the CSS custom properties it declares and the components it ships. Avoid: brownfield-code path, code extraction, learn-from-code
Vocabulary:
The what a design system is made of — its tokens. Harvested by the C0 step of a road
(ingest-figma-ds on the Figma road).
Avoid: primitives (that names a token tier, not the layer), token layer
Grammar:
The how a design system is actually used — the measured house style over real screens,
written to CONVENTIONS.md. The companion to Vocabulary, harvested by the C7 step
(synthesize-conventions).
Avoid: conventions (ambiguous with the file), usage DNA, house rules
Mode:
A named variant of a token's value across themes. The base mode is the token's $value;
every other mode is $extensions["mode.<name>"]. Modes are preserved and documented, not
compiled — ui tokens compile emits the base mode only.
Avoid: theme (that names the product's switching mechanism, e.g. data-theme, not the
token concept), variant (reserved for component variants), dark-mode override
Evidence ladder:
A best→last-resort ordering of evidence sources for one decision, where each rung is tried
before the one below and the rung used is reported. The house idiom — delivery-assets.md
(inline-SVG → raster → sprite → crop), motion-craft.md (T1 CSS → T6 WebGL), extract.md
§3c (SOURCE-grade → GUESS-grade → unverified). A rung ships only with its count over the
real corpus.
Avoid: fallback chain, priority list, decision tree
Parallel hardcoded set:
The token anti-pattern where each theme redeclares its own primitives instead of a second
semantic layer aliasing one shared set (knowledge/token-taxonomy.md:121). A finding to be
recorded at onboarding and normalised — never silently ingested.
Avoid: theme duplication, hardcoded dark mode
Seal:
The manifest's hash over the compiled DS (compiledHash + registryHash + generation).
A sanctioned command that mutates a sealed artifact must reseal — recompute the hashes,
bump the generation, append the changelog — or the next load reports DS_TAMPERED.
Avoid: lock, signature, checksum
Role recognition:
Understanding which of a project's own tokens plays which canonical role (background, primary,
danger…) WITHOUT renaming it — an annotation, not a rewrite. surface-content stays
surface-content; the tool records that it plays background. Stored in
$extensions["design-os.role"], baked at import, owner-editable.
Avoid: mapping, conversion, normalization (all imply renaming — forbidden)
Family role: The intent/purpose a token serves — background, foreground, card, primary, secondary, muted, accent, border, input, ring, destructive, success, warning, info. One axis of role recognition. Avoid: semantic role (too broad — a token has a family AND a position)
Surface position:
The other recognition axis — whether a token is a surface (bg) or the text on it (fg/text).
badge-danger-bg = danger family, bg position; badge-danger-text = danger family, fg position.
The paired axis ui ds a11y checks for contrast.
Avoid: foreground/background (name the axis, not one value)
Gap (design-system):
A canonical role with no token recognized for it — surfaced as a help-grow list, never
auto-filled. The user adds it in their own name via ui ds change-token.
Avoid: missing token, hole
Tenant section:
An embedded interactive block (scrub cinema, parallax, exploded-view, canvas hero) that lives inside a
larger page it does not own. It READS the host only through its own bounding box and WRITES only inside
its own subtree — zero global writes (no window.scrollTo, document-height mutation, :root writes,
position:fixed, or private ticker). The class-level law for all embeddable motion sections.
Avoid: widget, embed, island (island implies iframe/JS isolation — a tenant is same-DOM)
Scrub section:
The first Tenant section — a scroll-scrubbed camera cinema emitted as one section among many, pinned by
CSS position:sticky (the browser owns the pin), progress derived from getBoundingClientRect, media
driven frame-by-frame. NOT the standalone scrub page (that architecture assumes it owns the document).
Avoid: scrub page, scroll-world page (reserve those for the standalone deliverable)
tenant-lint:
The linter shipped with the Tenant-section emitter that fails any emitted section containing a global
write, AND fails a host layout that puts overflow/transform/filter/contain on a sticky-pin
ancestor (silently kills position:sticky). Emitter + linter, same commit.
Avoid: embed-check, section-validator
Plate:
A generated image placed BEHIND content to light a surface, never to carry it — the surface
carries the text. Lives on its own layer (a masked pseudo-element) rather than as the host
element's background-image, because a background drags the host's rectangle along with it and
any image whose ground is not perfectly black then shows its bounding box. A plate is admitted
only where the image IS the evidence for that surface's claim.
Avoid: background image (that names the mechanism a plate deliberately avoids), hero image,
texture, decoration
Refutation check:
A clause inside a rule that can only ever REMOVE a finding, and only on positive evidence.
It answers "no" when the facts show the finding is wrong; on every path where the evidence
is missing or unusable it answers "yes" and the finding stands. Distinct from a needs
entry, which states what a rule REQUIRES to run at all — promoting refutation evidence into
needs turns the rule NOT-EVALUATED wherever that evidence is absent, which silences
findings under cover of a coverage change.
Avoid: guard, filter, exemption (all three read as symmetric; the asymmetry is the point)
Product Atlas:
The canonical artifact ui product-context compile derives from capture receipts: it embeds
every normalized receipt and its digest, and resolves each product-truth and Flow field from
them. Derived and rebuildable — discard it and recompile from the receipts, which stay the
authoritative inputs. It carries no projection, no findings and no verdict, and its bytes never
depend on argv order, a requested projection, or the clock.
Avoid: product map, so
3AEC
urce of truth, product model (all three read as authority — the Atlas
is derived), strategy, qualification record (that names a different, existing contract)
Guidelines pack:
The folder ui ds guidelines build compiles from the sealed design system: facts in sealed generated
blocks (names written as explicit token: / component: / term: spans) plus scenario slots the host
answers. It states how a library is USED, which the tokens and the registry cannot. Derived and
rebuildable; the host's answers are the only part a rebuild carries forward.
Avoid: style guide, design docs, rulebook (all three read as hand-written and as authority — the pack
is compiled and every rule cites its source)
Figma guidelines bundle:
The export of a guidelines pack for Figma's "Manage guidelines" upload: figma-guidelines/ (a handful
of .md/.txt/.json files under Figma's size cap, no component inventory, apps merged) plus an
UPLOAD.md beside it. Upload is manual; the bundle is a copy of the pack, never its source.
Avoid: Figma upload, Figma export (name the artifact, not the act), canonical pack (that is the
untrimmed source the bundle is cut from)
Scenario slot:
A > QUESTION(<id>) line in the pack, seeded from evidence, that the host answers with Do:,
Don't: and Why: lines. Open, partial or filled; its id comes from the evidence, so a rebuild
keeps the answer attached, and an answer whose slot is gone is parked, never dropped.
Avoid: TODO, placeholder, prompt (a slot is checked and counted; none of the three is)
Ruling tier:
Where an owner ruling goes in the pack: A (global, design categories → rulings.md), A-other (global,
any other category → "Other library-wide rulings"), B (app-scoped → apps/<app>.md), C (process →
excluded, counted). Superseded rulings are never emitted. A tier is a placement decision, not a
priority.
Avoid: priority, importance level, severity (a tier says where a ruling lives, not how much it matters)
Design reuse ladder:
The fixed order of questions an agent asks per slot before building on an existing design system: need
it → DS template → registered component → variant → composition → tokens → new component (ds-new:).
It stops at the first rung that holds, and ranks what the design system declares above nearby product
code. Knowledge in knowledge/design-reuse-ladder.md; the answers live in a reuse plan.
Avoid: reuse checklist, component hierarchy, atomic design levels (all three read as a taxonomy of
components — the ladder is an order of decisions for one slot)
Reuse plan:
The Markdown file (reuse-plan.md) an agent writes before markup: per screen a Pattern: line and a
Slot / Rung / Use / Reason table. ui reuse-plan check validates its names against the registry and
tokens and lists the ds-new: items for the owner. Written first, checked, then built from.
Avoid: component list, build plan, bill of materials (a reuse plan records a choice and its rung per
slot, not just what is used)