| name | frontend-development |
| description | Use when building or structuring a React/Next.js + TypeScript + Tailwind frontend, choosing libraries, or wiring design tokens. Provides the opinionated blessed-library stack and the React-vs-Next decision, all on-token to DESIGN.md and accessible to WCAG AA. |
Frontend Development
Announce at start: "I'm using claude-engineer:frontend-development to build the frontend on the blessed stack."
React vs Next.js (default decision)
- Next.js (App Router) for marketing/content sites and content+app hybrids (SEO, RSC, server data).
- Vite SPA (React) for dashboards/SaaS behind auth and design-system/library work (no SEO need).
- Rule of thumb: anonymous crawler needs real content, or you need a server data layer → Next.js; everything behind a login and API-bound → Vite SPA.
Blessed libraries (June 2026 defaults - full table + versions in references/frontend-stack.md)
| Need | Default |
|---|
| UI primitives | shadcn/ui (own the code) over Radix/Base UI |
| Styling | Tailwind CSS v4 (@theme) + cva + tailwind-merge + clsx |
| Server/data state | TanStack Query (or Next server components/actions) |
| Client state | Zustand |
| Forms + validation | react-hook-form + Zod |
| Routing (non-Next) | React Router (TanStack Router if TS-first) |
| Tables | TanStack Table |
| Charts | Recharts (via shadcn charts) |
| Animation | motion (ex-Framer Motion) |
| Icons | lucide-react (+ custom typed SVG icons) |
| Toasts / cmd palette / DnD / upload | Sonner / cmdk / dnd-kit / react-dropzone + presigned uploads |
Non-negotiables
- On-token only - consume DESIGN.md tokens via Tailwind
@theme/CSS vars; no hardcoded values (claude-engineer:design-system).
- TypeScript strict - full strict flags (see reference); no
any escapes.
- WCAG AA by construction - semantic HTML, keyboard nav, focus management, ARIA, reduced-motion. This is a hard gate (
claude-engineer:testing-and-quality).
- Tested - Vitest + React Testing Library for components; Playwright for E2E flows.
- Monorepo placement - apps in
apps/, shared UI/config in packages/ (claude-engineer:monorepo-and-tooling).
Full detail: read references/frontend-stack.md (project structure, exact versions, tsconfig strict flags, ESLint flat config, token wiring, a11y checklist) on demand.
Red flags - STOP
- Reaching for a library outside the blessed list without a reason recorded in
docs/conventions.md.
- Inline styles / magic numbers instead of tokens.
- Building an interactive component that isn't keyboard-operable.
