ADR 0005 — Token group lifecycle

Status

Accepted, 2026-05-17.

Context

Adding a new token group (e.g. size-control in foundations, or color.bone in semantic) requires synchronized changes across multiple files: JSON definition, TypeScript types, resolver, emit pipeline, fixtures, and validation. Without a documented process, new additions risk partial implementation and broken builds.

Decision

Adding a new foundation group requires:

1. Add to packages/core/tokens/foundations.json — the JSON entries under the new group key
2. Extend FOUNDATION_GROUPS array in packages/core/src/types.ts
3. Extend FoundationsTokens interface in packages/core/src/types.ts
4. Update resolve.ts if cross-tier references will use the new group
5. Update __tests__/fixtures.ts so existing core tests still pass under the stricter interface
6. Verify pnpm build && pnpm test passes
7. Commit as feat(core): add <group-name> foundation tokens

Adding a new semantic group:

1. Add to packages/core/tokens/semantic.json in BOTH light and dark schemes
2. Extend SEMANTIC_GROUPS array if it's a new group key
3. Extend SemanticTier interface if needed
4. No changes needed in resolve.ts for aliases of existing foundation paths
5. Verify pnpm build emits the new CSS custom property
6. Commit as feat(core): add <group-name> semantic tokens

Adding component-specific (tier-3) tokens:

1. Add to packages/core/tokens/component-specific.json only
2. No types.ts changes needed — ComponentTier is Record<string, Record<string, string>> (generic)
3. No resolver changes needed — resolves to semantic via {path} syntax automatically
4. Verify pipeline emits --{component}-{key} CSS variable
5. Commit with the component implementation

Promotion criteria

A foundation seed should be promoted to semantic when:

• Two or more components need it (e.g. color.bone for Card and Avatar)
• Or it represents a system-wide role (e.g. size-control for all interactive elements)

A semantic token should be added when:

• The role is shared across multiple components
• It can be expressed without component-specific context

A tier-3 token should be used when:

• Only ONE component needs the value
• Or component requires precise per-variant control (e.g. button-background-accent-active)

Consequences

Positive:

• Clear checklist prevents partial implementations
• Architectural intent stays consistent
• CC and other AI agents can follow the process autonomously

Negative:

• Manual coordination across 4-5 files for foundation additions
• Pipeline does not auto-generate types from JSON (deliberate trade-off for IDE autocomplete)

Alternatives considered

• Auto-generated types from JSON — rejected; loses IDE autocomplete for specific group names
• Single generic Record<string, any> for all tiers — rejected; loses type safety
• Schema-driven generation — deferred; over-engineered for current velocity