workbuddy_skills/open-design/design-systems/_schema/AGENTS.md

# `_schema/` — design-system contracts

This directory codifies the structural contracts for design systems.
`tokens.schema.ts` re-exports the token contract that every tokenized brand under
`design-systems/<brand>/` must satisfy. The canonical runtime copy lives in
`packages/contracts/src/design-systems/token-schema.ts` so daemon importers and
repo guards consume one schema. `manifest.schema.ts` is the
project contract for Design System Project packages. Every bundled catalog
entry now ships `manifest.json`, `DESIGN.md`, and `tokens.css`; the daemon keeps
`DESIGN.md`-only discovery solely as a compatibility path for older or
user-installed folders.

```
_schema/
├── manifest.schema.ts ← project manifest schema (TS, machine-enforced when present)
├── tokens.schema.ts   ← token schema re-export (TS, machine-enforced)
├── defaults.css       ← A2 fallback values (CSS, human reference)
└── AGENTS.md          ← this file
```

The TypeScript schemas are the source of truth. `defaults.css` is a
human-readable mirror of the A2 `fallback` fields in the token schema
and exists so that reviewers can scan real CSS without parsing a TS
array — drift between the two is enforced by the `design-system: A2
defaults parity` guard. Manifest shape is enforced by
`scripts/check-design-system-manifests.ts` for any
`design-systems/<brand>/manifest.json` that exists.

## Project manifest contract

Design System Project folders use fixed v1 file names:

- `manifest.json` — machine-readable project entry.
- `DESIGN.md` — canonical design prose.
- `tokens.css` — canonical compiled tokens.
- `design-tokens.json` — optional Design Tokens JSON derived from
  `tokens.css` + `source/token-contract.report.json`.
- `tailwind-v4.css` — optional Tailwind v4 `@theme` CSS derived from
  `tokens.css`; it must not redefine source values independently.
- `components.html` — optional standalone component fixture.
- `assets/` — optional brand assets.
- `preview/` — optional static preview pages.
- `USAGE.md` — optional agent-facing package guide.
- `components.manifest.json` — optional rebuildable cache derived from
  `components.html` and `tokens.css`.
- `fonts/` — optional webfont files.
- `source/` — optional importer evidence (`scanned-files.json`,
  `evidence.md`, `tokens.source.json`, `token-contract.report.json`,
  and `snippets/INDEX.json`).

The manifest guard validates every bundled package through its `manifest.json`.
When rich fields are declared, paths must be safe and present, JSON indexes
must parse, and committed `components.manifest.json` files must match a fresh
derivation from `components.html` plus `tokens.css`. These fields are also
runtime inputs: catalog discovery consumes manifest metadata; prompt
composition consumes usage, tokens, component information, import mode, craft
bindings, and the manifest-derived pull index; package/static-file routes expose
only declared preview and source files. Legacy `DESIGN.md`-only folders remain
outside this manifest guard because they have no manifest to validate.

## Four layers, two questions

Every shared token answers two questions:

1. **Who decides the value?** — the brand author (Layer A) or the
   schema author (Layer B-slot, when the brand has no opinion).
2. **What happens if the brand omits it?** — required, fallback, or
   alias.

The four layers fall out of those answers:

| Layer | Who decides | If omitted | Examples |
| --- | --- | --- | --- |
| **A1-identity** | brand | guard fails | `--bg`, `--fg`, `--accent`, `--font-display` |
| **A1-structure** | brand | guard fails | type scale, `--container-max`, `--section-y-*` |
| **A2** | brand (with fallback) | guard fails today; derive script fills tomorrow | `--motion-fast`, `--success`, `--space-4`, `--font-mono` |
| **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)` |

Brand-specific tokens that fall outside the shared schema are tracked
as **C-extensions** in `BRAND_EXTENSIONS` (per-brand allowlist) or
`BRAND_EXTENSION_PREFIXES` (global prefix allowlist for whole families
like `--tag-bg-*`).

## Why A2 fails the guard today (and might not later)

A2 conceptually means "optional with fallback" — but artifacts are
generated by agents pasting one brand's `:root` block into a single
`<style>`. There is no global stylesheet that loads alongside the
brand, so a missing `--motion-fast` resolves to nothing inside the
artifact and any `transition: var(--motion-fast)` rule silently breaks.

Until a future derive script lands and inlines `defaults.css` values
into every brand's `tokens.css`, the only safe contract is "every
brand must declare every A2 token". The `design-system: A2 required
tokens` guard enforces that strictly.

After the derive script ships, brand authors only need to write the
A1 tokens (and any A2 they want to override); the script populates A2
slots from `defaults.css`. The guard contract does not change — every
final `tokens.css` still contains every A2 token — but the work
shifts from human author to script.

## Why B-slot is required (and what the alias is for)

Same artifact-paste constraint applies to B-slot tokens. Shared
components reference richer tiers via `var(--fg-2)`, `var(--meta)`,
`var(--surface-warm)`, `var(--border-soft)` — if a brand omits the
slot, those references resolve to nothing and the artifact silently
breaks.

The `aliasTo` field on each B-slot entry is the **schema-suggested
default**, not a runtime fallback. A brand with no opinion on the
richer tier copies the alias verbatim into its `:root`:

```
--fg-2: var(--fg);                /* default brand: 2-level fg */
--surface-warm: var(--surface);   /* default brand: 2-level surface */
```

A brand that does have the richer tier binds an independent value:

```
--fg-2: #3d3d3a;                  /* kami brand: dark warm */
--surface-warm: #e8e6dc;          /* kami brand: warm sand */
```

Either form satisfies the `design-system: B-slot required tokens`
guard. The pre-derive-script contract is identical to A2: every
brand's `:root` declares every shared slot.

## C → B-slot → A2 promotion path

Brand-specific tokens start in `BRAND_EXTENSIONS[brand]`. They earn
promotion when a second brand needs the same name:

```
C-extension                    B-slot                       A2
(one brand declares it)        (multiple brands declare,    (every brand declares
                                some alias to a sibling)     with a sensible default)

kami: --leading-display    →   schema: --leading-display    →   schema: --leading-display
                               aliasTo: var(--leading-tight)    fallback: 1.1
```

Concrete promotion rules:

1. **C → B-slot** when **≥2 brands** declare a token of the same name
   *and* there is a meaningful sibling to alias to for brands that
   lack the richer tier. Move the entry from `BRAND_EXTENSIONS` to
   `TOKEN_SCHEMA` with `layer: "B-slot"` and `aliasTo: "var(--sibling)"`.
2. **C → A2** when **≥2 brands** declare a token of the same name
   *and* a defensible cross-brand fallback exists (no aliasing
   needed). Move to `TOKEN_SCHEMA` with `layer: "A2"` and a `fallback`,
   then mirror the value in `defaults.css`.
3. **B-slot → A2** when a B-slot starts being independently bound by
   ≥2 brands (instead of aliasing). Replace `aliasTo` with `fallback`
   and add a defaults.css declaration.
4. **A2 → A1** is rare. It happens when the previously-defaultable
   value turns out to be brand-determining — e.g. if a future brand
   redefines `--motion-base` from 200ms to 50ms because its identity
   is "instant", and that change ripples meaningfully through the
   brand voice. Drop the `fallback` and reclassify.

Demotion (A → B → C) is not currently supported. A token that is
genuinely no longer needed should be marked `@deprecated` in the
schema for one release and then deleted from every brand's
`tokens.css` in the same PR.

## When **not** to add a token

Schema growth has a cost — every new entry forces every bundled brand to
declare or alias the new name when the derive script next runs.
Resist adding tokens that are:

- **Component-internal**: a `.btn-primary` background offset that no
  other component will ever read. Inline the value in the component
  rule.
- **One-off**: a single layout's hero crop ratio. Not a token.
- **Speculative**: "we might want a `--motion-slow` someday." Add it
  the first time a real interaction needs it, not before.
- **Already expressible**: a `--accent-tint-50` that resolves to
  `color-mix(in oklab, var(--accent), transparent 50%)`. Inline the
  `color-mix(...)` call until ≥2 components need the same tint with
  the same alpha, then promote to a token.

## Editing this directory

When you change the token schema:

- Run `pnpm guard` and confirm the bundled catalog still passes every
  design-system sub-check.
- If you added an A2 entry: also update `defaults.css` with the
  matching declaration, byte-equivalent to the `fallback` field.
- If you renamed a token: bump every brand's `tokens.css` and the
  matching `components.html` `:root` paste in the same commit.
  Otherwise the drift guard will fail.
- If you removed a token from `TOKEN_SCHEMA` and the same name now
  appears in only one brand: add it to that brand's
  `BRAND_EXTENSIONS` entry so the unknown-token guard does not fail.

## Open questions for the future derive script

The checked-in schema and guards enforce the final token contract today, but
the following authoring-automation questions are intentionally not answered:

- **How does the derive script source A1 values from `DESIGN.md`?**
  Some sections (color palette, type scale) parse cleanly; others
  (visual atmosphere, do's and don'ts) do not. A frontmatter or
  fenced-block convention will likely emerge.
- **What happens when a brand's `DESIGN.md` contradicts itself?**
  e.g. accents listed as both cobalt and indigo. The derive script
  will need a deterministic resolution (last-wins, manual override
  flag, or hard fail).
- **Are A2 fallback formulas stable when re-derived?** Bit-for-bit
  reproducibility of the script's output is required so that running
  the script twice on the same input does not churn the brand token files.

These remain future work for a change that introduces
`scripts/derive-tokens-css.ts`; that script does not exist yet.