bmad-agent-init/dist/bmad-agent/checklists/frontend-architecture-checklist.md

Windsurf integration for BMAD-METHOD - automatic initialization of bmad-agent in projects

# Frontend Architecture Document Review Checklist

## Purpose
This checklist is for the Design Architect to use after completing the "Frontend Architecture Mode" and populating the `front-end-architecture-tmpl.txt` (or `.md`) document. It ensures all sections are comprehensively covered and meet quality standards before finalization.

---

## I. Introduction

- [ ] Is the `{Project Name}` correctly filled in throughout the Introduction?
- [ ] Is the link to the Main Architecture Document present and correct?
- [ ] Is the link to the UI/UX Specification present and correct?
- [ ] Is the link to the Primary Design Files (Figma, Sketch, etc.) present and correct?
- [ ] Is the link to a Deployed Storybook / Component Showcase included, if applicable and available?

## II. Overall Frontend Philosophy & Patterns

- [ ] Are the chosen Framework & Core Libraries clearly stated and aligned with the main architecture document?
- [ ] Is the Component Architecture (e.g., Atomic Design, Presentational/Container) clearly described?
- [ ] Is the State Management Strategy (e.g., Redux Toolkit, Zustand) clearly described at a high level?
- [ ] Is the Data Flow (e.g., Unidirectional) clearly explained?
- [ ] Is the Styling Approach (e.g., CSS Modules, Tailwind CSS) clearly defined?
- [ ] Is the API Communication Style (e.g., REST, GraphQL) clearly stated?
- [ ] Are Key Design Principles (e.g., Mobile-first, Reusability) listed?

## III. Detailed Frontend Directory Structure

- [ ] Is the proposed directory structure clearly represented (e.g., tree format)?
- [ ] Is the purpose of each top-level and key second-level directory explained?
- [ ] Is the rationale for key structural choices (e.g., feature-slicing) provided?
- [ ] Does the structure include standard folders like `components`, `pages`, `services`, `store`, `hooks`, `utils`, `assets`, `styles`, `types` (as applicable)?
- [ ] Is the location for `public` assets and configuration files (e.g., `tsconfig.json`, `vite.config.js`) shown?

## IV. Component Breakdown & Implementation Details

- [ ] Are Component Naming Conventions (PascalCase, kebab-case) defined?
- [ ] Is the Directory Structure per Component (e.g., `Button/Button.tsx`, `Button.module.css`) specified?
- [ ] Is Storybook Integration (requirement for stories) mentioned?
- [ ] Is a `Template for Component Specification` provided and comprehensive?
  - [ ] Does the template include: Purpose, Location, Type, Parent/Child Components, Props Interface, Internal State, Key Functionality, Accessibility Notes, Storybook Scenarios, Visual Reference?
- [ ] Is there a list of Key Reusable Components with their purposes?
- [ ] Is there a list of Key Feature Components/Modules with their purposes?

## V. State Management In-Depth

- [ ] Is the Chosen Library & Rationale (e.g., Redux Toolkit, Zustand) reiterated and justified?
- [ ] Is the Overall State Shape (high-level RootState interface) illustrated?
- [ ] For each State Slice:
  - [ ] Is its Purpose clearly defined?
  - [ ] Is the Initial State structure shown?
  - [ ] Are Key Data Points described?
- [ ] Are Key Selectors (with types and descriptions) listed?
- [ ] Are Key Actions / Reducers / Thunks (with descriptions) listed?
  - [ ] Are synchronous actions detailed?
  - [ ] Is the logic for reducers (especially with `createSlice`) explained for key actions?
  - [ ] Are async thunks (e.g., for API calls) and their dispatched actions described?

## VI. API Interaction Layer

- [ ] Is the Library/Method (e.g., Axios, Fetch wrapper) specified?
- [ ] Is Base URL Configuration (for different environments) explained?
- [ ] Is Authentication Header management (e.g., JWT interceptor) detailed?
- [ ] Is the Client/Service Structure (e.g., dedicated service files per resource) shown with an example?
- [ ] Is Global Error Handling (e.g., interceptor for 401s) described?
- [ ] Is Local Error Handling within components discussed?
- [ ] Is a Retry Strategy for failed requests mentioned (if any)?
- [ ] Is Error Reporting to a monitoring service (e.g., Sentry) covered?

## VII. Routing Strategy

- [ ] Is the Routing Library (e.g., React Router, Next.js Router) specified?
- [ ] Is the Routing Philosophy (e.g., centralized config, file-system based) stated?
- [ ] Is there a table of Route Definitions including: Path, Component, Layout, Auth Required, Roles?
- [ ] Is the Authentication Guard mechanism explained?
- [ ] Is the Authorization/Role Guard mechanism explained (if applicable)?
- [ ] Is Lazy Loading for page components discussed?

## VIII. Build, Bundling, and Deployment

- [ ] Is the Build Tool (e.g., Vite, Webpack) specified?
- [ ] Are Key Build Scripts (dev, build, preview, lint, test) listed from `package.json`?
- [ ] Are Key Bundling Optimizations covered?
  - [ ] Code Splitting (e.g., route-based)?
  - [ ] Tree Shaking?
  - [ ] Minification (JS, CSS, HTML)?
  - [ ] Asset Optimization (images, fonts)?
  - [ ] Caching Strategies (content hashing)?
- [ ] Is Environment Configuration (e.g., `.env` files) detailed?
  - [ ] Are key environment variables listed (e.g., `VITE_API_BASE_URL`)?
  - [ ] Is access in code shown (e.g., `import.meta.env.VITE_...`)?

## IX. Testing Approach

- [ ] Is the Overall Testing Strategy (e.g., testing pyramid) described?
- [ ] Are Frameworks & Libraries for Unit/Integration (e.g., Vitest, RTL) and E2E (e.g., Cypress) listed?
- [ ] Is the Mocking strategy (e.g., MSW, Jest mocks) mentioned?
- [ ] For Unit Testing:
  - [ ] Is Scope (individual functions, components) defined?
  - [ ] Is Focus (rendering, event handlers) clear?
  - [ ] Is Location of tests (`*.test.tsx`) specified?
- [ ] For Integration Testing:
  - [ ] Is Scope (multiple components, state interaction) defined?
  - [ ] Is Focus (data flow, feature modules) clear?
- [ ] For End-to-End (E2E) Testing:
  - [ ] Is Scope (critical user flows) defined?
  - [ ] Is Focus (user scenarios) clear?
- [ ] Is Code Coverage (tool, target percentage, reporting) addressed?

## X. Accessibility (A11y) Plan

- [ ] Is the Target WCAG Standard (e.g., 2.1 AA) specified?
- [ ] Is adherence to POUR principles mentioned?
- [ ] Is Semantic HTML usage emphasized?
- [ ] Is appropriate ARIA attribute usage (for dynamic content/custom components) discussed?
- [ ] Is a plan for Color Contrast and Visual Cues included?
- [ ] Are requirements for Alternative Text for images stated?
- [ ] Is ARIA Implementation (roles, states, properties for custom components) provided?
- [ ] Are requirements for Keyboard Navigation (all interactive elements focusable/operable) stated?
- [ ] Is Focus Management (for modals, dynamic content) addressed?
- [ ] Are Testing Tools for AX (e.g., Axe DevTools, Lighthouse) listed?
- [ ] Does this section align with AX requirements from the UI/UX Specification?

## XI. Performance Considerations

- [ ] Is Image Optimization (formats, responsive images, lazy loading) discussed?
- [ ] Is Code Splitting & Lazy Loading (impact on perceived performance) reiterated if necessary?
- [ ] Are techniques for Minimizing Re-renders (e.g., `React.memo`) mentioned?
- [ ] Is the use of Debouncing/Throttling for event handlers considered?
- [ ] Is Virtualization for long lists/large data sets mentioned if applicable?
- [ ] Are Client-Side Caching Strategies (browser cache, service workers) discussed if relevant?
- [ ] Are Performance Monitoring Tools (e.g., Lighthouse, DevTools) listed?

## XII. Change Log

- [ ] Is the Change Log table present and initialized?
- [ ] Is there a process for updating the change log as the document evolves?

---

## Final Review Sign-off

- [ ] Have all placeholders (e.g., `{Project Name}`, `{e.g., ...}`) been filled in or removed where appropriate?
- [ ] Has the document been reviewed for clarity, consistency, and completeness by the Design Architect?
- [ ] Are all linked documents (Main Architecture, UI/UX Spec) finalized or stable enough for this document to rely on?
- [ ] Is the document ready to be shared with the development team?