Frontend Architect Agent

Overview

The Frontend Architect agent is a specialized AI agent designed to help with frontend architecture decisions, component design, performance optimization, and modern frontend development patterns.

When to Use This Agent

Invoke this agent when you need:

• Architecture Design: Component hierarchy, folder structure, state management strategy
• Framework Selection: Choosing between React/Next.js, Vue/Nuxt, or Angular
• Performance Optimization: Code splitting, lazy loading, bundle optimization
• Design System Implementation: Atomic Design, component libraries, theming
• Migration Planning: React Pages → App Router, Vue 2 → Vue 3, JavaScript → TypeScript
• Micro-Frontend Architecture: Module Federation, Single-SPA, independent deployments
• Testing Strategy: Unit, integration, E2E testing setup for frontend
• Build Configuration: Vite, Webpack, Turbopack setup and optimization
• SEO & Accessibility: Server-side rendering, metadata, WCAG compliance

How to Invoke

Use the Task tool with subagent_type:

Task({
  subagent_type: "specweave-frontend:frontend-architect:frontend-architect",
  prompt: "Design a component architecture for a dashboard application with real-time data updates"
});

Agent Capabilities

1. Framework Expertise

React Ecosystem:

• React 18+ with Concurrent features
• Next.js 14+ App Router and Server Components
• State management (Zustand, Redux Toolkit, Jotai, React Query)
• Custom Hooks patterns

Vue Ecosystem:

• Vue 3 Composition API
• Nuxt 3 with Nitro engine
• Pinia state management
• Composables and auto-imports

Angular Ecosystem:

• Angular 17+ with standalone components
• Signals for reactivity
• RxJS reactive programming
• NgRx state management

2. Architecture Patterns

• Atomic Design: Organize components by complexity (Atoms → Molecules → Organisms → Templates → Pages)
• Compound Components: Flexible component composition
• Smart vs Presentational: Separation of concerns
• Micro-Frontends: Module Federation, Single-SPA
• Design Systems: Token architecture, multi-brand support

3. Performance Optimization

• Code splitting strategies (route-based, component-based)
• Lazy loading and dynamic imports
• Bundle optimization (tree shaking, vendor splitting)
• Image optimization (next/image, responsive images)
• Core Web Vitals (LCP, FID, CLS)
• Virtual scrolling for large lists

4. Build & Tooling

• Vite for lightning-fast development
• Webpack 5 with Module Federation
• Turbopack (Next.js)
• TypeScript strict mode configuration
• ESLint + Prettier + Husky

5. Testing

• Vitest for unit testing
• React/Vue Testing Library
• Playwright for E2E
• MSW for API mocking
• Storybook for component development

6. Styling Approaches

• CSS-in-JS (styled-components, Emotion, Vanilla Extract)
• Utility-first (TailwindCSS, UnoCSS)
• CSS Modules with composition
• Modern CSS (Variables, Container Queries, Cascade Layers)

7. SEO & Accessibility

• Server-side rendering strategies
• Metadata API (Next.js)
• Structured data (JSON-LD)
• ARIA labels and roles
• Keyboard navigation
• WCAG AA/AAA compliance

Common Use Cases

1. Scaffold New Frontend Project

Prompt:

"Set up a Next.js 14 App Router project with TypeScript, TailwindCSS, Zustand for state management, and Playwright for E2E testing"

What the agent provides:

• Project structure with best practices
• Configuration files (tsconfig, eslint, prettier)
• Base components and layouts
• Testing infrastructure setup
• Deployment pipeline configuration

2. Design Component Architecture

Prompt:

"Design a reusable DataTable component with sorting, filtering, pagination, and virtual scrolling for 10,000+ rows"

What the agent provides:

• Component hierarchy (Atomic Design)
• Props interface design
• State management approach
• Performance optimization strategy
• Usage examples and documentation

3. Optimize Performance

Prompt:

"Analyze and optimize a React dashboard application with slow initial load (5s+) and laggy interactions"

What the agent provides:

• Performance audit checklist
• Bundle size analysis approach
• Code splitting recommendations
• Lazy loading strategy
• Caching optimization
• Monitoring setup (Core Web Vitals)

4. Implement Design System

Prompt:

"Create a design system with support for light/dark themes, 3 brand colors, and consistent spacing/typography across 20+ components"

What the agent provides:

• Design token architecture
• Theme configuration system
• Base components (atoms, molecules)
• Storybook setup
• Documentation guidelines

5. Migration Strategy

Prompt:

"Plan migration from React Pages Router to App Router for a 50+ page e-commerce application"

What the agent provides:

• Incremental migration strategy
• Compatibility analysis
• Server Components adoption plan
• Data fetching migration
• Testing strategy
• Rollback plan

Example Workflows

Workflow 1: New Feature Development

1. Define Requirements: Describe the feature and constraints
2. Architecture Design: Agent designs component structure
3. Implementation Plan: Breaking down into tasks
4. Code Scaffolding: Generate initial component templates
5. Testing Strategy: Unit + integration + E2E test plan
6. Performance Review: Ensure Core Web Vitals targets met

Workflow 2: Performance Optimization

1. Current State Analysis: Measure existing metrics
2. Bottleneck Identification: Bundle size, render performance
3. Optimization Plan: Code splitting, lazy loading, caching
4. Implementation: Apply optimizations
5. Measurement: Compare before/after metrics
6. Monitoring: Set up ongoing tracking

Workflow 3: Design System Creation

1. Audit Existing Components: Identify patterns and inconsistencies
2. Define Design Tokens: Colors, typography, spacing, shadows
3. Create Base Components: Atoms (Button, Input, Icon)
4. Build Composite Components: Molecules (Form Field, Card)
5. Document Usage: Storybook with examples
6. Migration Plan: Adopt design system across codebase

Input Format

The agent expects a clear, specific prompt describing:

1. Context: What are you building? What framework?
2. Requirements: What features/constraints?
3. Goals: Performance targets, accessibility needs, SEO requirements
4. Constraints: Team size, timeline, existing tech stack

Good prompt:

"Design a React dashboard for financial data visualization with:
- Real-time WebSocket updates
- 10+ chart types (using D3.js)
- Responsive design (mobile, tablet, desktop)
- Dark mode support
- Target LCP < 2.5s
- Accessibility WCAG AA compliant
Existing stack: Next.js 14, TypeScript, TailwindCSS"

Poor prompt:

"Make a dashboard"

Output Format

The agent provides:

1. Architecture Overview: High-level structure and decisions
2. Component Hierarchy: Atomic Design breakdown
3. Technology Recommendations: Libraries, tools, patterns
4. Implementation Plan: Step-by-step tasks
5. Code Examples: Scaffolding and patterns
6. Testing Strategy: Unit, integration, E2E approach
7. Performance Checklist: Optimization targets
8. Documentation: Usage guidelines

Best Practices

1. TypeScript First

Always use TypeScript with strict mode for type safety.

2. Component Composition

Prefer composition over inheritance for flexibility.

3. Performance Budgets

Monitor and enforce bundle size limits (e.g., < 200KB initial JS).

4. Accessibility

Build with a11y from the start, not as afterthought.

5. Testing Pyramid

More unit tests, fewer E2E tests (70% unit, 20% integration, 10% E2E).

6. Code Splitting

Split by routes and heavy components for faster initial load.

7. Progressive Enhancement

Ensure basic functionality without JavaScript.

8. Documentation

Document complex components in Storybook with examples.

Integration with SpecWeave

Use with /sw:increment

When planning a frontend feature increment:

# 1. Plan increment
/sw:increment "Design and implement responsive navigation with mega menu"

# 2. Generate architectural plan
Task({
  subagent_type: "specweave-frontend:frontend-architect:frontend-architect",
  prompt: "Design component architecture for responsive navigation with mega menu supporting 100+ menu items, search, and multi-level dropdowns"
});

# 3. Implement based on architectural plan
/sw:do

Use with /sw:qa

After implementation, validate architecture decisions:

# Run quality assessment
/sw:qa 0123

# Agent checks:
# - Component modularity
# - Performance metrics
# - Accessibility compliance
# - Code splitting effectiveness
# - Bundle size

Troubleshooting

Issue: Agent recommends outdated patterns

Solution: Specify framework version explicitly in prompt

"Using Next.js 14 App Router (NOT Pages Router), design..."

Issue: Recommendations too generic

Solution: Provide more context about constraints and requirements

"For a team of 3 developers with React experience, building a B2B SaaS dashboard with 50+ pages, using Next.js 14, TypeScript, and TailwindCSS..."

Issue: Performance recommendations unclear

Solution: Specify performance targets

"Target: LCP < 2.5s, FID < 100ms, CLS < 0.1, initial bundle < 200KB"

Advanced Usage

Micro-Frontend Architecture

Task({
  subagent_type: "specweave-frontend:frontend-architect:frontend-architect",
  prompt: `Design a micro-frontend architecture for an e-commerce platform with:
    - Product catalog (team A)
    - Shopping cart (team B)
    - Checkout flow (team C)
    - User profile (team D)
    Requirements:
    - Independent deployments per team
    - Shared design system
    - Module Federation (Webpack 5)
    - Cross-team communication via events`
});

Monorepo Setup

Task({
  subagent_type: "specweave-frontend:frontend-architect:frontend-architect",
  prompt: `Set up a Turborepo monorepo with:
    - 3 Next.js applications (marketing, dashboard, admin)
    - Shared UI component library (@acme/ui)
    - Shared utilities (@acme/utils)
    - Shared TypeScript config
    - Independent versioning per package
    - Build caching and parallel execution`
});

Resources

• React Docs: https://react.dev
• Next.js Docs: https://nextjs.org/docs
• Vue Docs: https://vuejs.org
• Angular Docs: https://angular.io
• Patterns.dev: https://patterns.dev (Modern web patterns)
• Web.dev: https://web.dev (Performance, accessibility)

Version History

• v1.0.0 (2025-01-22): Initial release with React, Vue, Angular expertise
• v1.1.0 (TBD): Add Svelte/SvelteKit support
• v1.2.0 (TBD): Add mobile framework support (React Native, Flutter)

Support

For issues or questions:

• GitHub Issues: https://github.com/anton-abyzov/specweave/issues
• Discord: https://discord.gg/specweave
• Documentation: https://spec-weave.com