Migration guides

tools specs/tools/migration-guides.kmd

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.

When this spec applies

Primary triggers

All triggers

Spec — Migration guides

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

FamilyURL patternExample
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:

SectionContents
Why migrateSelf-hosted, full theme control, multi-preset, no Google dependency
Token mappingMaterial token name → Koder token name (lookup table)
Component mappingMaterial component (e.g., MaterialButton) → Koder equivalent (KoderButton)
Breaking differencesToken-level deltas (e.g., Koder ditches Material's 13-tone palette for HCT-derived 18-role)
Per-platform code samplesFlutter, Web, Android (Compose), iOS (SwiftUI native) — same swap pattern
Stepwise upgrade1) Replace token import 2) Replace component imports 3) Adjust theme builder seed
Known gapsWhat Material does that Koder doesn't yet (e.g., Material variable fonts behavior)

R2 — Token mapping table (Material → Koder)

Excerpt:

Material tokenKoder tokenNotes
md.sys.color.primary--kds-color-primary1:1
md.sys.color.on-primary--kds-color-on-primary1:1
md.sys.color.primary-container--kds-color-primary-container1:1
md.sys.color.primary-fixed--kds-color-primary (Koder doesn't model fixed)Use primary
md.sys.elevation.level0..5--kds-elevation-0..5Tonal recipe differs; see elevation.kmd § R3
md.sys.typescale.display-large.font--kds-font-displayMaterial 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/*.kmd git diff between the two tags, then:

  1. Detects added / removed / modified specs
  2. For each modified spec, surfaces the rules that changed (R1-Rn diff)
  3. Emits breaking-change callouts where spec text matches patterns (e.g., BREAKING:, ❌ Forbidden:)
  4. Renders a structured Markdown page with anchors per category

Example page sections:

  • Summary (1 paragraph)
  • Added (new specs, new R rules)
  • Changed (modified R rules, with diff highlight)
  • Deprecated (rules marked deprecated; removal target)
  • Removed (specs deleted between versions)
  • Code mod recipes (per-language snippets when token names change)

R4 — Output format

Both guide families render via design-gen kind migrate (already present at tools/design-gen/internal/kinds/migrate.go).

Each guide:

  • Front matter: title, source, target, generated_at
  • Body: structured Markdown sections
  • Anchors per change item (#change-md-button-tonal-bg) for linking from release notes and migration tools

R5 — Material guide refresh policy

Material → Koder guide refreshed:

  • On every Material version bump (Material 3 → Material 4, etc.)
  • On every Koder Design major-version that changes token mapping
  • Owner-curated; not auto-generated (Material's own changes don't trigger ours)

R6 — Linked from release notes

Each Koder Design release in tools/blog-changelog-index.kmd links to the auto-generated migration guide:

v0.7.0  →  v0.7.0 release notes  ·  Migrate from v0.6.0

R7 — Accessibility

  • Code snippets have language label + copy button
  • Tables are real <table> semantic elements with proper headers
  • Anchored sections support deep-link with focus visible on jump

R8 — Forbidden patterns

  • ❌ Manually hand-editing auto-generated version-to-version guides (re-run the generator instead)
  • ❌ Treating Material → Koder as a 1:1 token rename (mention philosophical differences: 18-role vs 13-tone, presets vs Material You, etc.)
  • ❌ Omitting per-platform code samples (Flutter / Web / Android / iOS — all four)
  • ❌ Hiding the Material guide behind login (open access; it's a conversion-funnel doc)
  • tools/blog-changelog-index.kmd — release notes link out to guides
  • themes/*.kmd — diff sources for version-to-version generation
  • releases/packaging.kmd — release asset cross-link
  • Generator code: tools/design-gen/internal/kinds/migrate.{go,templ}

References