KDS Token Consumers Registry

Source 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: 2026-05-24 (ticket meta/docs/stack#130, k-evolve design-gen plan-only round)

Install via npm (design-gen#154 / HUB#180)

Tokens are published as @koder/design-tokens to the self-hosted Koder Hub npm registry (live since 2026-05-28; first version 0.1.0):

# .npmrc (project or ~/.npmrc)
@koder:registry=https://hub.koder.dev/npm/
//hub.koder.dev/npm/:_authToken=<publish-key>   # only needed to publish

npm install @koder/design-tokens

The package bundles tokens.{json,css,scss,d.ts,dart,rs,kt,swift} + README (main: tokens.json, types: tokens.d.ts, style: tokens.css). Publish a new version: make tokens-publish VERSION=x.y.z in tools/design-gen (needs KODER_HUB_PUBLISH_KEY; emits from dist/tokens/, so run after make gen). The live kds.koder.dev/api/v1/tokens.json remains the no-install / latest path.

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 (2026-05-24)

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 2026-05-24 KDS team
engines/sdk/koder_web_kit CSS vars dist/tokens/tokens.css (vendored into assets/css/) rolling-latest 2026-05-22 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)
engines/lang/kvg (KVG format — themable vector assets) color roles + spring tokens, bound by name from the token set (tokens.json / tokens.dart / tokens.css) engines/lang/kvg#066 (+#067) pending — RFC accepted (KVG RFC-003, 2026-05-27); activates when #066 (theming) ships on the Core renderer. KVG mirrors Verge's semantic role names 1:1; audit pins KVG roles ⊆ Verge roles.

Adding a new consumer

When adding a new component that consumes KDS tokens:

  1. Pick 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).

  2. Choose a pin model:
    • rolling-latest — consumer rebuilds against current

      dist/tokens/ on every CI run; cleanest for in-monorepo components

    • snapshot per deploy — consumer pins to a specific commit's

      tokens.json; needed for out-of-monorepo or vendored consumers

    • runtime — consumer fetches live from kds.koder.dev/api/v1/

      with TTL cache; right model for LSPs, AI agents, dashboards

  3. Add a row to this registry with all 6 columns filled
  4. Cross-link in your component's README and koder.toml
  5. 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

  • Rolling consumers — drift impossible; CI fails on rename/removal
  • Snapshot consumers — pin should not exceed 30 days behind

    canonical (alertsdashboard TBD per `toolsdesign-gen#108` companion)

  • Runtime consumers — TTL ≤ 24h; cache-hit metrics tracked per

    engines/sdk/koder-design-lsp#004

Related specs / tickets

  • 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)