Build with AI

import contracts from '@elirobinson/ai-patterns/contracts';

// contracts.componentConstraints['touch-target-primary'].summary
// contracts.componentConstraints['no-barrel-imports'].check

# 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.
- The docs site's `/llms-full.txt` (or `design-system-docs/preview/` in this repo) — the
  canonical look of buttons, fields, cards, and tags.
- Two existing components in the target tier, read end to end, as the pattern to match.

## Constraints

- Place it by the tier boundary rule: portal/focus-trap/multi-element open state →
  `organisms/`; assembled from 2+ atoms without that → `molecules/`; else `atoms/`.
- `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.
- [ ] The docs build (`pnpm nx run docs:build`) picks the component up in
      `component-manifest.json` 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

- The docs site's `/llms-full.txt` — component inventory with exact import subpaths and
  prop tables, token names with values, and the system constraints.
- `@elirobinson/ai-patterns/contracts` — the machine-checkable rules to enforce.

## 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.
- 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.
- [ ] No hardcoded hex/px style values remain in the migrated scope (grep for `#`, `px`
      values outside token definitions, and inline `style=` blocks; list justified
      exceptions).
- [ ] Every migrated screen is fully operable with the keyboard alone, with visible focus
      throughout.
- [ ] Touch targets follow the scoped policy — 44×44px primary controls, dense scale for
      inline affordances, no overlapping hit areas.
- [ ] 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.
- The docs site's `/llms-full.txt` — token names/values and each component's documented
  accessibility contract.

## 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` for chip-remove/clear/stars/day-cells;
   `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.

## Constraints

- **Fix directly:** token substitutions with identical rendered results, missing
  `aria-label`s, `outline: none` deletions.
- **Report, don't fix:** layout changes, color changes that alter the design, component
  swaps, anything touching behavior.
- 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.