Agentic React Starter — project guide

Vite + React 19 + TypeScript front-end with a design system you own, set up so an agent can navigate the repo structurally, extend the UI safely, and verify its own work.

Verify with one command

pnpm check     # typecheck + lint + design tokens + unit tests  (~6s)
pnpm e2e       # Playwright against a production build          (~5s)

Both are cheap — run them. The whole loop is about ten seconds, so there is no reason to skip pnpm e2e on anything visual, and no reason to guess whether a change worked. If the environment itself looks broken (missing CLI, stale index), run pnpm doctor.

A PostToolUse hook also runs the design-token checker against every file you edit under src/, so token violations come back in the tool result rather than at the end of the task.

Stack

There is no third-party component library. Do not add shadcn, MUI, Chakra, or similar. If a component is missing, build it on a Base UI primitive following the design-system skill.

Layout

src/
  design-system/   the UI library — you own every line
    brand.css        layer 0: THE knobs — edit this to restyle the app
    presets/         ready-made brand looks
    tokens.css       layer 1: scales, derived from brand.css (do not edit)
    theme.css        layer 2: semantic tokens
    ui/_motion.ts    the motion vocabulary every component composes from
    ADDING-A-COMPONENT.md   the recipe for new components
    ui/*.tsx         components
    index.ts         import from '@/design-system'
  routes/          file-based routes; __root.tsx is the app shell
                   users.*, form-demo are EXAMPLES — `pnpm reset` removes them
  routeTree.gen.ts GENERATED — never edit
  styles/index.css layer 3: semantic tokens → Tailwind utilities
  features/        feature modules — queries, mutations, domain types
  mocks/           MSW mock API — handlers.ts is served to the browser
                   (browser.ts) and to Vitest (server.ts) from one source
  lib/             env.ts (validated), api.ts (the only fetch wrapper),
                   app.ts (APP_NAME), query-client.ts
e2e/               Playwright specs — app.spec.ts and a11y.spec.ts survive
                   `pnpm reset`; examples.spec.ts does not
scripts/           doctor.mjs, check-tokens.mjs, reset.mjs, hook-check-tokens.mjs
.claude/skills/    project skills (see below)

Skills — read these before working

Try brand values live at /brand in the running app.

Hard rules

1. No hardcoded design values. No hex codes, no magic pixels, and no raw Tailwind palette classes (bg-slate-800, text-red-500) — they bypass the token system and will not respond to a retheme. Use semantic utilities (bg-surface, text-fg-muted) or component variants.
2. To restyle the app, edit src/design-system/brand.css — that file only. 19 knobs (hue, chroma, radius, border width, fonts, type scale, density, shadow, motion) drive everything else. tokens.css is derived output; do not put literal values in it. Never restyle at a call site.
3. Never edit src/routeTree.gen.ts.
4. Keep Input/Textarea event-first. Their native onChange is what makes register() from React Hook Form work. A value-first callback would break every uncontrolled form library.
5. Import UI from @/design-system, not from ui/* directly.
6. Validate at the edges with Zod (env, API responses, search params).
7. Tailwind v4 variables use parentheses: duration-(--x), not duration-[--x]. The bracket form emits invalid CSS and silently does nothing.
8. All motion comes from design-system/ui/_motion.ts. A literal duration ignores --brand-motion, so the component keeps animating in a brand that asked for none.
9. The app's name comes from package.json via APP_NAME in @/lib/app. Never hardcode it.
10. Every API call goes through api() in @/lib/api. It decides the base URL, the headers and the error shape once — including fieldErrors from a 422, which is what lets a form put each message back on its own field. A second hand-rolled fetch is how "something went wrong" reaches the UI.
11. A control that renders no text of its own must require a label. Use the Labelled type from design-system/ui/_a11y.ts, as Progress and Slider do, so an unlabelled call site is a compile error rather than an audit finding.

pnpm check:tokens enforces rules 1, 7 and 8 mechanically — hex codes, Tailwind palette classes, arbitrary pixel values, literal durations and the v3 variable syntax all fail the build. It also runs from a PostToolUse hook on every file you edit under src/, so a violation comes back in the tool result. When it flags something, reach for a token rather than adding an exception.

Rule 11 is enforced by the type system, and e2e/a11y.spec.ts runs an axe scan over every route in both themes — which is what catches the contrast failures a brand change can introduce without touching a component.

Tools available to you

CodeGraph (MCP, .mcp.json) — the repo is indexed as a queryable graph. Use codegraph_explore to trace callers, callees and blast radius before changing shared code — especially useful now that components are owned source and a change to one can ripple. CLI: codegraph query <symbol>, codegraph explore <question>, codegraph status.

Ponytail (plugin, project scope) — biases toward writing less code: reuse what exists, use the platform, prefer one line over ten. Safety, validation and accessibility are explicitly never traded away. /ponytail lite|full|ultra|off · /ponytail-review · /ponytail-audit · /ponytail-debt.

Commands

pnpm dev           # dev server
pnpm build         # typecheck + production build
pnpm check         # typecheck + lint + design tokens + tests
pnpm check:tokens  # design-system rule enforcement on its own
pnpm test          # vitest watch
pnpm e2e           # Playwright against a production build
pnpm lint:fix      # autofix
pnpm format        # Prettier
pnpm reset         # strip the example screens to start a real app
pnpm doctor        # verify + repair the agent toolchain
pnpm doctor:check  # report only (CI); exits non-zero on required failures

Environment

.env is validated by src/lib/env.ts at boot; a missing or malformed value fails immediately with a readable message rather than surfacing as undefined later. Add a variable in both the Zod schema and .env.example.

The app's display name is not an env var — it is derived from the name field in package.json so the project has exactly one name.