Spec — Design kit export

Facet Tool of Koder Design. Material parity: https://m3.material.io/develop/figma.

URL: https://kds.koder.dev/{locale}/tools/design-kits/

Target formats

R1 — Source of truth

Code is the source of truth — designs derive from code, never the reverse. Export pipeline:

specs/themes/*.kmd  →  design-gen  →  dist/tokens/  →  per-format adapter  →  .json / .sketch / .xd / .fig

Token names match the --kds-* CSS variable names exactly — no divergence (e.g., color.primary not colorPrimary).

R2 — Figma Variables JSON

Schema follows Figma's Variables import format (docs.figma.com/design-tokens-spec):

{
  "version": "1.0.0",
  "collections": {
    "Colors (Light)": {
      "primary": { "$type": "color", "$value": "#6750A4" },
      "on-primary": { "$type": "color", "$value": "#FFFFFF" },
      ...
    },
    "Colors (Dark)": {
      "primary": { "$type": "color", "$value": "#D0BCFF" },
      ...
    },
    "Typography": {
      "display-large.font-family": { "$type": "string", "$value": "Koder Sans" },
      "display-large.font-size": { "$type": "number", "$value": 57 },
      "display-large.line-height": { "$type": "number", "$value": 64 },
      "display-large.weight": { "$type": "number", "$value": 400 },
      ...
    },
    "Spacing": { "0": 0, "4": 4, "8": 8, "12": 12, "16": 16, "24": 24, "32": 32 },
    "Shape": { "0": 0, "4": 4, "8": 8, "12": 12, "16": 16, "28": 28, "full": 999 },
    "Elevation": { "0": "...", "1": "...", "2": "...", "3": "..." }
  }
}

R3 — Per-preset variant

Each design tool format ships ONE file per preset (material3.fig, ios_cupertino.fig, gnome.fig, etc.) — not a single multi-preset library (Figma doesn't multiplex well).

User picks preset on the kit page; downloads the matching file.

R4 — Component library (Figma only)

Beyond raw tokens, ship a .fig library with Components for the canonical wave 1 + wave 2 components:

• Buttons (7 variants)
• Cards
• Text fields
• Dialogs
• Banners / Snackbars / Tooltips
• Navigation bar / drawer / rail
• Lists / Menus / Chips / Tabs

Each Figma Component uses Variants properties matching the spec's R-rules (e.g., state=hover, size=small/default/large). Tokens applied via Figma Variables; updating a token in code + regenerating regenerates the library.

Sketch / XD ship only the styles + colors — components on those platforms are out of scope for v1 (open ticket if demand).

R5 — Versioning

Each export carries the source version:

• Filename pattern: koder-design-{preset}-{version}.{ext} (e.g., koder-design-material3-v1.4.0.fig)
• Internal metadata frame in Figma includes kds-version string
• Old versions remain downloadable at kds.koder.dev/tools/design-kits/archive/

R6 — Update flow

Single button on the page: "Regenerate latest". Runs:

1. tools/design-gen make tokens (rebuilds all token files)
2. Per-format adapters convert tokens → tool-specific format
3. Uploads regenerated files to dist/tokens/design-kits/
4. Deploy ships them to kds.koder.dev

Adapters live at tools/design-gen/internal/exporters/:

• figma.go → Variables JSON + .fig (via Figma REST API)
• sketch.go → .sketch (via official Sketch CLI)
• xd.go → .xd (via XD plugin SDK, run in CI container)

Note: .fig / .sketch / .xd require the respective tool CLIs; fallback to raw JSON (Figma) / spec.txt (Sketch / XD) when CLI is unavailable.

R7 — Downloads page

┌─────────────────────────────────────────────────────┐
│  Koder Design Kit · v1.4.0                          │
│ ──────────────────────────────────────────────────  │
│  Preset:  [Material 3 ▾]                            │
│                                                      │
│  Figma                                               │
│   Library file (.fig)        [Download 8 MB]        │
│   Variables JSON             [Download 24 KB]       │
│                                                      │
│  Sketch                                              │
│   Library (.sketch)          [Download 6 MB]        │
│                                                      │
│  Adobe XD                                            │
│   UI Kit (.xd)               [Download 5 MB]        │
│                                                      │
│  Universal                                           │
│   Style Dictionary JSON      [Download 32 KB]       │
│ ──────────────────────────────────────────────────  │
│  Archive · Older versions                            │
└─────────────────────────────────────────────────────┘

R8 — Accessibility

• Download buttons: full label including file format + size
• Preset dropdown follows menus.kmd exposed-dropdown pattern
• Generation log (when regenerating) live-region announces progress

R9 — Forbidden patterns

• ❌ Design tool is the source of truth (code is canonical)
• ❌ Token rename drift between code and design kit
• ❌ Hand-edited .fig / .sketch files (must be regenerated by adapters)
• ❌ Per-component library covering > 24 components (maintenance burden outpaces value — keep to canonical wave 1+2 + most-used cluster 5/6)
• ❌ Sketch / XD components for v1 (cap scope; revisit per demand)

Cross-link

• themes/color-roles.kmd / typography.kmd / shape.kmd / elevation.kmd — token source schemas
• tools/theme-builder.kmd — sibling tool exporting to same formats
• releases/packaging.kmd — kit files ship alongside binary releases

Implementation tracking

Adapters are non-trivial; tracked separately:

• projects/koder-stack#XXX — tools/design-gen/internal/exporters/
• This spec is the contract; impl conforms to it.