# Migration

## v1 → v2 (paper-and-ink) — already happened

The hard cutover from the v1 dark theme to the v2 paper-and-ink theme shipped in PR #1. v1 is gone — its tokens are no longer defined and the lint rejects them.

What changed:

- **Theme:** dark navy surfaces + blue accent → off-white paper + mint accent
- **Type:** Inter + Clash Display → Geist (sans) + Geist Mono + Instrument Serif italic (pull-quotes only)
- **Tokens:** `surface-*` / `fg-*` / `border-*` / `accent-soft` / `success` / etc. → `paper-*` / `ink-*` / `hairline-*` / `mint-*` / `ok` / etc.
- **Type scale:** `text-hero` / `text-heading` / `text-subheading` / `text-label` / `text-caption` → `text-h1` / `text-h4` / `text-body-lg` / `text-eyebrow` / `text-mono`
- **Shadows:** `shadow-raised` / `shadow-overlay` / `shadow-modal` → `.shadow-1` / `.shadow-2` / `.shadow-3`

The full mapping table is in `ANTI-PATTERNS.md` § "v1 dark-theme tokens (removed)".

## The codemod

`scripts/migrate-tokens.mjs` is kept in the repo. It rewrites v1 tokens to their v2 equivalents in `src/**.{tsx,ts,css}`.

```sh
node scripts/migrate-tokens.mjs            # dry-run (default)
node scripts/migrate-tokens.mjs --apply    # write changes
```

Use it if:

- You import or vendor third-party code that still uses v1 tokens.
- You're cherry-picking a commit from before the cutover.
- The lint flags v1 tokens in a file you didn't expect.

The codemod is structural — it doesn't fix visual fidelity. After running it, re-check the file in the browser. Some patterns (e.g. `bg-warn-soft`) collapse to a less expressive v2 equivalent (`bg-paper-2` + `text-warn`) and need a small manual touch-up.

## Future migrations

When the next theme bump happens:

1. Bump the `@theme` block in `src/index.css` — add new tokens alongside old.
2. Write a codemod in `scripts/` modeled on `migrate-tokens.mjs`.
3. Run it. Re-check `bun run check`. Fix what the codemod can't.
4. Remove the old tokens from `@theme`. Update `ANTI-PATTERNS.md` with the new banned list.
5. Commit as a single PR — partial migrations rot.

## Versioning

- **Major:** breaking semantic change, primitives reorganized, tokens removed (this happened: v1 → v2).
- **Minor:** new tokens, new components, refined ratios.
- **Patch:** doc clarifications, no token changes.
