Migration — M3 baseline → M3 Expressive uplift

tools specs/tools/migration-m3-expressive-uplift.kmd

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.

When this spec applies

Primary triggers

All triggers

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-* / motion-effect-* (spring)Additive
Tween-based animations (Flutter Tween)Spring-based (SpringSimulation) preferred when gesturalAdditive (legacy works)
Decay linear (gesture release)Spring decay (motion-spatial-default)Recommended migration

Shape (shape-library)

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

Components

AntesDepoisBreaking?
Bottom App Bar (#049.25)Docked Toolbar (#068) — bottom app bar marked deprecated-in-expressiveSoft deprecation (retro-compat)
Single-style button groups (#049.21-24)Button groups Expressive (#069) com 5 sizes XS-XL + hover/press scale + shape morphAdditive (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 inertiaAdditive
Circular spinner everywhere (#049.42)Loading indicator (#065) for <5s + Progress indicators for ≥5sRefactoring needed (audit usage)

Typography

AntesDepoisBreaking?
15 type roles (display/headline/title/body/label × small/medium/large)Same + 15 emphasized roles parallel (#070 R9)Additive
Single weight per roleOptional emphasized weight delta (+100/+200)Additive (per text node)

Foundations

AntesDepoisBreaking?
Implicit emphasis decisions per surfaceFormal emphasis ladder (#071 R1) with 5 levels × 5 vectorsAdditive (guides decisions)

Adaptive

AntesDepoisBreaking?
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:

  1. Audit usages of deprecated patterns (bottom app bar, speed-dial).
  2. Suggest replacements (interactive prompt).
  3. 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

  • T1 Tabela R-uplift.1 cobre todos os umbrella sub-tickets fechados.
  • T2 Estratégia incremental (R-uplift.2): per-component opt-in works.
  • T3 Codemod placeholder (R-uplift.3): documented as future; no impl required.
  • T4 Rendering (R-uplift.4): design-gen migrate kind handles 3rd lane.
  • Base: migration-guides.kmd (#049.58)
  • Umbrella source: #062
  • Each row's source: linked tickets (#063 motion, #064 shape, #065 loading, etc.)

References