feat(design-system): make the design system the default source for all UI

[EliRobinson]

Makes the design system the primary source of components, tokens, and design patterns for anything built on this template — reinforced across every surface an AI agent or human might read, and enforced by lint and E2E rather than only asked for in prose.

Nothing in this template hardcodes the design system's contents, so bumping the package version is the only maintenance it ever needs.

The mechanism

Docs that list components rot on every design system release. So instead of a list, there's a command — pnpm ds, which reads the installed packages at run time:

pnpm ds                  # components (+ exports & variants), hooks, typography classes, token groups
pnpm ds props Dialog     # props, variant unions, and the exact import line to copy
pnpm ds tokens accent    # tokens filtered by name or value
pnpm ds contracts        # the rules UI must satisfy, and what verifies each
pnpm exec ds-resync      # what's out of date, and what changed while you were away

Every doc points at this command rather than repeating its output. AGENTS.md says it explicitly: never paste or trust a component inventory — it is wrong as of the next release.

The tooling ships from upstream, not from here

The final commit on this branch deletes the hand-built versions of that tooling in favour of the published packages, which are versioned with the code they describe. Each local copy drifted independently, and nothing signalled when it had.

Deleted	Replaced by
scripts/design-system.mjs (333 lines)	elirobinson-ds, a bin on @elirobinson/ai-patterns
The @theme inline block in src/app/globals.css (~30 aliases)	@import '@elirobinson/tokens/tailwind.css'
FOREIGN_UI_LIBRARIES / DESIGN_SYSTEM_BARRELS / DIRECT_PRIMITIVES in eslint.config.mjs	@elirobinson/eslint-config
The hand-written Claude skill, Cursor rule, Copilot instructions, and AGENTS.md section	pnpm ds init --agents
Most of docs/design-system.md (154 → 100 lines)	pnpm ds

The upstream CLI reads a generated manifest.json instead of regex-parsing .d.ts, and is layout-agnostic. The ESLint config adds no-hardcoded-design-values, which catches hex / rgb() / oklch() literals and magic px for radius, shadow and duration in className strings, cn() calls and style objects.

Package versions: react@1.3.0, tokens@0.3.0, ai-patterns@0.5.0, eslint-config@0.2.0, plus axe-core.

Coverage

Surface	Role
AGENTS.md / CLAUDE.md	Managed "UI: design system first" block leads the file; repo-specific rules and "Do Not" entries around it
docs/design-system.md	The four places the design system touches this repo — stylesheets, Tailwind bridge, lint, contract checks
.claude/skills/design-system/SKILL.md	Claude Code skill scoped to fire on any UI-shaped task
.cursor/rules/design-system.mdc	Cursor rule, auto-attached to .tsx/.css
.github/copilot-instructions.md	GitHub Copilot / Copilot Workspace
README.md	Callout above the fold, stack table rows, usage section, agent-surface map

The four agent-instruction files are generated by pnpm ds init --agents, so a version bump refreshes them too.

Enforcement, not just instruction

• Lint — @elirobinson/eslint-config blocks foreign UI libraries, direct Radix imports outside src/components/ui/, bare @elirobinson/* imports, and hardcoded design values.
• Tailwind bridge — @elirobinson/tokens/tailwind.css maps the Tailwind namespaces onto the tokens. This fixed a live bug on the way in: text-muted-foreground previously resolved to nothing, and now compiles to var(--fg-3). Dark mode works via [data-theme="dark"] with no extra code.
• E2E — new e2e/design-system.spec.mts runs expectDesignSystemContracts (touch targets, visible focus, WCAG AA contrast) in both light and dark themes. The existing e2e CI job picks it up with no workflow change.
• src/app/page.tsx — the template's one page models correct usage (Eyebrow, .t-h1/.t-lead/.t-caption), since agents pattern-match on existing code.

Two things worth a reviewer's attention

The contract spec is .mts, not .ts. The helper is ESM-only, and Playwright compiles a plain .ts spec to CJS, where the subpath fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Adding a require condition to that export map upstream would let the .ts form work.

The next/font variables moved from <body> to <html>. Dropping the @theme block also dropped --font-sans: var(--font-geist-sans), and the token's literal 'Geist' never matches next/font's generated family name — so the page silently rendered in system-ui. The family tokens are now repointed from an unlayered :root (tokens.css declares them unlayered, so anything in @layer base loses), which requires --font-geist-sans to exist at :root. Geist now carries through tokens.css's own body rule, the .t-* classes, and Tailwind's font-sans — previously only body had it.

Verification

• pnpm build, pnpm lint, pnpm type-check, pnpm format:check, pnpm test all clean. The new lint rule was probed with a throwaway file: it caught a hex color, a rounded-[7px], and a raw boxShadow.
• pnpm test:e2e --project=chromium against pnpm build && pnpm start: 4/4 passed, including both contract tests.
• In-browser: bg-background resolves to var(--bg), fonts resolve to Geist, "Geist Fallback", data-theme="dark" flips the page, no console errors.

🤖 Generated with Claude Code