# Phase 11 Token Implementation

## Authority and flow

The immutable Phase 9 files remain the raw and semantic source authority:

```text
src/contracts/phase9/design-tokens.json
  -> src/styles/tokens.css
  -> src/styles/component-tokens.css
  -> component CSS Modules and global styles
```

`src/styles/tokens.css` remains byte-identical to `contracts/phase9/tokens/semantic-tokens_v1.0.css`. Phase 11 does not rename or edit those variables.

## Phase 11 additions

`src/styles/component-tokens.css` adds documented component-facing roles required by the Phase 11 scope:

- page, primary, elevated, muted, and strong surfaces;
- primary, secondary, subdued, and inverse text;
- standard and strong borders;
- primary, conversion, danger, link, and focus roles;
- success, warning, error, and information states;
- overlay, disabled, selection, skeleton, and shadow roles;
- container, gutter, section spacing, header offset, and layer roles;
- display, heading, body, label, caption, line-height, and tracking roles.

These are aliases over approved Phase 9 values. Status roles use the approved raw status ramps because Phase 9 did not expose complete semantic status aliases. This extension is additive and does not mutate the historical contract.

## Consumption rules

1. Component and page CSS consume Phase 11 component-facing tokens.
2. Raw palette variables are allowed only in `tokens.css` and `component-tokens.css`.
3. Literal color functions and hexadecimal values are prohibited outside token declaration files.
4. Orange remains reserved for conversion emphasis and focus where approved.
5. Physical directional properties remain prohibited.
6. Breakpoint literals remain the approved `768px` and `1120px` values because CSS custom properties cannot be used in media-query conditions.
7. Shadows, timing, radius, spacing, typography, and layout roles are centralized rather than repeated through components.

## Automated enforcement

- `scripts/validate-tokens.mjs` verifies the immutable Phase 9 token source and detects raw color values.
- `scripts/validate-phase11-foundation.mjs` verifies required Phase 11 roles and rejects raw palette consumption or literal colors in component styles.
- `scripts/validate-css-logical.mjs` rejects physical directional CSS.