The Frontend Architect Inside Every Great Web Project
Meet the Claude agent that thinks like a senior engineer, codes like a craftsman, and ships production-grade UI — so you don't have to reinvent the wheel on every project.
How This Agent Thinks
The frontend-architect agent isn't a code autocomplete tool. It reasons through problems the way a senior engineer would on a real team: it asks where should this state live? before writing a line, considers the accessibility tree before picking an ARIA role, and always plans for loading, error, and empty states — not just the happy path.
Before every component, the agent answers five non-negotiable questions:
- Is this server or client? — the server/client boundary is decided upfront, not as an afterthought
- Where does state live? — server, URL, context, or local component state
- What is the loading and error UX? — every state is a first-class citizen
- Is this reusable or page-specific? — determines the abstraction level and prop contract
- Does it need optimistic updates? — mutation strategy is planned before any data layer is touched
This mental model produces output that's actually deployable — not scaffolding you still have to finish.
The four pillars of its reasoning
Architecture-first. Component tree, state location, and data flow are defined before a single JSX element is written. The agent always delivers an architecture section alongside the code.
Accessibility by default. Every component ships with correct ARIA roles, keyboard navigation, and focus management. Radix UI primitives are used for their accessibility tree guarantees, not just their convenience.
Edge-state aware. Loading, error, and empty states are part of the component contract — always covered, never left as a TODO.
Performance-minded. Re-render surfaces, memoization strategy, and code-splitting opportunities are flagged on every output. The agent doesn't just write working code; it explains what triggers re-renders and why.
What the Agent Can Do
From greenfield component design to deep integration work, this agent covers the full frontend surface area of a production application.
- Design and implement full component trees with strict TypeScript interfaces — no
any, no escape hatches - Set up Next.js App Router layouts:
loading.tsx,error.tsx, server/client boundaries, nested layouts - Build Refine.dev data-driven UIs with
useOne,useList, and resource-based routing - Author schema-driven forms with React Hook Form + Zod, using
z.input<typeof schema>correctly when schemas have.default() - Compose Radix UI primitives into fully accessible, ARIA-correct components with proper focus traps and keyboard interaction
- Wire up shadcn/ui with CVA variants — never brittle conditional
classNamestrings - Define CSS custom properties for Tailwind v4 token systems, without a
tailwind.config.js - Audit and optimize re-render surfaces, memoization boundaries, virtualization, and bundle size
Every output follows the same structure: Architecture → Accessibility → Performance → Types → Code → Edge cases. Nothing ships without all six.
Technologies the Agent Specializes In
The agent carries deep, production-tested expertise in each of these layers — not surface-level familiarity.
React 18+ and Next.js App Router
Server Components, Suspense boundaries, concurrent features, and transitions. The agent knows when to reach for use client, how to pass data through the server/client boundary without prop-drilling, and how to structure loading.tsx and error.tsx files for a coherent UX.
TypeScript
Generics, discriminated unions, template literal types, and branded types. Props are typed strictly — no optional props that should be required, no any that masks a missing contract. The agent uses z.input<> vs z.output<> intentionally and understands why they differ.
Tailwind CSS v4
CSS-first configuration via @import "tailwindcss" in index.css. No tailwind.config.js. CSS custom properties for theme tokens, @layer base/components/utilities for custom styles, and dark mode via a .dark class on <html>. Arbitrary values are a last resort — named CSS variables are created instead.
Radix UI and shadcn/ui
Radix primitives are composed for their accessibility guarantees: correct ARIA patterns, keyboard interaction, and focus management come for free. shadcn/ui components are manually installed and extended with CVA (Class Variance Authority) for variant-driven styling that scales.
Refine.dev
DataProvider, useOne, useList, useForm, and resource routing. The agent understands the read/write separation: reads go through the DataProvider, mutations go through the blockchain or service layer — never through Refine mutations when the provider is read-only.
React Hook Form + Zod
Schema-driven forms with end-to-end type safety. The agent always uses controlled components, never array index as a React key, and avoids useEffect for derived state by computing it during render.
Full technology stack at a glance:
React 18 · Next.js App Router · TypeScript · Tailwind CSS v4 · Radix UI · shadcn/ui · Refine.dev · React Hook Form · Zod · CVA · Vite · Accessibility
Adding the Agent to Your Project
The agent is defined as a YAML file inside .claude/agents/. Drop it into your repository root, populate the system prompt with your project's context, and it will understand your stack, your path aliases, and your provider order from day one.
1. Create the agent file
.claude/
agents/
frontend-architect.md
2. Paste the configuration
---
name: frontend-architect
description: Frontend architecture and UI engineering specialist. Use for Next.js/React component design, routing, layouts, providers, Tailwind CSS, Radix UI, Refine.dev integration, TypeScript type systems, state management, performance optimization, accessibility, and design system decisions. Invoke when building pages, components, hooks, providers, or any UI layer.
model: claude-sonnet-4-6
tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch
---
# paste your full system prompt here
# (the "You are the frontend architecture..." block)
3. Add your project context
The more project-specific context you provide in the system prompt, the more opinionated and accurate the output becomes. At minimum, include:
- Path aliases — e.g.
@/→src/ - Tailwind setup — v4 via
@import "tailwindcss"inindex.css, no config file - Provider order — e.g.
BrowserRouter → ThemeProvider → AuthProvider → Refine → AppRoutes - DataProvider location — and whether it supports mutations
- Auth context path — e.g.
src/contexts/AuthContext.tsx - Known Zod patterns — e.g. always use
z.input<typeof schema>when schema has.default()
4. Invoke it from Claude Code
# In your terminal, inside the project root
claude "Build a PostCard component using shadcn/ui
that handles loading, error, and empty states,
fully typed, with a Radix UI tooltip on the author avatar"
The agent reads your existing codebase through its Glob and Read tools, aligns with your current conventions, and outputs production-ready components with full architecture documentation.
Tip: The agent is designed to be a permanent team member, not a one-shot prompt. Keep its system prompt up to date as your stack evolves — new providers, new resource names, new conventions — and it will stay aligned with your codebase automatically.
Why It Works
Most AI coding tools produce components that look right but aren't. They skip accessibility, skip edge states, pick the wrong state location, and leave type safety as an exercise for the reader.
The frontend-architect agent is opinionated by design. It has a checklist, it follows it on every single output, and it explains its decisions so you can push back when the context calls for something different. That's what makes it a collaborator rather than a code generator.
Drop it into your project once. Let it own the frontend layer. Ship faster.