BMAD-METHOD/bmad-core/templates/front-end-architecture-tmpl.yaml

template:
  id: frontend-architecture-template-v2
  name: Frontend Architecture Document
  version: 2.0
  output:
    format: markdown
    filename: docs/ui-architecture.md
    title: "{{project_name}} Frontend Architecture Document"

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: template-framework-selection
    title: Template and Framework Selection
    instruction: |
      Review provided documents including PRD, UX-UI Specification, and main Architecture Document. Focus on extracting technical implementation details needed for AI frontend tools and developer agents. Ask the user for any of these documents if you are unable to locate and were not provided.

      Before proceeding with frontend architecture design, check if the project is using a frontend starter template or existing codebase:

      1. Review the PRD, main architecture document, and brainstorming brief for mentions of:
         - Frontend starter templates (e.g., Create React App, Next.js, Vite, Vue CLI, Angular CLI, etc.)
         - UI kit or component library starters
         - Existing frontend projects being used as a foundation
         - Admin dashboard templates or other specialized starters
         - Design system implementations

      2. If a frontend starter template or existing project is mentioned:
         - Ask the user to provide access via one of these methods:
           - Link to the starter template documentation
           - Upload/attach the project files (for small projects)
           - Share a link to the project repository
         - Analyze the starter/existing project to understand:
           - Pre-installed dependencies and versions
           - Folder structure and file organization
           - Built-in components and utilities
           - Styling approach (CSS modules, styled-components, Tailwind, etc.)
           - State management setup (if any)
           - Routing configuration
           - Testing setup and patterns
           - Build and development scripts
         - Use this analysis to ensure your frontend architecture aligns with the starter's patterns

      3. If no frontend starter is mentioned but this is a new UI, ensure we know what the ui language and framework is:
         - Based on the framework choice, suggest appropriate starters:
           - React: Create React App, Next.js, Vite + React
           - Vue: Vue CLI, Nuxt.js, Vite + Vue
           - Angular: Angular CLI
           - Or suggest popular UI templates if applicable
         - Explain benefits specific to frontend development

      4. If the user confirms no starter template will be used:
         - Note that all tooling, bundling, and configuration will need manual setup
         - Proceed with frontend architecture from scratch

      Document the starter template decision and any constraints it imposes before proceeding.
    sections:
      - id: changelog
        title: Change Log
        type: table
        columns: [Date, Version, Description, Author]
        instruction: Track document versions and changes

  - id: frontend-tech-stack
    title: Frontend Tech Stack
    instruction: Extract from main architecture's Technology Stack Table. This section MUST remain synchronized with the main architecture document.
    elicit: true
    sections:
      - id: tech-stack-table
        title: Technology Stack Table
        type: table
        columns: [Category, Technology, Version, Purpose, Rationale]
        instruction: Fill in appropriate technology choices based on the selected framework and project requirements.
        rows:
          - ["Framework", "{{framework}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["UI Library", "{{ui_library}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - [
              "State Management",
              "{{state_management}}",
              "{{version}}",
              "{{purpose}}",
              "{{why_chosen}}",
            ]
          - ["Routing", "{{routing_library}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["Build Tool", "{{build_tool}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["Styling", "{{styling_solution}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["Testing", "{{test_framework}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - [
              "Component Library",
              "{{component_lib}}",
              "{{version}}",
              "{{purpose}}",
              "{{why_chosen}}",
            ]
          - ["Form Handling", "{{form_library}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["Animation", "{{animation_lib}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]
          - ["Dev Tools", "{{dev_tools}}", "{{version}}", "{{purpose}}", "{{why_chosen}}"]

  - id: project-structure
    title: Project Structure
    instruction: Define exact directory structure for AI tools based on the chosen framework. Be specific about where each type of file goes. Generate a structure that follows the framework's best practices and conventions.
    elicit: true
    type: code
    language: plaintext

  - id: component-standards
    title: Component Standards
    instruction: Define exact patterns for component creation based on the chosen framework.
    elicit: true
    sections:
      - id: component-template
        title: Component Template
        instruction: Generate a minimal but complete component template following the framework's best practices. Include TypeScript types, proper imports, and basic structure.
        type: code
        language: typescript
      - id: naming-conventions
        title: Naming Conventions
        instruction: Provide naming conventions specific to the chosen framework for components, files, services, state management, and other architectural elements.

  - id: state-management
    title: State Management
    instruction: Define state management patterns based on the chosen framework.
    elicit: true
    sections:
      - id: store-structure
        title: Store Structure
        instruction: Generate the state management directory structure appropriate for the chosen framework and selected state management solution.
        type: code
        language: plaintext
      - id: state-template
        title: State Management Template
        instruction: Provide a basic state management template/example following the framework's recommended patterns. Include TypeScript types and common operations like setting, updating, and clearing state.
        type: code
        language: typescript

  - id: api-integration
    title: API Integration
    instruction: Define API service patterns based on the chosen framework.
    elicit: true
    sections:
      - id: service-template
        title: Service Template
        instruction: Provide an API service template that follows the framework's conventions. Include proper TypeScript types, error handling, and async patterns.
        type: code
        language: typescript
      - id: api-client-config
        title: API Client Configuration
        instruction: Show how to configure the HTTP client for the chosen framework, including authentication interceptors/middleware and error handling.
        type: code
        language: typescript

  - id: routing
    title: Routing
    instruction: Define routing structure and patterns based on the chosen framework.
    elicit: true
    sections:
      - id: route-configuration
        title: Route Configuration
        instruction: Provide routing configuration appropriate for the chosen framework. Include protected route patterns, lazy loading where applicable, and authentication guards/middleware.
        type: code
        language: typescript

  - id: styling-guidelines
    title: Styling Guidelines
    instruction: Define styling approach based on the chosen framework.
    elicit: true
    sections:
      - id: styling-approach
        title: Styling Approach
        instruction: Describe the styling methodology appropriate for the chosen framework (CSS Modules, Styled Components, Tailwind, etc.) and provide basic patterns.
      - id: global-theme
        title: Global Theme Variables
        instruction: Provide a CSS custom properties (CSS variables) theme system that works across all frameworks. Include colors, spacing, typography, shadows, and dark mode support.
        type: code
        language: css

  - id: testing-requirements
    title: Testing Requirements
    instruction: Define minimal testing requirements based on the chosen framework.
    elicit: true
    sections:
      - id: component-test-template
        title: Component Test Template
        instruction: Provide a basic component test template using the framework's recommended testing library. Include examples of rendering tests, user interaction tests, and mocking.
        type: code
        language: typescript
      - id: testing-best-practices
        title: Testing Best Practices
        type: numbered-list
        items:
          - "**Unit Tests**: Test individual components in isolation"
          - "**Integration Tests**: Test component interactions"
          - "**E2E Tests**: Test critical user flows (using Cypress/Playwright)"
          - "**Coverage Goals**: Aim for 80% code coverage"
          - "**Test Structure**: Arrange-Act-Assert pattern"
          - "**Mock External Dependencies**: API calls, routing, state management"

  - id: environment-configuration
    title: Environment Configuration
    instruction: List required environment variables based on the chosen framework. Show the appropriate format and naming conventions for the framework.
    elicit: true

  - id: frontend-developer-standards
    title: Frontend Developer Standards
    sections:
      - id: critical-coding-rules
        title: Critical Coding Rules
        instruction: List essential rules that prevent common AI mistakes, including both universal rules and framework-specific ones.
        elicit: true
      - id: quick-reference
        title: Quick Reference
        instruction: |
          Create a framework-specific cheat sheet with:
          - Common commands (dev server, build, test)
          - Key import patterns
          - File naming conventions
          - Project-specific patterns and utilities