Migration guides
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.
Facet Tool 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 |
|---|---|---|
| Material → Koder | /migrate/material/{version}/ |
/migrate/material/m3/ |
| Koder → Koder | /migrate/koder/{from}/{to}/ |
/migrate/koder/v0.6.0/v0.7.0/ |
Material guide is hand-curated (one big page). Version-to-version guides are auto-generated by design-gen make migrate.
R1 — Material → Koder guide
Single page at /migrate/material/m3/ covering:
| Section | Contents |
|---|---|
| Why migrate | Self-hosted, full theme control, multi-preset, 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 | Token-level deltas (e.g., Koder ditches Material's 13-tone palette for HCT-derived 18-role) |
| 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 — Version-to-version 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