Migration — M3 baseline → M3 Expressive uplift

Strict extension to `tools/migration-guides.kmd` (#049.58). Adds 3rd migration lane: Koder M3 baseline → Koder M3 Expressive uplift. Documents what changed when umbrella #062 specs ratified; provides per-area migration tables (motion, shape, components, typography); outlines future codemod strategy.

Spec — Migration M3 baseline → M3 Expressive uplift

Strict extension to migration-guides.kmd (#049.58 ratified). Adds 3rd lane (Koder→Koder Expressive) alongside existing Material→Koder + Koder→Koder lanes.

R-uplift.1 — Mudanças por área

Tabela com what's deprecated vs what replaces, agrupada por área:

Motion (R9 spring tokens)

Antes (#049 baseline)	Depois (#063 ratified)	Breaking?
`motion-instant` / `motion-fast` / `motion-medium` / `motion-slow` / `motion-long` (duration)	Same (R1~~R2 retained) + new R9 `motion~~spatial* `/` motioneffect-*` (spring)	Additive
Tween-based animations (Flutter `Tween`)	Spring-based (`SpringSimulation`) preferred when gestural	Additive (legacy works)
Decay linear (gesture release)	Spring decay (`motion-spatial-default`)	Recommended migration

Shape (shape-library)

Antes	Depois	Breaking?
6~~level radius scale (`shape~~corner-{xs,sm,md,lg,xl,full}`)	Same (retained) + #064 35 named shapes library	Additive
Flat surfaces (radius only)	Optional shape morph between states (#064 R2)	Additive (opt-in per component)
Static `shape-corner-large` for FAB	FAB morphs to Toolbar / X / squircle on interaction states	Recommended migration

Components

Antes	Depois	Breaking?
Bottom App Bar (#049.25)	Docked Toolbar (#068) — bottom app bar marked `deprecated-in-expressive`	Soft deprecation (retro-compat)
Single~~style button groups (#049.21~~24)	Button groups Expressive (#069) com 5 sizes XS-XL + hover/press scale + shape morph	Additive (opt-in via `expressive: true`)
Speed-dial (legacy custom widgets)	FAB Menu (#067)	Replacement (audit needed)
Single hero carousel (#049.31)	Hero Expressive (#076) com shape morph + spring inertia	Additive
Circular spinner everywhere (#049.42)	Loading indicator (#065) for <5s + Progress indicators for ≥5s	Refactoring needed (audit usage)

Typography

Antes	Depois	Breaking?
15 type roles (displayheadlinetitlebodylabel × smallmediumlarge)	Same + 15 emphasized roles parallel (#070 R9)	Additive
Single weight per role	Optional emphasized weight delta (+100/+200)	Additive (per text node)

Foundations

Antes	Depois	Breaking?
Implicit emphasis decisions per surface	Formal emphasis ladder (#071 R1) with 5 levels × 5 vectors	Additive (guides decisions)

Adaptive

Antes	Depois	Breaking?
4 canonical layouts (#049.3)	Pane scaffolds APIs concretas (#074 R1-R6)	Additive

R-uplift.2 — Estratégia de adoção incremental

Per-component flagging:

# product koder.toml
[expressive]
enabled = true
components = ["buttons", "carousels", "fab"]  # opt-in per component

Or full opt-in:

[expressive]
enabled = true
all = true

Until owner opts in, products see baseline behavior. No breaking changes.

R-uplift.3 — Codemods (futuro)

Future koder-migrate expressive --component=<slug> tool would:

Audit usages of deprecated patterns (bottom app bar, speed-dial).
Suggest replacements (interactive prompt).
Apply mechanical refactors (Tween → spring() where safe).

Não shipável ainda (depende de AST parsing per surface). Manual migration via this doc + koder-spec-audit warnings.

R-uplift.4 — Renderização

Renderizada por design-gen existing migrate kind (per migration-guides.kmd R4); add a 3rd lane entry in design-gen configuration:

migration_lanes:
  - material-to-koder
  - koder-to-koder (intra-koder breaking)
  - koder-m3-baseline-to-expressive (this spec)

R-uplift.5 — Compliance check

Before declaring a product "M3 Expressive ready":

[ ] All emphasis levels (R-uplift.1 Foundations) explicit em design files.
[ ] Motion R9 spring tokens used where gestural.
[ ] Shape morph opt-in where applicable.
[ ] No bottom app bar in new screens (deprecated).
[ ] AAA contrast preserved per usability.kmd R4.1.
[ ] Reduced-motion contract honored per R4.2.

Audit script: koder-spec-audit expressive --product <slug> (futuro).

T-suite

*1*Tabela R~~uplift.1 cobre todos os umbrella sub~~tickets fechados.
*2*Estratégia incremental (R~~uplift.2): per~~component opt-in works.
*3*Codemod placeholder (R-uplift.3): documented as future; no impl required.
*4*Rendering (R~~uplift.4): design~~gen migrate kind handles 3rd lane.

Cross-link

Base: migration-guides.kmd (#049.58)
Umbrella source: #062
Each row's source: linked tickets (#063 motion, #064 shape, #065 loading, etc.)