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