# Migrating Ristra's surfaces onto the design system

The design system (this repo) is now the canonical source for color, type, spacing, radius,
and motion. Three surfaces still run on legacy palettes. Migrate them in this order — each
phase is independently shippable and reviewable.

Semantic token **names are unchanged** everywhere, so each phase is a value swap, not a rename.

---

## Phase 1 — Web app / PWA (`Shopping List` repo)

1. **Token block.** Replace the token block at the top of `src/app.css` (the `:root` and
   `:root[data-theme="dark"]` sections, currently lines 1–98) with the contents of this repo's
   [`tokens.css`](tokens.css). Everything below the token block is untouched. New tokens the
   app didn't have (`--link`, `--space-*`, type scale, motion) are additive — adopt them
   opportunistically.
2. **Theme plumbing hexes.** In `src/lib/theme.js`, update the `theme-color` meta values:
   dark `#201e1c` → `#0f0a06` (earth-975). Light stays `#ffffff` while the header is on
   surface; use `#fcf6ed` (earth-50) if the header sits on bg.
3. **Pre-paint script.** `index.html` inline theme script: no logic change, but re-check the
   hardcoded fallback colors if any.
4. **PWA manifest.** In `vite.config.js`: `background_color` and `theme_color`
   `#faf1ea` → `#fcf6ed` (earth-50).
5. **Logo.svelte.** The v2 line-chili mark keeps riding `var(--accent)` / `var(--pill-bg)` —
   it re-themes automatically. Eyeball it on both themes.
6. **Grep for legacy literals.** `--clay-` and `--sky-` variables disappear; any component
   `<style>` blocks referencing them directly must move to semantic tokens (that's the point).
   `grep -rn 'clay-\|sky-' src/` should end up empty.
7. **QA list:** both themes × (lists screen, list detail with all four item states, live-trip
   banner, edit sheet, settings, auth screen, install banner). Check iOS Safari standalone
   status-bar blending.

## Phase 2 — iOS

1. Copy [`platform/Theme.swift`](platform/Theme.swift) over
   `ios/ShoppingList/Theme/Theme.swift`. The Color API is identical; the app compiles without
   other changes.
2. From now on the design repo is the color source for iOS. (`gen-data.mjs` keeps generating
   *data* — departments, stores — from the web app; theme now comes from here.)
3. QA on simulator: light/dark appearance flip, Liquid Glass tinting on list rows, trip pulse.

## Phase 3 — Marketing site (`ristra-site` repo)

1. Replace the token snapshot at the top of `styles.css` (the "Southwest Earthy v1.0" block)
   with `tokens.css` values. Retire the terra/sage/ocher/turq 100–700 ramps and `--ink-*` set;
   map their usages to the new ramps and semantic tokens.
2. Copy the Latin-subset woff2 fonts from `assets/fonts/` and switch the Solitreo
   `@font-face` to woff2 (keep ttf fallback if desired). Add the Jua face for the tagline.
3. Update the README note that pointed at the app's `src/app.css` — the snapshot source is now
   this repo.

## Phase 4 — Figma variables

Import [`tokens/ristra.tokens.json`](tokens/ristra.tokens.json) with Tokens Studio (or push via
the Figma MCP) into the Ristra-branding file: `ramp.*` groups as primitive variables,
`semantic.light` / `semantic.dark` as one collection with two modes. Bind the brand-file
components to variables afterward so Figma designs and code resolve identically.

## Phase 5 — Android (later)

Add an `emitKotlin()` emitter to `scripts/gen-tokens.mjs` producing a Compose `ColorScheme` /
token object from the same resolved values. The emitter seam is marked in the script.

---

## Legacy → new mapping

Old ramps were doing double duty (clay was both the accent hue *and* the neutral ladder).
The new system splits those jobs: **terra** carries the accent, **earth** carries the neutrals,
**turquoise** replaces sky.

| Legacy | Was | Becomes | Now |
|---|---|---|---|
| `--clay-600` (accent) | `#a5613b` | `--terra-600` | `#d7391d` |
| `--clay-700` (accent-strong) | `#834d30` | `--terra-700` | `#a71c00` |
| `--clay-50` (bg) | `#faf1ea` | `--earth-50` | `#fcf6ed` |
| light surface-sunken | `#f6e8dd` | `--earth-100` (sand) | `#ffeed6` |
| light border | `#ecdccf` | `--earth-200` | `#e2d2bb` |
| light text | `#3a2a1f` | `--earth-900` | `#362c21` |
| light text-muted | `#8a6f5e` | `--earth-600` | `#7c6f60` |
| `--sky-600` (title) | `#2f7295` | `--turquoise-500` | `#0a9c81` |
| `--sky-500` (in-cart) | `#3a89b4` | `--turquoise-500` | `#0a9c81` |
| `--sky-300` (dark title) | `#84bedd` | `--turquoise-300` | `#20dbba` |
| status-unavailable | `#b4863a` | `--ochre-700` / `--ochre-500` | `#804d00` / `#bf7600` |
| trip sage set | `#e9efdf` … | `--sage-50/200/700/500` | see tokens.css |
| dark bg | `#201e1c` | `--earth-975` | `#0f0a06` |
| dark surface | `#2a2724` | `--earth-950` (brand field) | `#231a11` |
| dark accent | `#cf8a5f` | `--terra-400` | `#f37860` |
| site "Southwest Earthy" ramps | `#b86751` etc. | retired | use terra/sage/ochre/turquoise ramps |

**Unchanged on purpose:** the Apple Icon Composer glass palette (`ristra.icon` bundles) —
app-icon surfaces only; and the in-app v2 line-chili `Logo.svelte`, which re-themes via tokens.