Token consumers

KDS Token Consumers Registry

*ource of truth*for every Koder Stack component consuming design tokens emitted by tools/design-gen → dist/tokens/ + live kds.koder.dev/api/v1/tokens.json.

Opened: 20260524 (ticket meta/docs/stack#130, k~~evolve design~~gen plan-only round)

Why this registry exists

The KDS tokens.json/tokens.* artifacts are consumed by multiple downstream components. Silent drift between a consumer's pinned version and KDS canonical risks:

Compile failures when a token gets renamed/removed
Visual regressions when a token's value shifts
Cross-product inconsistency when one consumer is months behind

This registry tracks every consumer + their format + version pin so drift is visible.

Current consumers (20260524)

Component	Format	Source	Version pin	Last sync	Owner
`engines/sdk/koder_kit`	Dart consts	`dist/tokens/tokens.dart` + `lib/src/motion/motion_tokens.dart`	rolling-latest	20260524	KDS team
`engines/sdk/koder_web_kit`	CSS vars	`dist/tokens/tokens.css` (vendored into `assets/css/`)	rolling-latest	20260522	KDS team
`engines/sdk/koder-design-lsp`	runtime fetch	`kds.koder.dev/api/v1/tokens.json` (24h TTL cache)	runtime	n/a (live)	LSP team
`Figma sync (ticket #157)`	JSON export	`dist/tokens/tokens.json`	snapshot per deploy	deploy-time	Figma sync owner
`dist/tokens/tokens.scss`	SCSS vars	direct copy	rolling	n/a (build artifact)	KDS team
`dist/tokens/tokens.kt`	Kotlin consts	direct copy	rolling	n/a (build artifact)	KDS team
`dist/tokens/tokens.swift`	Swift consts	direct copy	rolling	n/a (build artifact)	KDS team
`dist/tokens/tokens.d.ts`	TypeScript types	direct copy	rolling	n/a (build artifact)	KDS team

Planned consumers (tickets open)

Component	Format	Tracking ticket	Status
Rust components (kodec, klink, kdb-next admin UI)	`dist/tokens/tokens.rs`	`tools/design-gen#103`	pending
AI agents (live query)	MCP `tools/list_tokens`	`tools/design-gen#117`	pending (RFC needed)

Adding a new consumer

When adding a new component that consumes KDS tokens:

*ick the right format*— DartTSetc. for compiled languages;
live /api/v1/tokens.json for runtime introspection (LSPs, agents); tokens.json snapshot for tools that need an immutable artifact per release (Figma sync pattern).
*hoose a pin model*
- *olling-latest*— consumer rebuilds against current
  dist/tokens/ on every CI run; cleanest for in-monorepo components
- *napshot per deploy*— consumer pins to a specific commit's
  tokens.json; needed for outofmonorepo or vendored consumers
- *untime*— consumer fetches live from kds.koder.dev/api/v1/
  with TTL cache; right model for LSPs, AI agents, dashboards
*dd a row to this registry*with all 6 columns filled
*ross-link*in your component's README and koder.toml
If you need a format not yet emitted (e.g. Python), open a ticket
in tools/design-gen#10X requesting the new exporter

Drift policy

*olling consumers*— drift impossible; CI fails on rename/removal
*napshot consumers*— pin should not exceed 30 days behind
canonical (alertsdashboard TBD per `toolsdesign-gen#108` companion)
*untime consumers*— TTL ≤ 24h; cache-hit metrics tracked per
engines/sdk/koder-design-lsp#004

meta/docs/stack/specs/themes/verge.kmd — token vocabulary
meta/docs/stack/specs/themes/ui-style.kmd — preset variations
tools/design-gen/internal/tokens/extract.go — emitter
meta/docs/stack#129 — KDS public API spec (covers /api/v1/tokens.json)
tools/design-gen#103 — Rust exporter
tools/design-gen#108 — Cache-Control headers
tools/design-gen#117 — MCP server (alternative live query path)