Migration guides

mandatory

Auto-generated migration guides covering both (a) Material → Koder Design adoption and (b) version-to-version Koder Design upgrades. Material parity (`/develop/migration`). Driven by `design-gen make migrate` infrastructure already in place for inter-version diffs.

Spec — Migration guides

Facet *ool*of Koder Design. Material parity: https://m3.material.io/develop/migration.

URL: https://kds.koder.dev/{locale}/migrate/{from}/{to}/

Two guide families

Family URL pattern Example
*aterial → Koder* /migrate/material/{version}/ /migrate/material/m3/
*oder → Koder* /migrate/koder/{from}/{to}/ /migrate/koder/v0.6.0/v0.7.0/

Material guide is *andcurated*(one big page). Versionto-version guides are *utogenerated*by `designgen make migrate`.

R1 — Material → Koder guide

Single page at /migrate/material/m3/ covering:

Section Contents
Why migrate Selfhosted, full theme control, multipreset, no Google dependency
Token mapping Material token name → Koder token name (lookup table)
Component mapping Material component (e.g., MaterialButton) → Koder equivalent (KoderButton)
Breaking differences Tokenlevel deltas (e.g., Koder ditches Material's 13tone palette for HCTderived 18role)
Per-platform code samples Flutter, Web, Android (Compose), iOS (SwiftUI native) — same swap pattern
Stepwise upgrade 1) Replace token import 2) Replace component imports 3) Adjust theme builder seed
Known gaps What Material does that Koder doesn't yet (e.g., Material variable fonts behavior)

R2 — Token mapping table (Material → Koder)

Excerpt:

Material token Koder token Notes
md.sys.color.primary --kds-color-primary 1:1
md.sys.color.on-primary --kds-color-on-primary 1:1
md.sys.color.primary-container --kds-color-primary-container 1:1
md.sys.color.primary-fixed --kds-color-primary (Koder doesn't model fixed) Use primary
md.sys.elevation.level0..5 --kds-elevation-0..5 Tonal recipe differs; see elevation.kmd § R3
md.sys.typescale.display-large.font --kds-font-display Material splits per-class; Koder uses 4 roles

Full table lives in meta/docs/stack/specs/tools/migration-mapping.kmd (separate file referenced by the guide — kept generated, not hand-edited).

R3 — Versiontoversion guides (auto-generated)

For each tag of Koder Design (e.g., v0.6.0 → v0.7.0):

  • design-gen make migrate MIGRATE_FROM=v0.6.0 MIGRATE_TO=v0.7.0
  • Produces /migrate/koder/v0.6.0/v0.7.0/ page

Generator walks `specs

Source: ../home/koder/dev/koder/meta/docs/stack/specs/tools/migration-guides.kmd