docs: add tasks 02b and 02c for the dead token layer and the gap queue
This commit is contained in:
Marcos Paulo
@@ -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
|
||||
Reference in New Issue
Block a user