overhaul: 03 primitives

[CS-5]

Layer 3 of the overhaul stack, on overhaul/02-design-system. plan/03-primitives.md.

The zero-JS primitive layer, plus the agent skill for adding more.

What's here

Button (5 variants × 4 sizes, renders <a> given href), Card with CardHeader/Title/Description/Content/Footer, Badge (7 tones incl. the four sponsor tiers), Input, Textarea, Label, FieldError, Separator, Accordion + AccordionItem, Dialog, Carousel, Icon, Skeleton. Every one is on /styleguide in all variants and states, and the theme section at the bottom now renders the full set under data-theme="frc" and "fll".

Interactivity stays as high up the ladder as it can go: Accordion is native <details> with the name attribute for exclusive open, Dialog is native <dialog> so the browser owns the focus trap and Esc, Carousel is a CSS scroll-snap track. The whole styleguide — Dialog and Carousel included — ships 835 bytes of inlined script, and a page built from only the static primitives ships zero <script> tags and zero .js files.

Also here: src/components/ui/primitives/README.md (the conventions) and .claude/skills/shadcn-astro/SKILL.md (how to port a shadcn component, with the Radix→native mapping table and the Accordion worked through end to end, including what gets dropped and why).

⚠️ Two silent bugs this phase surfaced

Both would have spread through every page built after this one.

1. cn() was dropping font sizes.

Tailwind builds text-* utilities from two token namespaces — --text-* for sizes, --color-* for colors — and the merge step only recognizes Tailwind's stock scale (text-sm, text-lg), not text-h4 or text-small. So it treated every text-* class as a single conflict group and kept only the last one:

cn("text-primary-foreground", "text-body")  →  "text-body"
cn("text-small", "text-muted")              →  "text-muted"   // size gone

The first line is the damaging one. Every primary button's label rendered in body gray on Safety Yellow — I measured it in the browser at 1.3:1. @/lib/cn is now a configured merge (cnfast takes a tailwind-merge config) that registers the §3 type scale as the font-size group. Same buttons now measure 11.7:1, and size-plus-color pairs keep both classes while two colors or two sizes still resolve to the last.

The tradeoff worth flagging: adding a size token to global.css now means adding one line to cn.ts, or it silently loses to any color next to it. That's called out in cn.ts, the primitives README, and the skill.

2. text-body is a color, not a size. Phase 02 established this (body names both, Tailwind resolves colors first), but Button, Input, and Textarea were all using text-body intending the size and silently getting none. They use text-copy now.

Deviations from the phase brief

• Icons come from @tabler/icons, inlined at build per ADR 0002 — not astro-icon + @iconify-json/tabler. Worth knowing: that package's exports map is "./*": "./icons/*", which rewrites every subpath including package.json, so src/lib/icon.ts locates the icons directory through a known icon file rather than the manifest. An unknown icon name throws at build with a pointer to tabler.io/icons.
• CVA recipes live in sibling *.variants.ts files. Astro forbids exporting values from a component (astro/no-exports-from-components), so buttonVariants can't live in Button.astro. This turns out better than shadcn's arrangement: another component can import the recipe rather than copying classes.
• Card sub-parts are separate components, not named slots, matching shadcn's composition model.
• Skeleton included, no Spinner — the calendar's loading state needs the former in Phase 07; nothing needs the latter.

Verified

• pnpm check && pnpm build green.
• Dialog asserted against the live page: dialog.open is true after the trigger, false after Escape.
• Button contrast and computed font sizes read out of the browser after the cn() fix (11.71:1; 14px / 16.85px / 18.70px for sm/md/lg, the fluid clamp working).
• Zero-JS claim verified by building a page using only Button/Card/Badge/Input/Accordion and grepping the output.

---

Generated by Claude Code