[mvilacad]

Closes #122

Root causes

1. Page jumps / stuck while using the theme lab (screen recording). Two causes:
   • Layout shift: focusing the Brand color field switched the lab to brand mode, which appended one line (presets: [...]) to the code snippet. The chapter copy column is vertically centered against the lab, so the whole section moved ~10px and the document grew 21px under the reader's scroll (CLS 0.0035).
   • Swatches stole each other's clicks (library bug). The hand-rolled swatch had a 44px ::after tap pad on a 26px dot at a 34px pitch, so each pad overlapped its neighbours. A click aimed at violet landed on emerald (Playwright: <button aria-label="emerald"> intercepts pointer events), i.e. selecting a color silently failed or picked the wrong one.
2. Hero glow, copy density, mixed button styles: design debt in the site theme.

Changes

packages/ui (core)

• New SwatchGroup (role="radiogroup", roving tabindex, preset or custom color, size, disabled, forced-colors styles). Under pointer: coarse the swatch itself is the 44px target, so hit areas can never overlap. Tests in SwatchGroup.svelte.test.ts (axe, click/onchange, keyboard, paint, no tap area reaches a neighbour). Documented in AGENTS.md, README, llms.txt and the generated API.md. Changeset: minor.

site/

• Theme lab: uses SwatchGroup; the snippet has the same number of lines in every mode; focusing the hex field no longer flips to brand mode (only a valid typed hex does).
• Hero 'Northwind' app, alive: revenue and active-teams tick (paused by Auto deploy off), the chart draws in and bars rise, a working Auto deploy switch drives the status chip, 12 weeks / 4 weeks range (and Preview) rebuilds the charts, Ship it runs a release (Releasing v2… then v2 is live) and shows a toast. Under prefers-reduced-motion there are no timers, no draw-in and the release resolves immediately; markup is the final state, so e2e/VRT are deterministic. Uses the package's toast/Toaster, SegmentedControl, Switch, StatusChip.
• Orange corner glow removed: replaced with a pencil hatch (diagonal strokes) in the active preset's brand color, fading toward the middle. The hero now starts on the site's own blue (ocean) instead of amber.
• Sketchbook polish: calmer grid via theme overrides (32px pitch, ~55% ink), plain-language copy across hero and chapters, one button hierarchy (filled primary + outlined secondary + ghost tertiary), the agent prompt box moved out of the fold into the agents chapter, quieter first screen (no code above the fold).

Regression tests (test first)

site/tests/landing-theme-lab.spec.ts (3 tests) and SwatchGroup.svelte.test.ts.

Before (current code / old pad design):

✘ landing-theme-lab › switching style, swatch, scheme and brand color keeps scroll and layout
    Test timeout ... <button aria-label="emerald" data-preset="emerald"> intercepts pointer events (swatch violet)
✘ landing-theme-lab › layout shift score stays zero while the preview changes   (same click blocked)
  with only the swatch fixed and the snippet line left in:
    - "docH": 6200, "copyTop": 1095, "labH": 583
    + "docH": 6221, "copyTop": 1105, "labH": 604      CLS Received: 0.0035
SwatchGroup: × no swatch tap area reaches into a neighbouring swatch
    AssertionError: swatch 1 overlaps swatch 0: expected 25 to be greater than or equal to 35

After: landing-theme-lab.spec.ts 3/3 pass; SwatchGroup.svelte.test.ts 5/5 pass.

Verification

• bun run validate passes (pre-push gate).
• Playwright: landing.spec.ts + landing-theme-lab.spec.ts (desktop + mobile), layout.spec.ts for / (390, 768, 1024, 1280, 844x390), routes.a11y.spec.ts for / (dark, light, forced-colors), keyboard, responsive, scroll-lock, theme, network-idle: all green.

Screenshots (1440x900)

	Before	After
Hero, dark
Hero, light
Theme chapter, dark
Theme chapter, light
Agents chapter, light

(Images live on the throwaway branch pr-assets/122; delete it after merge.)

Maintainer notes

• Visual baselines for / must be regenerated (hero, copy and grid changed): run bun run test:vrt:update on this branch; the visual job commits __screenshots__/.
• site/src/content/docs is untouched; a swatch-group.mdx page is requested from the Docs owner.

Checklist

• bun run validate passes
• Changeset (minor, SwatchGroup)
• Docs updated (AGENTS.md, README, llms.txt, API.md); site docs page pending (Docs owner)

[github-actions]

Site preview: https://pr-124.codeatlas-ui.pages.dev