agentic-react-starter

React 19 · Vite 8 · TypeScript 6 · MIT

Turn a knob. The whole page follows.

This page is wired to the same three-layer token system the starter ships — nineteen values in one file drive every colour, radius, duration and control height you can see, including this sentence. Drag something. Nothing here is a screenshot.

Layer 0 — the knobs brand.css
123
0.065
0.625rem
1
0.4
1
6 of 19 knobs shown

The differentiator

An agent that cannot verify is an agent that guesses.

Most starters hand an agent a component library it can only use from the outside. This one closes the loop: every rule that matters is machine checkable, and the whole suite runs in about eleven seconds — short enough that there is no excuse to skip it.

6s pnpm check Types, lint, design tokens and 27 unit tests.
5s pnpm e2e 20 Playwright tests against a production build.
0.17s pnpm check:tokens Also fires from an editor hook on every file the agent edits.
0 axe violations Every route in the nav, scanned in both themes. It found four real ones.

How it holds together

Four layers, each referencing only the one above it.

That constraint is the whole trick. A literal value anywhere below layer 0 is a leak, and a leak is why most design systems stop responding to their own theme file.

00 design-system/brand.css The 19 knobs you edit. The only file a new project needs to touch.
01 design-system/tokens.css OKLCH ramps, control heights and durations — derived, never authored.
02 design-system/theme.css Meaning: --ds-surface, --ds-accent. One light-dark() pair covers both themes and follow-the-OS.
03 styles/index.css Tailwind v4 utilities: bg-surface, text-fg-muted.

Enforced, not documented

Six ways a component quietly stops responding to the brand.

Each one produces UI that looks correct today and silently ignores brand.css tomorrow. Prose in a style guide cannot catch them, so check:tokens fails the build instead.

Exit code 1, with file, line, column and the token to reach for instead.
Rejected Because
#3f8f5e A hex literal bypasses the semantic tokens entirely.
rgb() · hsl() Same, and it will not follow a hue change.
bg-slate-800 Tailwind's built-in palette never rethemes.
p-[13px] An arbitrary pixel value escapes the density and type scales.
duration-150 A literal duration ignores --brand-motion, so it still animates in a brand that asked for none.
duration-[--x] Tailwind v3 syntax. In v4 it emits invalid CSS the browser drops, and the style silently does nothing.

The agent layer

Context an agent reads before it writes.

Five project skills

The design system, UI standards, React patterns, testing, and the routing workflow — each written to be loaded at the moment it applies.

A PostToolUse hook

Checks design tokens on every file the agent edits, so a violation lands in the tool result rather than at the end of the task.

/new-component

Runs the component recipe end to end — checks it should exist, builds on a Base UI primitive, writes the test, then verifies.

Four test archetypes

A CVA component, a portalled Base UI wrapper, a form field with Zod, and a query with optimistic rollback. Meant to be copied, not reinvented.

CodeGraph over MCP

The repo indexed as a queryable graph, so the agent traces callers and blast radius instead of grepping.

One mock API, two consumers

MSW handlers serve the running app and Vitest from a single source, so a test and the real screen cannot disagree.

Clone to your own app

No component library to fight.

Every component is source in the repo, built on Base UI headless primitives — they supply focus management, keyboard navigation and ARIA wiring; the styling and the API are yours. When the examples have served their purpose, pnpm reset strips them and leaves the infrastructure.

$ git clone https://github.com/swapnil-saal/agentic-react-starter
$ pnpm install && cp .env.example .env
$ pnpm doctor // verifies the agent toolchain
$ pnpm dev
 
$ pnpm check
design tokens: no violations
27 passed (5 files)