Task 15e — Retire responsive.css

Agent: design-system-keeper · Model: agy (Gemini 3.1 Pro — vision) Depends on: 15d, 16 · Blocks: 20 Worktree: .agents/scripts/worktree.sh start 15e responsive-css

Goal

responsive.css is 30 KB and mostly served /full-guide/. Once 15d and 16 have landed, port what the Astro pages still need into component styles or tokens.css, prove the remainder dead, and delete it.

Proof is screenshots, not reading. A rule that looks unused because no selector matches at 1600 px may be the only thing holding the 560 px layout together.

Method

Build. Screenshot every migrated route at 560 / 800 / 1100 / 1600 px.
Remove responsive.css from the build entirely.
Screenshot again. Every diff is a rule you must port.
Port it into the owning component's <style>, or — if it is a real token — into tokens.css, which you own. No other agent may add tokens.
Repeat until the diffs are empty.

Constraints

Allowed breakpoints are 560 / 800 / 1100 / 1600 / 2200 px. .agents/scripts/check-tokens.mjs rejects others.
Do not delete the file while any legacy page still loads it. Check which routes have actually been migrated at the time you run; 20 is the cutover.
No raw hex, no font-size: Npx outside tokens.css.
You are also the owner of the ~190 accumulated /* token-gap: ... */ markers. Resolving them is not in this brief — do not start. Report the count so it can be scheduled.

Done when

Screenshot diffs empty at all four widths without responsive.css
Ported rules live with the component that needs them, or in tokens.css
responsive.css deleted, and nothing references it
pnpm run gate green; 42 assertions intact

Amendment — the screenshot step now actually works

When this brief was written, .agents/scripts/visual-regression.mjs threw playwright ... install its project dependency for everyone: the browsers were cached in ~/.cache/ms-playwright but the node package was never a dependency. Every "screenshots match" checkbox in this plan was unsatisfiable. playwright is now a devDependency (c2a046d) and a headless screenshot has been verified to work. Take the screenshots. "I read the rules and they look unused" is not the proof this brief asks for.

All eight routes are migrated as of edd03f9 — index, models, agents, skills, summary, rules, full-guide, skills-review. Screenshot all of them, not just /full-guide/.

Amendment — the token-gap queue is already closed

The brief says "~190 accumulated /* token-gap: ... */ markers … do not start". Task 02c ran and took them from 154 to 17. Do not reopen that work either; the 17 that remain are deliberate.

Two things 02c got wrong that you must not repeat. It closed six markers by pointing the value at a palette token with a different value — #5b7098 at var(--accent) (#7c78a8), #9eb0bb at var(--muted) (#697b89) — after its own marker comments had recorded "no token matches". That shipped a silent redesign the gate could not see. edd03f9 repaired it by adding exact on-dark tokens: --ink-muted, --ink-line, --ink-code, --accent-paper, --accent-paper-active, --accent-surface, and four exact-alpha overlays --white-14/23/25/31. Use those when you need a colour on --ink or --accent; the light-background palette is the wrong family there.

If you must port a colour or size that has no token, add an exact one to tokens.css — you own it — or leave the raw value under a token-gap: marker. Never round to a near neighbour.

Amendment — how this gets verified

The gate does not read your output: all 42 assertions in scripts/verify.mjs read the legacy files, so deleting responsive.css and breaking every mobile layout passes it cleanly. Before you claim done, diff the built CSS (dist/_astro/*.css) against main and enumerate every declaration that disappeared. Each one is either present elsewhere or a regression.

Attempt 1 stopped short — and the goal as written is not reachable yet

Preserved as rejected/15e-attempt-1 (d2312d7). Start by reading that diff: it ported rules into ChapterHero, FleetDiagram, RouteTable, WorktreeMap, LanguageToggle, ReadingProgress, agents.astro, full-guide.astro and tokens.css, and it added pixelmatch, pngjs and postcss plus a working screenshot-compare harness. Reuse all of it. It never finished the comparison loop and never committed on its own.

It also deleted responsive.css while full-guide/index.html still links it. That page is the live site until task 20 cuts over; deleting the stylesheet strips it. src/components/islands/GuideSelector.astro still references it too.

So the "delete it" checkbox in this brief cannot be honestly ticked before the cutover. Do not tick it, and do not delete the file. The deliverable is everything up to the deletion:

Every rule responsive.css provides to an Astro route lives with the component that needs it, or in tokens.css.
No .astro file and no Astro layout links responsive.css any more.
full-guide/index.html still links it, unchanged, and still renders exactly as it does today.
A list, in this file, of the rules that remain in responsive.css solely for the legacy page — that list is the deletion checklist task 20 will execute.

Amend the "Done when" boxes to match before you start, and say in your final report that the file is intentionally still present.

One rule to port properly while you are in there

.route-meter span animates height: var(--score) — a layout property, which task 18 was meant to eliminate. 18 changed it in responsive.css and that change was reverted (0bca43c) because it belongs in the component, not in a legacy file. When you port this rule, port it as transform: scaleY(var(--score)); transform-origin: bottom with height: 100%. --score is set inline as a percentage (--score:92%) by GuideSelector.astro and full-guide.astro; a percentage in scaleY() is valid and was verified rendering correctly at matrix(1, 0, 0, 0.92, 0, 0). Leave the legacy responsive.css copy of the rule alone.

6.1 KiB Raw Blame History