# §00.12 Migration Checklist

Use when substantially modifying any legacy module (any module
created before FvW v8.6.0 ratification on 2026-09-14).

Forward-only policy: §00.12.11 exempts legacy code from retroactive
compliance. Migration happens incrementally, as modules are touched.

A module moves through three states:

  LEGACY     — not yet modified since ratification
  MIGRATING  — partially compliant, recently touched
  COMPLIANT  — meets all §00.12 principles

## Before you start

- [ ] Is this a "substantial modification"? (new feature, refactor,
      new UI surface — not a bug fix or minor edit)
- [ ] If yes: this checklist applies.
- [ ] If no: proceed without the checklist.

## On modification — check these in order

### §00.12 P1 — Units
- [ ] Replace px with rem for font-size, spacing, sizing
- [ ] Exception: 1px borders, box-shadow offsets < 4px
- [ ] Verify: `node tools/check-px.mjs <files>`

### §00.12 P2 — Typography
- [ ] Use rem-based font sizes
- [ ] No px font-size in the touched files

### §00.12 P3 — Contrast
- [ ] Verify text contrast meets WCAG AA (4.5:1 body, 3:1 large)
- [ ] Tool: axe-core (once wired — currently Sprint 4 scope)

### §00.12 P4 — Motion
- [ ] Wrap animations in <MotionSafe> (or use usePrefersReducedMotion)
- [ ] Verify: motion is disabled when prefers-reduced-motion: reduce

### §00.12 P5 — Accessibility
- [ ] ARIA labels on interactive elements
- [ ] Keyboard handlers (onKeyDown) alongside onClick
- [ ] Semantic HTML (button, not div+role)

### §00.12 P6 — Responsiveness
- [ ] Test at 320px and 4K
- [ ] No horizontal overflow at narrow widths

### §00.12 P7 — Performance
- [ ] No new large dependencies without justification
- [ ] No render-blocking assets

### §00.12 P8 — Content
- [ ] Empty state present
- [ ] Error state present
- [ ] Loading state present

### §00.12 P9 — No legacy patterns
- [ ] No deprecated React lifecycles
- [ ] No inline styles in shared components

### §00.12 P10 — By construction
- [ ] The pre-commit hook (Husky) ran successfully
- [ ] CI is green on the pushed commit

## After you finish

- [ ] Update the module's status in `app-recipe/migration-status.yaml`
- [ ] Add a note to the migration log: `./scripts/log-migration.sh <module-id> MIGRATING`

## Exemptions (do not migrate even if touched)

- Existing 4,113 px lines (unless the touched block uses them)
- The legacy `src/styles.css` file
- Pre-ratification test fixtures

## Reference

- FvW v8.6.0 §00.12 World-Class UI Standard
- FvW v8.6.0 §00.12.11 Forward-only applicability
- [`docs/architecture/fvw-map.md`](../architecture/fvw-map.md)
- [`docs/INDEX.md`](../INDEX.md) — canonical doc map
- Validator: `gallery-pact/fvw/validator-v8.json`

## Status

This is the canonical migration template as of TASK-006 (2026-09-14).
Stored under `docs/migration/`. Authored by id 9 (vibecoder-standalone-mavis).