Rental-operations-platform/docs/TOKEN_IMPLEMENTATION_v1.0.md

Phase 11 Token Implementation

Authority and flow

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

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.