AGENTS.md

1# `_schema/` — design-system contracts
2 
3This directory codifies the structural contracts for design systems.
4`tokens.schema.ts` re-exports the token contract that every tokenized brand under
5`design-systems/<brand>/` must satisfy. The canonical runtime copy lives in
6`packages/contracts/src/design-systems/token-schema.ts` so daemon importers and
7repo guards consume one schema. `manifest.schema.ts` is the
8project contract for Design System Project packages. Every bundled catalog
9entry now ships `manifest.json`, `DESIGN.md`, and `tokens.css`; the daemon keeps
10`DESIGN.md`-only discovery solely as a compatibility path for older or
11user-installed folders.
12 
13```
14_schema/
15├── manifest.schema.ts ← project manifest schema (TS, machine-enforced when present)
16├── tokens.schema.ts   ← token schema re-export (TS, machine-enforced)
17├── defaults.css       ← A2 fallback values (CSS, human reference)
18└── AGENTS.md          ← this file
19```
20 
21The TypeScript schemas are the source of truth. `defaults.css` is a
22human-readable mirror of the A2 `fallback` fields in the token schema
23and exists so that reviewers can scan real CSS without parsing a TS
24array — drift between the two is enforced by the `design-system: A2
25defaults parity` guard. Manifest shape is enforced by
26`scripts/check-design-system-manifests.ts` for any
27`design-systems/<brand>/manifest.json` that exists.
28 
29## Project manifest contract
30 
31Design System Project folders use fixed v1 file names:
32 
33- `manifest.json` — machine-readable project entry.
34- `DESIGN.md` — canonical design prose.
35- `tokens.css` — canonical compiled tokens.
36- `design-tokens.json` — optional Design Tokens JSON derived from
37  `tokens.css` + `source/token-contract.report.json`.
38- `tailwind-v4.css` — optional Tailwind v4 `@theme` CSS derived from
39  `tokens.css`; it must not redefine source values independently.
40- `components.html` — optional standalone component fixture.
41- `assets/` — optional brand assets.
42- `preview/` — optional static preview pages.
43- `USAGE.md` — optional agent-facing package guide.
44- `components.manifest.json` — optional rebuildable cache derived from
45  `components.html` and `tokens.css`.
46- `fonts/` — optional webfont files.
47- `source/` — optional importer evidence (`scanned-files.json`,
48  `evidence.md`, `tokens.source.json`, `token-contract.report.json`,
49  and `snippets/INDEX.json`).
50 
51The manifest guard validates every bundled package through its `manifest.json`.
52When rich fields are declared, paths must be safe and present, JSON indexes
53must parse, and committed `components.manifest.json` files must match a fresh
54derivation from `components.html` plus `tokens.css`. These fields are also
55runtime inputs: catalog discovery consumes manifest metadata; prompt
56composition consumes usage, tokens, component information, import mode, craft
57bindings, and the manifest-derived pull index; package/static-file routes expose
58only declared preview and source files. Legacy `DESIGN.md`-only folders remain
59outside this manifest guard because they have no manifest to validate.
60 
61## Four layers, two questions
62 
63Every shared token answers two questions:
64 
651. **Who decides the value?** — the brand author (Layer A) or the
66   schema author (Layer B-slot, when the brand has no opinion).
672. **What happens if the brand omits it?** — required, fallback, or
68   alias.
69 
70The four layers fall out of those answers:
71 
72| Layer | Who decides | If omitted | Examples |
73| --- | --- | --- | --- |
74| **A1-identity** | brand | guard fails | `--bg`, `--fg`, `--accent`, `--font-display` |
75| **A1-structure** | brand | guard fails | type scale, `--container-max`, `--section-y-*` |
76| **A2** | brand (with fallback) | guard fails today; derive script fills tomorrow | `--motion-fast`, `--success`, `--space-4`, `--font-mono` |
77| **B-slot** | brand or schema-suggested alias | guard fails — brand must declare, either as `var(--sibling)` (collapsed) or independent value (richer) | `--fg-2 → var(--fg)`, `--surface-warm → var(--surface)` |
78 
79Brand-specific tokens that fall outside the shared schema are tracked
80as **C-extensions** in `BRAND_EXTENSIONS` (per-brand allowlist) or
81`BRAND_EXTENSION_PREFIXES` (global prefix allowlist for whole families
82like `--tag-bg-*`).
83 
84## Why A2 fails the guard today (and might not later)
85 
86A2 conceptually means "optional with fallback" — but artifacts are
87generated by agents pasting one brand's `:root` block into a single
88`<style>`. There is no global stylesheet that loads alongside the
89brand, so a missing `--motion-fast` resolves to nothing inside the
90artifact and any `transition: var(--motion-fast)` rule silently breaks.
91 
92Until a future derive script lands and inlines `defaults.css` values
93into every brand's `tokens.css`, the only safe contract is "every
94brand must declare every A2 token". The `design-system: A2 required
95tokens` guard enforces that strictly.
96 
97After the derive script ships, brand authors only need to write the
98A1 tokens (and any A2 they want to override); the script populates A2
99slots from `defaults.css`. The guard contract does not change — every
100final `tokens.css` still contains every A2 token — but the work
101shifts from human author to script.
102 
103## Why B-slot is required (and what the alias is for)
104 
105Same artifact-paste constraint applies to B-slot tokens. Shared
106components reference richer tiers via `var(--fg-2)`, `var(--meta)`,
107`var(--surface-warm)`, `var(--border-soft)` — if a brand omits the
108slot, those references resolve to nothing and the artifact silently
109breaks.
110 
111The `aliasTo` field on each B-slot entry is the **schema-suggested
112default**, not a runtime fallback. A brand with no opinion on the
113richer tier copies the alias verbatim into its `:root`:
114 
115```
116--fg-2: var(--fg);                /* default brand: 2-level fg */
117--surface-warm: var(--surface);   /* default brand: 2-level surface */
118```
119 
120A brand that does have the richer tier binds an independent value:
121 
122```
123--fg-2: #3d3d3a;                  /* kami brand: dark warm */
124--surface-warm: #e8e6dc;          /* kami brand: warm sand */
125```
126 
127Either form satisfies the `design-system: B-slot required tokens`
128guard. The pre-derive-script contract is identical to A2: every
129brand's `:root` declares every shared slot.
130 
131## C → B-slot → A2 promotion path
132 
133Brand-specific tokens start in `BRAND_EXTENSIONS[brand]`. They earn
134promotion when a second brand needs the same name:
135 
136```
137C-extension                    B-slot                       A2
138(one brand declares it)        (multiple brands declare,    (every brand declares
139                                some alias to a sibling)     with a sensible default)
140 
141kami: --leading-display    →   schema: --leading-display    →   schema: --leading-display
142                               aliasTo: var(--leading-tight)    fallback: 1.1
143```
144 
145Concrete promotion rules:
146 
1471. **C → B-slot** when **≥2 brands** declare a token of the same name
148   *and* there is a meaningful sibling to alias to for brands that
149   lack the richer tier. Move the entry from `BRAND_EXTENSIONS` to
150   `TOKEN_SCHEMA` with `layer: "B-slot"` and `aliasTo: "var(--sibling)"`.
1512. **C → A2** when **≥2 brands** declare a token of the same name
152   *and* a defensible cross-brand fallback exists (no aliasing
153   needed). Move to `TOKEN_SCHEMA` with `layer: "A2"` and a `fallback`,
154   then mirror the value in `defaults.css`.
1553. **B-slot → A2** when a B-slot starts being independently bound by
156   ≥2 brands (instead of aliasing). Replace `aliasTo` with `fallback`
157   and add a defaults.css declaration.
1584. **A2 → A1** is rare. It happens when the previously-defaultable
159   value turns out to be brand-determining — e.g. if a future brand
160   redefines `--motion-base` from 200ms to 50ms because its identity
161   is "instant", and that change ripples meaningfully through the
162   brand voice. Drop the `fallback` and reclassify.
163 
164Demotion (A → B → C) is not currently supported. A token that is
165genuinely no longer needed should be marked `@deprecated` in the
166schema for one release and then deleted from every brand's
167`tokens.css` in the same PR.
168 
169## When **not** to add a token
170 
171Schema growth has a cost — every new entry forces every bundled brand to
172declare or alias the new name when the derive script next runs.
173Resist adding tokens that are:
174 
175- **Component-internal**: a `.btn-primary` background offset that no
176  other component will ever read. Inline the value in the component
177  rule.
178- **One-off**: a single layout's hero crop ratio. Not a token.
179- **Speculative**: "we might want a `--motion-slow` someday." Add it
180  the first time a real interaction needs it, not before.
181- **Already expressible**: a `--accent-tint-50` that resolves to
182  `color-mix(in oklab, var(--accent), transparent 50%)`. Inline the
183  `color-mix(...)` call until ≥2 components need the same tint with
184  the same alpha, then promote to a token.
185 
186## Editing this directory
187 
188When you change the token schema:
189 
190- Run `pnpm guard` and confirm the bundled catalog still passes every
191  design-system sub-check.
192- If you added an A2 entry: also update `defaults.css` with the
193  matching declaration, byte-equivalent to the `fallback` field.
194- If you renamed a token: bump every brand's `tokens.css` and the
195  matching `components.html` `:root` paste in the same commit.
196  Otherwise the drift guard will fail.
197- If you removed a token from `TOKEN_SCHEMA` and the same name now
198  appears in only one brand: add it to that brand's
199  `BRAND_EXTENSIONS` entry so the unknown-token guard does not fail.
200 
201## Open questions for the future derive script
202 
203The checked-in schema and guards enforce the final token contract today, but
204the following authoring-automation questions are intentionally not answered:
205 
206- **How does the derive script source A1 values from `DESIGN.md`?**
207  Some sections (color palette, type scale) parse cleanly; others
208  (visual atmosphere, do's and don'ts) do not. A frontmatter or
209  fenced-block convention will likely emerge.
210- **What happens when a brand's `DESIGN.md` contradicts itself?**
211  e.g. accents listed as both cobalt and indigo. The derive script
212  will need a deterministic resolution (last-wins, manual override
213  flag, or hard fail).
214- **Are A2 fallback formulas stable when re-derived?** Bit-for-bit
215  reproducibility of the script's output is required so that running
216  the script twice on the same input does not churn the brand token files.
217 
218These remain future work for a change that introduces
219`scripts/derive-tokens-css.ts`; that script does not exist yet.
220