# Token reference and metrics

Inspect every token and build spacing, breakpoints and fluid typography explicitly.

## One source contract
The contract currently contains 258 nodes including aliases, not 258 independent visual promises. token-specs.json declares types and meanings; tokens.json supplies the default definition. TypeScript contracts and CSS are generated from those files. Generation checks reject drift, missing definitions and CSS-variable name collisions.

Each node is classified by a runtime source reference, an alias dependent or a documented authoring use. Static linkage is not proof that a React component or every state executes correctly.

## Semantic coverage
The token system includes six complete color families, thirteen typography roles with family/size/weight/line/tracking fields, spacing, control geometry, icons, avatars, sliders/switches, feedback sizes, overlays, borders, elevation, layering, focus, opacity and motion. Use meaning-bearing roles rather than raw color constants.

## References and live values
compileThemeCSS and themeBindings redeclare the whole contract on a theme boundary, including alias var() expressions. A base font or size change on that boundary updates dependent role tokens. A raw descendant override without a new complete boundary cannot recompute an inherited alias.

resolveTheme returns concrete values. themeVariables applied to that result is deliberately a resolved snapshot, useful for non-CSS integrations. It is not the live-binding form.

## Authoring helpers
createSpacing accepts one to four finite scale factors or auto. fluidType emits a validated clamp expression. createBreakpoints supplies up/down/between/only/not helpers and ordered distinct thresholds. createTransition validates timing values and property names.

The sheet compiler accepts custom named fixed breakpoint maps. Changing a CSS custom property does not change already compiled media-query thresholds or the bundled layout utility scale.

## Migration and verification
Existing full theme JSON files with the earlier 99 nodes must be explicitly completed against the current default contract, then re-audited. completeTheme takes a patch without schemaVersion, not an arbitrary complete JSON document. Regenerate semantic palettes after migrating older custom colors and review visual changes.

Machine-readable token definitions and theme capabilities are available independently of JavaScript at /api/tokens.json and /api/theme-capabilities.json. No full DTCG conformance or accessibility certification is implied.