diff --git a/plans/astro-refactor/README.md b/plans/astro-refactor/README.md index e0825e7..4e5262f 100644 --- a/plans/astro-refactor/README.md +++ b/plans/astro-refactor/README.md @@ -45,6 +45,8 @@ Phase 4 polish 18 ∥ 19, then 20 | --- | ----------------------------------------------------------------- | --------------------- | ------------------ | ------------- | | 01 | [scaffold + gates](task-01-scaffold.md) | astro-architect | — | — | | 02 | [design tokens](task-02-tokens.md) | design-system-keeper | 01 | 03, 04 | +| 02b | [token layer wiring](task-02b-token-layer-wiring.md) | design-system-keeper | 02 | 03, 04 | +| 02c | [token-gap queue](task-02c-token-gaps.md) | design-system-keeper | 02b, 15d | — | | 03 | [verification net](task-03-verification-net.md) | verification-engineer | 01 | 02, 04 | | 04 | [content schema](task-04-content-schema.md) | content-i18n-migrator | 01 | 02, 03 | | 05 | [guide content](task-05-content-guide.md) | content-i18n-migrator | 04 | 06 | diff --git a/plans/astro-refactor/task-02b-token-layer-wiring.md b/plans/astro-refactor/task-02b-token-layer-wiring.md new file mode 100644 index 0000000..0ac2dfc --- /dev/null +++ b/plans/astro-refactor/task-02b-token-layer-wiring.md @@ -0,0 +1,107 @@ +# Task 02b — Wire the token layer in + +**Agent**: `design-system-keeper` · **Model**: `agy` (Gemini 3.1 Pro — needs +vision for the screenshot diffs) **Depends on**: 02 · **Blocks**: 02c +**Worktree**: `.agents/scripts/worktree.sh start 02b token-layer-wiring` + +## Why this task exists + +Task 02 built the token layer and it was never connected to anything. This is +not a criticism of that task — its brief and its done-when list never asked for +the wiring, and `check-tokens.mjs` only looks for _violations_ in `src/`, so +nothing could have caught it. + +Verify each of these yourself before you start; do not take my word for it: + +1. **`src/styles/tokens.css` is imported by nothing.** The only reference in the + repo is `src/styles/base.css:2`, and `base.css` is itself imported nowhere. + The whole layer is dead code. +2. **The pages import the legacy stylesheets instead**, drifted `:root` blocks + and all: + - `src/layouts/ChapterLayout.astro:16` → `../../chapters.css?url` + - `src/pages/skills.astro:11` → `../../skills/styles.css?url` + - `src/pages/skills-review.astro:4,5` → `skills-review/styles.css`, + `change-lens.css` +3. **So task 02's `--blue` decision never reached a page.** It chose `#527f9f` + and wrote it down. The built CSS today ships both values: + ``` + dist/_astro/chapters.*.css --blue:#215675 + dist/_astro/rules.*.css --blue: #527f9f + dist/_astro/styles.*.css --blue:#215675 + ``` + +## Scope + +`src/styles/tokens.css`, `src/styles/base.css`, +`.agents/scripts/check-tokens.mjs` — you are the only writer of these — plus the +four import sites listed above and whatever layout work the wiring needs. + +## Deliver + +### 1. One loaded token layer + +Make `tokens.css` actually load on every route. Either fix `base.css` and import +it from the layouts, or drop `base.css` and import `tokens.css` directly — your +call, but say which and why. A file that exists and is never loaded is worse +than no file, because it reads as done. + +### 2. The legacy stylesheet imports reconciled + +Those three `?url` imports are how the drifted palettes reach production. You do +not have to delete them in this task — much of that CSS is still load-bearing +until task 15e and task 20 — but the `:root` blocks inside them must stop +overriding the canonical tokens. Make the layer authoritative and prove with +screenshots that nothing moved except what you intend. + +`--blue` is the one real difference: `#527f9f` vs `#215675` is visible. Task 02 +already decided `#527f9f`. Apply that decision; do not re-open it. If applying +it looks wrong on a real page, screenshot it and escalate rather than quietly +picking the other value. + +### 3. Font tokens + +Manrope and DM Mono are **real now** — self-hosted in `public/fonts/`, wired +through `public/fonts/fonts.css` (linked by `BaseLayout.astro`, `@import`ed by +the legacy root `styles.css`). Read `.agents/context/design-system.md`; the old +"delete the dead rule, fall back to Arial" instruction is **superseded and must +not be re-applied**. + +Add `--font-sans` and `--font-mono` and point the stacks at them. Do not touch +`public/fonts/fonts.css` itself, and do not remove the faces. + +### 4. A check so this cannot recur + +The gap that let a dead token layer ship is that nothing asserts the tokens are +_loaded_. Add that check — a build-output assertion that every route resolves +the canonical palette, or an equivalent. Put it in `check-tokens.mjs`, which you +own. **Do not touch `scripts/verify.mjs`**; it stays at 42 assertions and only +the verification-engineer may change it. + +## Screenshots: your baseline is HEAD, not history + +The self-hosted fonts landed in `7f11b6e` and **changed how every page +renders**, deliberately — that is the one sanctioned visual change in this +migration. Any screenshot taken before it shows Arial and is not a valid +baseline. Capture your own "before" from HEAD at the start of this task. + +Widths: 560 / 800 / 1100 / 1600, plus the eight breakpoints task 02 removed +(520, 530, 600, 620, 720, 850, 880, 900) — that is where regressions hide. + +## Do not + +- Do not resolve the ~164 `token-gap:` markers. That is task 02c, and doing it + here would collide with task 15d's page work. Report the count. +- Do not delete `responsive.css`. That is 15e. +- Do not convert the `gap:1px` over a coloured parent trick into `border` — it + is deliberate house style and appears everywhere. +- Do not rename tokens to numeric scales (`--color-neutral-900`). +- Never use `--no-verify`; never set `core.hooksPath`. + +## Done when + +- [ ] `tokens.css` loads on every route, proven from built output +- [ ] One value per token in the shipped CSS — `--blue` is `#527f9f` everywhere +- [ ] `--font-sans` / `--font-mono` exist and are used; the faces still load +- [ ] A check exists that fails if the token layer stops being loaded +- [ ] Before/after screenshots at all twelve widths, every difference explained +- [ ] `pnpm run gate` green — the full gate; 42 assertions intact diff --git a/plans/astro-refactor/task-02c-token-gaps.md b/plans/astro-refactor/task-02c-token-gaps.md new file mode 100644 index 0000000..07378f5 --- /dev/null +++ b/plans/astro-refactor/task-02c-token-gaps.md @@ -0,0 +1,51 @@ +# Task 02c — Work the token-gap queue + +**Agent**: `design-system-keeper` · **Model**: `agy` (Gemini 3.1 Pro) **Depends +on**: 02b, 15d · **Blocks**: 19 **Worktree**: +`.agents/scripts/worktree.sh start 02c token-gaps` + +## Why this task exists + +`check-tokens.mjs` bans raw hex, `font-size: Npx` and ad-hoc breakpoints outside +the token layer. Until the escape hatch was added it offered no legal +alternative, so agents told both "keep the site identical" and "get the gate +green" cheated — writing px through the `font:` shorthand the regex misses, or +substituting the nearest token and shipping a silent redesign (`12px` and `14px` +both became `var(--step-1)`, 15px; a diff-added green became `var(--accent)`, +purple). + +The `/* token-gap: ; owner design-system-keeper */` marker replaced that +with an honest, visible queue. **You are the owner it names.** There are ~164 +markers on `main`; get the real count yourself from `check-tokens.mjs` output. + +## The work + +For each marked value, one of three outcomes — and the choice is yours to make, +not to defer: + +1. **The scale should cover it.** Extend `--step-*` and point the site at it. + Most of the queue is this: `24px`, `25px`, `20px`, `17px`, `13px` fixed sizes + from `chapters.css` that fall between existing steps. +2. **It is genuinely one-off.** Keep the literal value, delete the marker, and + leave a comment saying why it is exempt. +3. **It was already wrong.** Some markers record a near-miss substitution an + earlier task made under duress. Restoring the true legacy value is a visible + change — screenshot it and say so. + +Work in batches by source file and commit per batch. A single 164-site commit is +unreviewable. + +## Do not + +- Do not weaken `check-tokens.mjs` to make markers disappear. Removing a check + is not resolving a gap. +- Do not touch `scripts/verify.mjs` — 42 assertions, verification-engineer only. +- Do not leave a marker whose reason you have satisfied. + +## Done when + +- [ ] Every marker either resolved into the scale or documented as a deliberate + exemption +- [ ] `check-tokens.mjs` reports zero unexplained gaps +- [ ] Screenshots for every change that moved a pixel, differences explained +- [ ] `pnpm run gate` green; 42 assertions intact