overhaul: 02 design system

[CS-5]

Layer 2 of the overhaul stack, on overhaul/01-foundation. plan/02-design-system.md.

DESIGN.md turned into working CSS. ⚠️ This PR amends DESIGN.md — see "Design amendments" below, it needs your eyes.

What's here

Tokens (src/styles/global.css) — the full §2–§4/§6 set as a Tailwind v4 @theme block: the recessed surface system, the AAA text ramp, fill/text accent pairs, sponsor tiers, the fluid type scale as clamp() between 360px and 1440px, the three-value radius scale, motion durations and easings.

Program themes remap exactly four tokens — primary, primary-bright, primary-foreground, ring — and nothing else, diff-checked in the built CSS.

Fonts, self-hosted. Declared face by face rather than importing the @fontsource CSS, because those ship every subset: this way dist contains 5 latin woff2 files and no cyrillic, greek, or vietnamese. src/styles/fonts.ts exports the two above-the-fold URLs for Phase 05's preload.

Motifs as components so pages can't reinvent them: Pattern (engineering grid + dimension ticks), GhostNumeral, RulerDivider, RegistrationMarks, TitleBlock, Callout, and the hand-markup set — ChalkOval, ChalkUnderline, SketchArrow, each with three distinct paths. Plus utilities for the pocket anatomy, accent rules, media frame, highlighter swipe, ambient pools, spec labels and chips.

/styleguide — every token, ramp, and motif rendered once, with computed contrast ratios, and each section repeated under data-theme="frc" and "fll". Noindexed.

Contrast is verified at build, not by eye

The page computes every pair DESIGN.md §9 requires and throws with the offending pairs listed if one drops below its floor. Verified by temporarily dimming body to #8A8A8A:

Error: DESIGN.md §9 contrast floors violated — fix the tokens in src/styles/global.css:
  body (#8A8A8A) on #262626 is 4.3:1, below its 7:1 floor
  body (#8A8A8A) on #171717 is 5.1:1, below its 7:1 floor

A token edit can't quietly break accessibility now.

Design amendments (DESIGN.md §11) — please review

That verification caught two real defects in the spec:

1. Science Blue's fill label was failing AA. #FAFAFA on #3B82F6 measures 3.5:1, and blue fills carry chip-sized text (calendar/event chips, data UI). Changed the label to the brand near-black #171717 → 4.9:1, which also stops blue being the one fill with a white label. Science Blue's own hex is untouched, so its reservation as the future light-theme primary stands.
2. body's documented ratio was wrong — "≈11.5:1" vs. a measured 10.2:1. Still AAA; the decision holds, only the number changed.

Two gaps filled:

3. Added a destructive pair (#DB262F/#FAFAFA fill at 4.6:1, #FCA5A5 text at 8.0:1). §8 requires "the destructive text token" but no value existed anywhere in the doc.
4. Highlighter swipe pinned at 25% alpha — the only value in the documented 25–35% range that keeps white text at AAA (7.7:1 on the ground, 9.2:1 on card). §2.13 asked for this to be verified on /styleguide; the page now prints the measured numbers.

Also corrected Danger Orange's stated 8.0:1 to the measured 7.9:1.

Deviations from the phase brief

• Four theme tokens, not three. The brief's acceptance line says three; DESIGN.md §2 lists four, adding primary-bright. The doc wins (§11) — and without it, links and stat numerals on a green FRC page would stay yellow.
• Motif components live in src/components/ui/primitives/, which Phase 03 also populates. DESIGN.md §2.12 calls them primitives; the conventions README arrives with Phase 03.
• @typescript-eslint/no-unsafe-return is off for .astro. astro-eslint-parser doesn't type template JSX, so every items.map(() => <El />) resolves as error and trips the rule. Frontmatter — where the real logic lives — stays fully typed, and astro check type-checks templates properly. The config comment names the sibling rules that may need the same treatment, and says not to blanket-off the family.
• The gear-bulb lineart vector is still outstanding (§2b — it needs to come from the merch/brand source files). I deliberately did not commit an approximation, so the scribed-lineart motif is simply absent rather than something to un-draw later. The other scribed devices (TitleBlock, Callout) are done.

Notes

Two mechanics worth knowing, both of which bit during implementation: hand-markup strokes carry pathLength="100" so the draw-on dash math is in percent — a hard-coded length silently truncates any longer path, which is what first left the chalk ovals as open arcs — and the ovals and underlines use vector-effect="non-scaling-stroke", since their SVG is stretched non-uniformly over whatever word it wraps.

I rendered the page at 1280px and 390px and iterated on it; both hold up, and the contrast table scrolls inside its own container rather than the page.

---

Generated by Claude Code

[CS-5]

Code review of the design-system layer. Verified by installing this branch, running pnpm check (green) and pnpm build, then reading the emitted dist/_astro/global.*.css, dist/styleguide/index.html and dist/sitemap-0.xml, and by compiling global.css against the pinned tailwindcss@4.3.3 to confirm what the utilities actually resolve to. Contrast numbers below come from this PR's own src/lib/contrast.ts.

The structure is good and the build-time contrast idea is the right instinct. Eleven findings, four of which change what ships:

Rendering / behavior

1. global.css — in-prose links get no underline: text-decoration-line is never set, and preflight's a { text-decoration: inherit } resolves it to none. DESIGN.md §8 unimplemented, and links become color-only.
2. global.css — adding svg to the base max-width: 100% rule clamps ChalkOval's w-[calc(100%+2rem)], so the oval renders word-width and offset 1rem left instead of ringing the word.
3. SketchArrow.astro — direction="right" is dead: the inline rotate style overrides the -rotate-45 class, since Tailwind v4 rotation uses the rotate property.
4. global.css — --color-body and --text-body both claim .text-body; the color wins, so the body size token has no usable utility (and the type-ramp row demonstrating it silently sets a color).

The guard itself
5. styleguide.astro — the contrast check reads hex literals duplicated into the page, not global.css, so a token edit on the CSS side alone leaves the build green against stale values.
6. DESIGN.md — Danger Orange's "corrected" 7.9:1 is the destructive token's number; #FB923C measures 6.6:1. The error crosses the AAA line, and the guard's AA-only floor can't catch it.

Smaller
7. /styleguide is noindex but still listed in dist/sitemap-0.xml — one-line filter in astro.config.ts.
8. spec-chip's border is opaque currentcolor, while its comment and DESIGN.md §8 both specify 40% alpha.
9. Callout renders <figcaption> with no <figure> anywhere on the page.
10. ambient-pool-neutral silently renders nothing unless composed with ambient-pool.
11. Swipe (7.6 vs 7.7) and Science Blue label (4.8 vs 4.9) doc figures are each 0.1 off the verifier.

Nothing here is structural — 1, 2 and 3 are the ones I'd fix before merge.

---

Generated by Claude Code

[CS-5]

/simplify pass — quality review (reuse · simplification · efficiency · altitude)

Quality only; correctness findings are in the separate review on this PR. Finding 2 below overlaps that review's styleguide.astro:23 item — I'm restating it because three of the four quality angles landed on it independently, and because the fix is a simplification rather than a bug patch.

---

1. The engineering grid is defined twice — once as a CSS utility, once as an inline style with a raw hex

src/components/ui/primitives/Pattern.astro:22-38

const opacity = { hero: 0.07, section: 0.05, pocket: 0.04 }[placement];
const cell = placement === "pocket" ? 26 : 28;
...
      background-image:
        linear-gradient(to right, #FAFAFA 1px, transparent 1px),
        linear-gradient(to bottom, #FAFAFA 1px, transparent 1px);
      background-size: ${String(cell)}px ${String(cell)}px;

src/styles/global.css:260-267 (@utility pocket-feature) already draws exactly this grid — same two gradients, same 26px cell — as rgb(250 250 250 / 0.05). So one DESIGN.md §2.3 device now has two independent implementations that already disagree (0.04 vs 0.05 alpha), in two different syntaxes. A change to cell size or stroke alpha has to be made twice.

The color is the worse half. #FAFAFA is the literal value of --color-foreground, and DESIGN.md §2 says "All component color comes from semantic tokens — raw hex values and Tailwind palette classes are banned in components." D15 promises "a light theme / theme switcher is a future token-set addition, not a refactor" — but a white grid is invisible on a light ground, so the light theme becomes a component edit plus two utility edits, in three files a token-block author has no reason to open. This is also the one motif DESIGN.md restricts by placement, so it'll be reused on heroes and section breaks and spread the literal further. (global.css:373 ambient-pool-neutral has the same hardcode as rgb(250 250 250 / …).)

Fix: one @utility engineering-grid in global.css parameterized by --grid-cell / --grid-alpha, built on currentColor (gradients accept it) with text-foreground on the wrapper. pocket-feature composes it; Pattern sets class="engineering-grid" plus two custom properties. The whole style template literal and both lookup tables collapse.

---

2. The contrast gate verifies a hand-typed copy of the palette, not the tokens

src/pages/styleguide.astro:23-120

const BACKGROUND = "#262626";
const CARD = "#171717";
const textTokens: readonly TextToken[] = [
  { name: "foreground", value: "#FAFAFA", floor: AAA_NORMAL, use: "Headings, nav, emphasis" },
  { name: "body", value: "#D4D4D4", floor: AAA_NORMAL, use: "All reading copy" },

~25 hex values (surfaces, text ramp, fill pairs, tiers), the three radius values, and const SWIPE_ALPHA = 0.25 (line 95) restate global.css:16-53 and the 25% inside @utility highlight-swipe (line 304). The build-time throw compares those literals to each other; global.css is never read.

So the gate cannot detect the thing it exists to detect. Edit --color-body in global.css and the build stays green against #D4D4D4, and the rendered swatch keeps showing the old color. DESIGN.md §9: "Contrast pairs verified live on /styleguide (computed ratios rendered); token changes must re-verify." A token change does not re-verify here.

It's already incomplete in exactly this way: textTokens carries one primary-bright, so the program themes' accent text colors — #3ECF6E and #FB923C, whose ratios DESIGN.md §2 tabulates — are never checked on any surface, even though the page renders both themes.

Fix: give the palette one source. import globalCss from "@/styles/global.css?raw" (or readFileSync — src/lib/icon.ts in PR #17 does build-time file reads already), scan the --color-* / --radius-* declarations out of the @theme block into a Record<string, string>, and drive both the swatches and the gate off the parsed map. The arrays then keep only what's genuinely editorial (floor, use) and look values up by name — a missing token becomes a build failure instead of silent drift. Deriving the theme rows from the [data-theme] blocks the same way means a new program can't ship an unchecked accent.

---

3. The hand-markup stroke recipe is copy-pasted across three primitives

ChalkOval.astro:21-43, ChalkUnderline.astro:19-44, SketchArrow.astro:44-57

      tone === "chalk" ? "text-foreground" : "text-primary",
...
    <path
      d={paths[variant]}
      pathLength="100"
      stroke="currentColor"
      stroke-linecap="round"
      stroke-width="2.5"
      vector-effect="non-scaling-stroke"></path>

ChalkOval and ChalkUnderline have effectively the same body — same variant/tone/class props, same paths/rotations lookup tables, same <span class="relative inline-block"> + stretched preserveAspectRatio="none" svg — differing only in path data and placement classes. The tone ternary appears three times and the five stroke attributes five times. SketchArrow has already dropped vector-effect while the other two kept it, which is the drift arriving on schedule.

DESIGN.md §13 sets these values for the register as a whole ("2–3px, stroke-linecap: round") and mandates ≥3 variants per markup device with more devices coming — so this template gets copied again each time a device is added, and the part that must stay identical across devices is exactly the part that's duplicated.

Fix: either an internal HandStroke.astro owning the wrapper, the tone ternary and the <path> attributes (taking paths / rotations / viewBox / positioning classes as props), or an @utility hand-stroke in global.css beside the existing @utility draw-on carrying fill: none; stroke: currentColor; stroke-linecap: round; stroke-width: 2.5. Either way ChalkOval and ChalkUnderline keep their public API and shrink to a data table plus one element.

---

4. Four hand-written corner paths where one path and three rotations do it

src/components/ui/primitives/RegistrationMarks.astro:15-27

const corners = [
  { key: "tl", path: "M1 13 L1 1 L13 1" },
  { key: "tr", path: "M11 1 L23 1 L23 13" },
  { key: "br", path: "M23 11 L23 23 L11 23" },
  { key: "bl", path: "M13 23 L1 23 L1 11" },
] as const;

const position = { tl: "top-0 left-0", tr: "top-0 right-0", ... } as const;

I checked the geometry: every path is the tl bracket rotated 90° about (12,12) — M1 13 L1 1 L13 1 rotated 90° is exactly M11 1 L23 1 L23 13. So the bracket's arm length and inset are encoded four times, and changing the mark means recomputing four coordinate strings by hand and keeping a second keyed map in sync.

Fix: one const BRACKET = "M1 13 L1 1 L13 1" and one list of position+rotation classes — ["top-0 left-0", "top-0 right-0 rotate-90", "right-0 bottom-0 rotate-180", "bottom-0 left-0 -rotate-90"]. The corners/position pair becomes a single array and the path is edited once.

---

5. The four brand SVGs are duplicated, not moved — the public/ copies still deploy

src/assets/brand/logo-black-full.svg, logo-color-full.svg, logo-color.svg, logo-white-full.svg

These are byte-identical to the existing public/image/svg/* (same git blob hashes — e.g. f51e8055… for logo-black-full.svg in both places), and both copies are still present as of 05-app-shell.

Cost: 48,422 bytes uploaded on every Cloudflare Pages deploy for files nothing references, served unhashed from public/ (no fingerprint, no immutable caching) rather than the fingerprinted _astro/ copies Astro emits. Plus two sources of truth for the logo.

Fix: delete public/image/svg/logo-*.svg. legacy/ is reference-only and never built, so nothing needs them at that path.

---

Checked and cleared

The font setup is the strongest part of this PR and I want to say so explicitly: src/styles/fonts.css + fonts.ts are self-hosted, latin-only @font-face declarations hand-written to keep cyrillic/greek out, font-display: swap on every face, one variable file per family, and exactly the two above-the-fold faces preloaded. I confirmed in built dist/index.html that the two rel="preload" hrefs match the url()s in the emitted CSS byte for byte (inter-latin-wght-normal.Dx4kXJAl.woff2, orbitron-latin-wght-normal.Du7j2Vp2.woff2), so there's no double fetch. No finding.

Also cleared: the styleguide's utilities are not leaking into the shared bundle (removing the page shrinks the CSS by 1.4 KB raw / 227 bytes gzipped).

---

Generated by Claude Code