Token Architecture and Ownership

Single authored source

The directory structure is fixed:

frontend/packages/materials/src/tokens/
|-- source/
|   |-- reference.tokens.json
|   |-- system.tokens.json
|   |-- component.tokens.json
|   `-- themes/
|       |-- enterprise-neutral.tokens.json
|       |-- legal-navy.tokens.json
|       |-- legal-amber.tokens.json
|       |-- legal-burgundy.tokens.json
|       |-- legal-jade.tokens.json
|       `-- legal-orange.tokens.json
`-- generated/
    |-- tokens.css
    |-- tokens.ts
    `-- tokens.schema.json

source/ is the only authored source.
Colors are authored in sRGB Hex; one generator deterministically emits OKLCH, CSS, TypeScript, and schema output.
generated/ is never edited by hand. The generator has a --check drift detection mode that fails closed in CI.
packages/components consumes tokens, packages/widgets composes patterns, and apps/* supplies product content.
All source files declare version: "1.2.0"; the generator asserts this value is consistent.

Four dependency layers

--ref-* -> --sys-* -> --cmp-* -> shadcn compatibility aliases

Layer	Responsibility	Consumer	Example
Reference	Raw ramps, type, spacing, radius, duration	System only	`--ref-space-4`
System	Surface, text, action, link, focus, status, navigation	Layout and components	`--sys-color-text-default`
Component	One component variant and state	Component internals	`--cmp-button-primary-bg-hover`
Compatibility	shadcn and Tailwind aliases	Existing components	`--primary`

Component names follow:

--cmp-{component}-{variant}-{property}-{state}

Compatibility mapping

Compatibility aliases point upstream:

/* Keep shadcn aliases as a leaf compatibility layer. */
--background: var(--sys-color-canvas);
--foreground: var(--sys-color-text-default);
--border: var(--sys-color-border-subtle);
--input: var(--sys-color-border-control);
--primary: var(--sys-color-action-primary-bg);
--primary-foreground: var(--sys-color-action-primary-fg);
--ring: var(--sys-color-focus-ring);

Never derive Link, Focus, Selection, or Navigation back from --primary.

Page redlines

No raw Hex, RGB, HSL, OKLCH, or brand gradients.
No direct --ref-* consumption.
No global CSS custom properties owned by a page.
No manual edits to generated tokens.
No !important used to conceal ownership or cascade defects.
No global token created for a single page.

Use Patch for optical corrections, Minor for compatible additions, and Major for deleted names, changed stable IDs, or changed interaction semantics.

Version semantics

Version	Appropriate change
Patch	Optical correction that preserves meaning and layout
Minor	Backward-compatible Token, Pattern slot, or Recipe addition
Major	Removed or renamed Token, changed stable ID, Shell region, or interaction semantics

A breaking change requires an impact matrix, migration path, accessibility result, and visual regression evidence. The Design Guardian decision must be recorded before the generated contract is released.