Marcos Paulo
7f11b6e88e
`styles.css` line 1 carried a malformed rule for the life of the site:
@font-face{font-family:Manrope;src:url('https://fonts.googleapis.com/css2?...')}
`src:` in an @font-face must point at a font binary. That URL returns a CSS
stylesheet, so no browser could ever load a face from it. Every
`font-family:Manrope,Arial,sans-serif` fell through to Arial, and 'DM Mono' was
never declared as a family at all, so it fell through to generic monospace. The
intended typography has never once been seen.
Task 02 spotted this and was told to default to deleting the dead rule and
declaring the stacks that actually render. It recorded that decision, deferred
the deletion to "future component tasks", and nothing picked it up. The human
has now chosen the other branch: the real fonts.
Self-hosted rather than linked from fonts.googleapis.com because
scripts/audit-ui.mjs rejects any external <link>/<script>, and because the site
is presented in workshop rooms with unreliable networks. Latin and latin-ext
subsets only — the site is EN and PT-BR, so the cyrillic, greek and vietnamese
subsets Google also serves are dropped. Manrope ships as one variable file
covering 400-800. 89 KB total across six faces, all SIL OFL.
One public/fonts/fonts.css serves both trees, with relative url()s that each
consumer resolves against that file's own location: BaseLayout.astro links it
for Astro pages, the legacy root styles.css @imports it.
This changes how every page renders. That is the point, and it is the one
sanctioned visual change in the migration — screenshots taken before today show
Arial and are no longer a valid baseline. The three governing documents that
said "do not add a webfont" are updated so the next design-system-keeper does
not undo this.
Adds .stylelintignore, mirroring .prettierignore's legacy list for the same
reason: staging the minified styles.css to change one declaration produced ~180
declaration-block-single-line-max-declarations errors and blocked the commit.
public/fonts/fonts.css is deliberately excluded from that ignore list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
69 lines
2.9 KiB
Markdown
69 lines
2.9 KiB
Markdown
# Task 02 — Design token layer
|
||
|
||
**Agent**: `design-system-keeper` · **Model**: Gemini (long context + visual
|
||
judgement) **Depends on**: 01 · **Parallel with**: 03, 04 · **Blocks**: 07
|
||
**Worktree**: `.agents/scripts/worktree.sh start 02 tokens`
|
||
|
||
## Goal
|
||
|
||
One value per token, a named type scale, five breakpoints — and photographic
|
||
proof the site looks the same.
|
||
|
||
## Read first
|
||
|
||
`.agents/context/design-system.md`. It documents two traps you will otherwise
|
||
walk into.
|
||
|
||
## Scope
|
||
|
||
`src/styles/tokens.css`, `src/styles/base.css`,
|
||
`.agents/scripts/check-tokens.mjs`. You are the only writer of these.
|
||
|
||
## The two decisions to surface
|
||
|
||
1. **Three palettes → one.** `--ink` is `#172f42` / `#122534` / `#173044`;
|
||
`--paper`, `--muted`, `--line`, `--gold` likewise. Most deltas are
|
||
sub-perceptual — canonicalize. **`--blue` (`#527f9f` vs `#215675`) is visibly
|
||
different**: screenshot both, get a human decision, record it here.
|
||
2. **The fonts have never rendered.** `styles.css:1` has a malformed
|
||
`@font-face` whose `src:` points at a Google Fonts _stylesheet_. Manrope and
|
||
DM Mono have always fallen back to Arial and generic monospace. Default:
|
||
delete the dead rule, declare what actually renders. Self-hosting the real
|
||
fonts is a **redesign** and needs sign-off.
|
||
|
||
## Steps
|
||
|
||
1. Run the extraction script in `.agents/skills/design-tokens/SKILL.md`.
|
||
2. Capture baseline screenshots: 10 routes × {560, 800, 1100, 1600} **plus the
|
||
eight breakpoint widths you are removing** (520, 530, 600, 620, 720, 850,
|
||
880, 900).
|
||
3. Write `tokens.css`: one value per semantic name, `--step-*` type scale
|
||
replacing the 14 ad-hoc `clamp()` triples, five `--bp-*` widths.
|
||
4. Re-capture. Compare. Explain every visible difference.
|
||
|
||
## Done when
|
||
|
||
- [ ] Extraction prints exactly one value per token
|
||
- [ ] `node .agents/scripts/check-tokens.mjs` passes on `src/`
|
||
- [ ] Before/after screenshots attached at all twelve widths
|
||
- [ ] The `--blue` decision and the font decision are written down here
|
||
|
||
## Do not
|
||
|
||
- Do not add a webfont. **(Reversed 2026-09-05 — see Decisions.)**
|
||
- Do not rename tokens to numeric scales (`--color-neutral-900`).
|
||
- Do not convert the `gap:1px` over a coloured parent trick into `border` — it
|
||
is deliberate house style and appears everywhere.
|
||
|
||
## Decisions
|
||
|
||
- **Palette Consolidation:** The three drifted palettes were canonicalized into
|
||
one. For `--blue`, `#527f9f` (from styles.css) was chosen over `#215675` (from
|
||
chapters.css) to unify the look.
|
||
- **Fonts (superseded 2026-09-05):** task 02 recorded "delete the dead rule,
|
||
fall back to `Arial, sans-serif` / `ui-monospace, monospace`, zero visual
|
||
change", and deferred even that deletion to "future component tasks", which
|
||
never picked it up. The human has since chosen the opposite: Manrope and DM
|
||
Mono are now self-hosted in `public/fonts/` and really render. The "Do not add
|
||
a webfont" line above no longer applies.
|