Build with AI

Prompt: add a new component to the design system

Fill in the bracketed fields, then hand this whole file to the agent.

Add a [ComponentName] component to @elirobinson/react.

What it should do: [one paragraph — the job this component does and the states it has. If it maps to a shadcn/ui component, name it.]

Intent

The component must feel native to the Miltinson system: token-styled, keyboard-complete, and documented. shadcn/ui is the reference for API shape and accessibility patterns only — never its styles and never a Tailwind dependency.

Context to load first

• docs/agents/components.md — tier boundary rule, touch-target policy, shadcn adoption policy, FormField-vs-Input precedent.
• @elirobinson/ai-patterns/contracts (componentConstraints) — the machine-checkable rules you are subject to.
• design-system-docs/preview/ in this repo, or the packed brand skill in a consuming one (.claude/skills/miltinson-design/) — the canonical look of buttons, fields, cards, and tags. pnpm --package=@elirobinson/ai-patterns dlx ds-resync artifacts --write puts it there.
• Two existing components in the target tier, read end to end, as the pattern to match.

Constraints

• Place it by the tier boundary rule, asking the domain question first: no meaning outside an assistant surface → ai/; otherwise portal/focus-trap/multi-element open state → organisms/; assembled from 2+ atoms without that → molecules/; else atoms/. ai/ is the only tier keyed to what a component is for rather than how much it assembles, and it buys a directory and nothing else — every other constraint below still applies.
• forwardRef to the outermost interactive element it owns.
• Touch targets by role: 44×44px minimum for primary controls; shadcn/MUI dense scale for inline affordances; an expanded hit area must never overlap sibling content.
• Styles in a sibling <Name>.css using only --* tokens via ds-* classes; add its @import to packages/react/src/styles.css at the end of the cascade — never reorder existing lines.
• Keyboard behavior via the shared hooks (useRovingFocus, useActiveDescendant, useEscapeKey, useClickOutside, useAnchoredPosition) before writing new key handlers.
• No barrel files: the component is consumed as @elirobinson/react/components/<tier>/<Name>.
• No new runtime dependencies without explicit sign-off.

Verification checklist

• pnpm build && pnpm lint && pnpm typecheck && pnpm test pass from the repo root.
• Tests cover the keyboard contract the component claims (arrows/Escape/Home/End as applicable) — the test file is the contract's source of truth.
• A Storybook story exists in apps/storybook showing realistic usage.
• pnpm build picks the component up in @elirobinson/react's dist/manifest.json (generated, not committed) with no extraction gaps, and a docs page exists at /components/<slug> following the Button page's structure.
• Every color pairing introduced passes WCAG AA (compute it — don't eyeball it).
• Focus is visible on every interactive element; prefers-reduced-motion is not overridden.

Prompt: adopt the design system in an existing app

Fill in the bracketed fields, then hand this whole file to the agent.

Bring [app name / path] onto the Miltinson Design System (@elirobinson/tokens + @elirobinson/react).

Scope for this pass: [which routes/screens to migrate now; anything explicitly out of scope.]

Intent

Replace ad-hoc primitives and hardcoded style values with the system, without a big-bang rewrite — each step should leave the app shippable.

Context to load first

Do not work from a remembered or documented inventory — ask the installed packages:

pnpm ds                  # components, exports, variants, hooks, typography, token groups
pnpm ds props <Name>     # props, variant unions, and the exact import line to copy
pnpm ds tokens [filter]  # tokens and values
pnpm ds contracts        # the machine-checkable rules to enforce, and what verifies each
pnpm ds patterns         # working principles and the definition of done

pnpm exec elirobinson-ds works before the ds script exists.

Step 0 — wire up the tooling

Before migrating any screen, install the things that keep this from drifting back:

1. pnpm add @elirobinson/react@latest @elirobinson/tokens@latest and pnpm add -D @elirobinson/ai-patterns@latest @elirobinson/eslint-config@latest.

2. Add "ds": "elirobinson-ds" to scripts, so every instruction above resolves.

3. Extend the flat ESLint config with @elirobinson/eslint-config (and @elirobinson/eslint-config/css if the app has its own stylesheets). This is what makes the import bans and the no-hardcoded-values rule fail the build rather than depend on review.

4. pnpm ds init --agents — installs the Claude Code skill, the Cursor rule, the Copilot instructions, and an AGENTS.md block. Coverage matters: teammates drive different tools, and an agent only follows what it actually loads.

5. pnpm exec ds-resync artifacts --write — writes the brand skill and a version-stamped component reference (llms.txt, llms-full.txt) into .claude/skills/. Re-run it after any upgrade; it refreshes what it wrote and leaves anything you edited alone.

6. On Tailwind v4, add @import '@elirobinson/tokens/tailwind.css' after the tokens import. Without it, bg-background and friends resolve to nothing.

7. If the framework supplies the fonts — next/font and friends — re-point the families at its variables, or the app silently renders in the system font:

   Copy

   :root {
     --ds-font-sans-override: var(--font-geist-sans);
     --ds-font-mono-override: var(--font-geist-mono);
   }

   The font's class goes on <html>, not <body>: the tokens resolve at :root.

8. If the app has a theme switcher, point it at data-theme (next-themes: attribute="data-theme").

9. Drop expectDesignSystemContracts from @elirobinson/ai-patterns/testing/playwright into the E2E suite for the routes in scope.

Constraints

• Work in the documented order: (1) swap primitive buttons/inputs/cards for system components, (2) move style values onto --* tokens, (3) keyboard and focus pass.
• Imports use package subpaths only — @elirobinson/react/components/<tier>/<Name> — a bare @elirobinson/react import does not resolve.
• @elirobinson/tokens/tokens.css and @elirobinson/react/styles.css are imported once, in the app shell, in that order.
• Input/Textarea/Select require a label prop; do not wrap them in FormField (double labels). FormField is for controls without their own wiring.
• Reference semantic tokens (--fg, --surface, --accent) — never raw scale values (--ink-500) in app code.
• Any token override goes in an unlayered :root block. tokens.css is unlayered, and unlayered declarations beat layered ones whatever the order, so an override inside @layer base — the conventional place in a Next.js globals.css — will not apply, and nothing will say so.
• Spacing values snap to the --space-* scale; radii to --radius-*; no magic numbers survive the pass.
• Delete outline: none on focus wherever found — the token stylesheet's focus ring is non-negotiable.
• Do not restyle system components with overrides that fight the tokens; if a component can't do the job as shipped, report the gap instead of forking its styles.

Verification checklist

• The app builds and its existing tests pass after each of the three steps, not just at the end.
• pnpm lint passes with @elirobinson/eslint-config enabled — that is the check for hardcoded values and stray imports, rather than a grep whose exceptions nobody revisits.
• The Playwright contract check passes on every migrated route: touch targets, visible focus, and WCAG AA contrast.
• Every migrated screen is fully operable with the keyboard alone.
• Every migrated screen renders correctly under data-theme="dark".
• The full checklist in pnpm ds patterns — Definition of Done for UI work — holds.
• A short migration report: what was swapped, what was left, and any place the system was missing a component the app needed.

Prompt: audit a page for token and accessibility compliance

Fill in the bracketed fields, then hand this whole file to the agent.

Audit [route or file path] in [app] against the Miltinson Design System's contracts. Report findings; fix only what's listed under "fix directly" below.

Intent

A page that uses the system should be provably on-system: token-clean, AA-contrast, keyboard-complete. This audit produces a findings list a maintainer can act on — honest about severity, free of nitpicks dressed up as blockers.

Context to load first

• @elirobinson/ai-patterns/contracts — uiContracts and componentConstraints are the rulebook; cite the constraint id in every finding.
• pnpm ds tokens and pnpm ds props <Name> — token names/values and each component's documented accessibility contract, read from the installed package. For a bulk read, .claude/skills/design-system-reference/llms-full.txt, which pnpm --package=@elirobinson/ai-patterns dlx ds-resync artifacts --write writes and refreshes.

What to check

1. Imports — every @elirobinson/* import names a subpath (no-barrel-imports); flag any deep import into package internals.
2. Tokens — hardcoded colors, px spacing, radii, shadows, or durations that have a token equivalent; raw scale tokens (--ink-500) where a semantic token belongs.
3. Contrast — compute WCAG ratios for text/background pairings introduced by the page; AA is the floor (4.5:1 normal text, 3:1 large).
4. Touch targets — touch-target-primary (44×44px) for buttons/pagination/nav items; touch-target-dense (24×24px, WCAG 2.2 AA SC 2.5.8) for chip-remove/clear/stars/day-cells, size="sm" buttons and chip controls — a floor, not an exemption, so measure them too; hit-area-no-overlap everywhere (check computed geometry, not intent).
5. Keyboard and focus — tab reach and order, visible :focus-visible on every control, Escape/arrow behavior matching each component's documented contract, focus return on overlay close, no outline: none.
6. Semantics — labels on every control (aria-label on icon-only buttons), one h1, sane heading order, alt on images, live regions only where the system provides them.
7. Functional copy (ui-copy) — errors, empty states, helper and hint text, toasts, labels, button text, tooltips, confirmations, validation: fact, then consequence, then action, then stop. Flag frequency claims, blame attribution, filler pacing, unprompted reassurance or apology, unasked escalation, and exclamation marks. Editorial content is out of scope — marketing prose, conversational surfaces, and written deliverables carry the product's deliberate voice; do not report them.

Constraints

• Fix directly: token substitutions with identical rendered results, missing aria-labels, outline: none deletions.
• Report, don't fix: layout changes, color changes that alter the design, component swaps, anything touching behavior, and every wording change — quote the padded copy and the replacement, and let the author take the call on which side of the line it sits.
• Every finding cites the file/line, the constraint id, and the concrete fix.
• No hype, no padding — if the page is clean, say it's clean.

Verification checklist

• Findings each carry: location, constraint id, severity (blocker / should-fix / note), and a concrete remedy.
• Contrast claims include the computed ratio, not an adjective.
• The app builds and tests pass after the direct fixes.
• The report ends with the three most valuable fixes, ranked.