First-Time Setup
+Clear, concise instructions...
+ +Environment Configuration
+Step-by-step guidance...
+Story 2.1: "How It Works" Documentation
+ 13 points
+
+
+```
+
+### CSS Classes
+```css
+/* Base component */
+.component-name { }
+
+/* Component parts */
+.component-name__part { }
+
+/* Modifiers */
+.component-name--variant { }
+.component-name--size { }
+
+/* States */
+.component-name:hover { }
+.component-name:focus { }
+.component-name.is-disabled { }
+```
+
+### React Implementation
+```jsx
+import { ComponentName } from '@/components/ui/component-name'
+
+// Basic usage
+
+ Content
+
+
+ {/* Component JSX */}
+
+ );
+};
+
+export default ComponentName;
+```
+
+#### Project Structure Template
+
+```
+project-name/
+├── src/
+│ ├── components/
+│ │ ├── common/
+│ │ │ └── [shared components]
+│ │ ├── features/
+│ │ │ └── [feature-specific components]
+│ │ └── layouts/
+│ │ └── [layout components]
+│ ├── hooks/
+│ │ └── [custom hooks]
+│ ├── utils/
+│ │ └── [utility functions]
+│ ├── services/
+│ │ └── [API services]
+│ ├── types/
+│ │ └── [TypeScript types/interfaces]
+│ ├── styles/
+│ │ └── [global styles]
+│ └── pages/
+│ └── [page components]
+├── public/
+│ └── [static assets]
+├── tests/
+│ └── [test files]
+└── [configuration files]
+```
+
+### Development Templates
+
+#### Component Implementation Template
+
+```typescript
+/**
+ * @component FeatureComponent
+ * @description Implements the [feature name] functionality
+ */
+
+import React, { useState, useEffect } from 'react';
+import { useService } from '@/hooks/useService';
+import { ComponentProps } from '@/types';
+
+export const FeatureComponent: React.FC
+ {/* Component content */}
+
+ );
+};
+```
+
+#### Custom Hook Template
+
+```typescript
+/**
+ * @hook useFeature
+ * @description Custom hook for [feature] functionality
+ * @returns {Object} Hook methods and state
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+export function useFeature(initialValue) {
+ // State
+ const [state, setState] = useState(initialValue);
+ const [isLoading, setIsLoading] = useState(false);
+ const [error, setError] = useState(null);
+
+ // Methods
+ const doSomething = useCallback(async () => {
+ setIsLoading(true);
+ setError(null);
+
+ try {
+ // Implementation
+ const result = await someAsyncOperation();
+ setState(result);
+ return result;
+ } catch (err) {
+ setError(err);
+ return null;
+ } finally {
+ setIsLoading(false);
+ }
+ }, [/* dependencies */]);
+
+ // Effects
+ useEffect(() => {
+ // Effect implementation
+ }, [/* dependencies */]);
+
+ // Return hook API
+ return {
+ state,
+ isLoading,
+ error,
+ doSomething
+ };
+}
+```
+
+### Testing Templates
+
+#### Component Test Template
+
+```typescript
+/**
+ * @test ComponentName
+ * @description Test suite for ComponentName component
+ */
+
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ComponentName } from './ComponentName';
+
+describe('ComponentName', () => {
+ // Test setup
+ const defaultProps = {
+ propName: 'test value'
+ };
+
+ beforeEach(() => {
+ // Setup before each test
+ });
+
+ afterEach(() => {
+ // Cleanup after each test
+ });
+
+ // Test cases
+ test('renders correctly with default props', () => {
+ render(
+
+\```
+
+### Progress Indicator Component
+
+\```html
+Select Your Persona
+
+
+
+
+
+ Project Manager
+Coordinate projects and manage resources
+
+
+
+ System Architect
+Design technical architecture and solutions
+
+
+
+ UX/UI Designer
+Create user experiences and interfaces
+
+
+
+ Developer
+Implement features and technical solutions
+
+
+\```
+
+### Expandable Code Example Component
+
+\```html
+
+
+
+ 1
+ Requirements
+
+
+
+ 2
+ Architecture
+
+
+
+ 3
+ Design
+
+
+4
+ Implementation
+
+
+\```
+
+## Visual Diagram Standards
+
+### Mermaid Diagram Styling
+
+\```css
+/* Custom Mermaid theme for BMAD documentation */
+.mermaid {
+ font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+}
+
+/* Node styling */
+.node rect {
+ fill: var(--bmad-primary);
+ stroke: var(--bmad-primary);
+ stroke-width: 2px;
+}
+
+.node .label {
+ color: white;
+ font-weight: 500;
+}
+
+/* Decision nodes */
+.node.decision rect {
+ fill: var(--bmad-warning);
+ stroke: var(--bmad-warning);
+}
+
+/* Success nodes */
+.node.success rect {
+ fill: var(--bmad-success);
+ stroke: var(--bmad-success);
+}
+
+/* Edge styling */
+.edgePath .path {
+ stroke: var(--bmad-gray-500);
+ stroke-width: 2px;
+}
+
+.edgeLabel {
+ background-color: white;
+ border: 1px solid var(--bmad-gray-300);
+ border-radius: 4px;
+ padding: 4px 8px;
+}
+\```
+
+### Icon System
+
+We use a consistent icon system throughout the documentation:
+
+- 🎠**Orchestrator**: Central coordination
+- 👔 **Project Manager**: Planning and coordination
+- ðŸ—ï¸ **Architect**: Technical design
+- 🎨 **UX/UI Designer**: User experience
+- 💻 **Developer**: Implementation
+- 📊 **Analyst**: Data and requirements
+- ✅ **Completed**: Finished tasks
+- 🔄 **In Progress**: Active work
+- â³ **Pending**: Waiting to start
+- â **Decision Point**: Key choices
+- 🔴 **Pain Point**: Challenges
+- 💡 **Solution**: Problem resolution
+
+## Screenshot Standards
+
+### Consistent Screenshot Styling
+
+All screenshots should follow these guidelines:
+
+1. **Resolution**: Minimum 1920x1080 for desktop, 375x812 for mobile
+2. **Browser**: Use Chrome with clean profile (no extensions visible)
+3. **Zoom Level**: 100% browser zoom
+4. **Annotations**: Use consistent callout styling
+5. **File Format**: PNG for UI screenshots, JPG for photos
+6. **Naming Convention**: `section-subsection-description.png`
+
+### Annotation Guidelines
+
+\```html
+
+ BMAD Persona Configuration
+
+
+
+
+
+personas:
+ pm:
+ name: "Project Manager"
+ expertise: ["planning", "coordination", "stakeholder-management"]
+ templates: ["prd", "project-plan", "status-report"]
+ architect:
+ name: "System Architect"
+ expertise: ["system-design", "technology-selection", "integration"]
+ templates: ["architecture-doc", "technical-spec", "integration-plan"]
+
+ 
+
+\```
+
+## Accessibility Standards
+
+### Color Contrast Requirements
+
+All text must meet WCAG AA standards:
+- Normal text: 4.5:1 contrast ratio minimum
+- Large text (18pt+): 3:1 contrast ratio minimum
+- Interactive elements: 3:1 contrast ratio for focus states
+
+### Alternative Text Guidelines
+
+\```html
+
+
+
+
+
+
+ 1
+ Select your environment
+
+
+ 2
+ Configure persona settings
+ 
+
+
+
+
+
+
+\```
+
+### Keyboard Navigation
+
+All interactive elements must be keyboard accessible:
+- Tab order follows logical reading sequence
+- Focus indicators are clearly visible
+- All functionality available via keyboard
+- Skip links provided for long content
+
+## Responsive Design Guidelines
+
+### Breakpoint System
+
+\```css
+/* Mobile first approach */
+@media (min-width: 640px) { /* sm */ }
+@media (min-width: 768px) { /* md */ }
+@media (min-width: 1024px) { /* lg */ }
+@media (min-width: 1280px) { /* xl */ }
+@media (min-width: 1536px) { /* 2xl */ }
+\```
+
+### Mobile Optimization
+
+- Touch targets minimum 44px
+- Readable text without zooming
+- Horizontal scrolling avoided
+- Content reflows appropriately
+
+## Implementation Guidelines
+
+### CSS Custom Properties
+
+\```css
+:root {
+ /* Brand colors */
+ --bmad-brand-primary: #2563eb;
+ --bmad-brand-secondary: #7c3aed;
+
+ /* Semantic colors */
+ --bmad-success: #10b981;
+ --bmad-warning: #f59e0b;
+ --bmad-error: #ef4444;
+ --bmad-info: #3b82f6;
+
+ /* Typography */
+ --bmad-font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+ --bmad-font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+ /* Spacing */
+ --bmad-space-unit: 0.25rem;
+
+ /* Shadows */
+ --bmad-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+ --bmad-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+ --bmad-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+}
+\```
+
+### Component Classes
+
+\```css
+/* Base component styling */
+.bmad-card {
+ background: white;
+ border-radius: 8px;
+ box-shadow: var(--bmad-shadow-md);
+ padding: var(--space-6);
+ border: 1px solid var(--bmad-gray-200);
+}
+
+.bmad-button {
+ background: var(--bmad-brand-primary);
+ color: white;
+ border: none;
+ border-radius: 6px;
+ padding: var(--space-3) var(--space-6);
+ font-weight: 500;
+ cursor: pointer;
+ transition: all 0.2s ease;
+}
+
+.bmad-button:hover {
+ background: var(--bmad-brand-primary-dark);
+ transform: translateY(-1px);
+}
+
+.bmad-button:focus {
+ outline: 2px solid var(--bmad-brand-primary);
+ outline-offset: 2px;
+}
+\```
+
+## Quality Assurance Checklist
+
+### Visual Review Checklist
+
+- [ ] Color contrast meets WCAG AA standards
+- [ ] Typography hierarchy is consistent
+- [ ] Spacing follows the defined scale
+- [ ] Interactive elements have clear focus states
+- [ ] Images have appropriate alt text
+- [ ] Responsive design works across breakpoints
+- [ ] Brand consistency maintained throughout
+- [ ] Loading states are handled gracefully
+- [ ] Error states are clearly communicated
+- [ ] Success states provide positive feedback
+
+### Accessibility Audit
+
+- [ ] Screen reader compatibility tested
+- [ ] Keyboard navigation verified
+- [ ] Color is not the only means of conveying information
+- [ ] Text can be resized to 200% without horizontal scrolling
+- [ ] Motion can be disabled for users with vestibular disorders
+- [ ] Form labels are properly associated
+- [ ] Headings create a logical document outline
+- [ ] Links have descriptive text
+
+---
+
+*These visual documentation standards ensure a consistent, accessible, and professional experience across all BMAD Method materials.*
diff --git a/docs/visual-elements/accessibility-guide.md b/docs/visual-elements/accessibility-guide.md
new file mode 100644
index 00000000..059d6925
--- /dev/null
+++ b/docs/visual-elements/accessibility-guide.md
@@ -0,0 +1,536 @@
+# BMAD Method Accessibility Guide
+
+This guide ensures that all BMAD Method documentation and visual elements are accessible to users with diverse abilities and needs.
+
+## Accessibility Principles
+
+### 1. Perceivable
+Information and user interface components must be presentable to users in ways they can perceive.
+
+### 2. Operable
+User interface components and navigation must be operable by all users.
+
+### 3. Understandable
+Information and the operation of user interface must be understandable.
+
+### 4. Robust
+Content must be robust enough to be interpreted reliably by a wide variety of user agents, including assistive technologies.
+
+## Color and Contrast Standards
+
+### WCAG AA Compliance
+
+All text and interactive elements meet or exceed WCAG AA standards:
+
+\```css
+/* High contrast color combinations */
+.high-contrast-text {
+ color: #000000; /* Black text */
+ background: #ffffff; /* White background */
+ /* Contrast ratio: 21:1 */
+}
+
+.primary-text {
+ color: #1a365d; /* Dark blue text */
+ background: #ffffff; /* White background */
+ /* Contrast ratio: 12.6:1 */
+}
+
+.secondary-text {
+ color: #4a5568; /* Gray text */
+ background: #ffffff; /* White background */
+ /* Contrast ratio: 7.2:1 */
+}
+
+/* Interactive elements */
+.interactive-element {
+ color: #ffffff; /* White text */
+ background: #2563eb; /* Blue background */
+ /* Contrast ratio: 8.6:1 */
+}
+
+.interactive-element:focus {
+ outline: 2px solid #1d4ed8;
+ outline-offset: 2px;
+ /* Focus indicator clearly visible */
+}
+\```
+
+### Color-Blind Friendly Palette
+
+Our color system works for users with various types of color vision deficiency:
+
+\```css
+/* Color-blind friendly palette */
+:root {
+ --accessible-blue: #0066cc; /* Distinguishable blue */
+ --accessible-green: #228b22; /* Forest green */
+ --accessible-red: #cc0000; /* Clear red */
+ --accessible-orange: #ff8c00; /* Dark orange */
+ --accessible-purple: #6a0dad; /* Blue violet */
+ --accessible-gray: #666666; /* Medium gray */
+}
+
+/* Never rely on color alone */
+.status-indicator {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.5rem;
+}
+
+.status-success {
+ color: var(--accessible-green);
+}
+
+.status-success::before {
+ content: "✓";
+ font-weight: bold;
+}
+
+.status-error {
+ color: var(--accessible-red);
+}
+
+.status-error::before {
+ content: "✗";
+ font-weight: bold;
+}
+
+.status-warning {
+ color: var(--accessible-orange);
+}
+
+.status-warning::before {
+ content: "âš ";
+ font-weight: bold;
+}
+\```
+
+## Typography and Readability
+
+### Font Selection and Sizing
+
+\```css
+/* Accessible typography */
+body {
+ font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+ font-size: 16px; /* Minimum 16px for body text */
+ line-height: 1.6; /* Adequate line spacing */
+ letter-spacing: 0.01em; /* Slight letter spacing for clarity */
+}
+
+h1, h2, h3, h4, h5, h6 {
+ font-weight: 600;
+ line-height: 1.3;
+ margin-bottom: 0.5em;
+}
+
+/* Large text for better readability */
+.large-text {
+ font-size: 18px;
+ line-height: 1.7;
+}
+
+/* Ensure text can be zoomed to 200% */
+@media (min-resolution: 2dppx) {
+ body {
+ font-size: 18px;
+ }
+}
+\```
+
+### Reading Flow and Structure
+
+\```html
+
+BMAD Method Overview
+ +Introduction
+The BMAD Method is...
+
+
+
+
+
+
+
+ Project Manager Persona
+Responsible for...
+
+
+
+
+
+
+
+
+
+
+
+\```
+
+### Video and Audio Accessibility
+
+\```html
+
+
+
+
+
+\```
+
+## Testing and Validation
+
+### Accessibility Testing Checklist
+
+- [ ] **Keyboard Navigation**
+ - [ ] All interactive elements are keyboard accessible
+ - [ ] Tab order is logical and intuitive
+ - [ ] Focus indicators are clearly visible
+ - [ ] No keyboard traps exist
+
+- [ ] **Screen Reader Compatibility**
+ - [ ] Content is properly structured with headings
+ - [ ] Images have appropriate alt text
+ - [ ] Form labels are properly associated
+ - [ ] ARIA attributes are used correctly
+
+- [ ] **Color and Contrast**
+ - [ ] Text meets WCAG AA contrast requirements
+ - [ ] Color is not the only means of conveying information
+ - [ ] Interactive elements have sufficient contrast
+
+- [ ] **Responsive Design**
+ - [ ] Content is readable at 200% zoom
+ - [ ] No horizontal scrolling at standard zoom levels
+ - [ ] Touch targets are at least 44px
+
+- [ ] **Motion and Animation**
+ - [ ] Animations can be disabled via prefers-reduced-motion
+ - [ ] No content flashes more than 3 times per second
+ - [ ] Auto-playing media can be paused
+
+### Automated Testing Tools
+
+\```javascript
+// Example accessibility testing with axe-core
+import { axe, toHaveNoViolations } from 'jest-axe';
+
+expect.extend(toHaveNoViolations);
+
+test('BMAD documentation should be accessible', async () => {
+ const { container } = render(Video Description
+This video introduces the BMAD Method, showing how different personas collaborate...
+
+
+Full Transcript
+Welcome to the BMAD Method introduction...
+
+
+
+
+
+
+
+## Persona Comparison Tool
+
+
+
+
+ BMAD Method Workflow
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Requirements
+ Product Owner
+
+
+
+
+
+
+ Architecture
+ System Architect
+
+
+
+
+
+
+ Design
+ UX/UI Designer
+
+
+
+ Implementation
+ Developer
+
+
+
+
+
+ Requirements Phase
+Product Owner defines project scope, user stories, and acceptance criteria.
+-
+
- Stakeholder interviews +
- User story creation +
- Acceptance criteria definition +
+
+
+ Architecture Phase
+System Architect designs technical approach and system structure.
+-
+
- Technology selection +
- System design +
- Integration planning +
+
+
+ Design Phase
+UX/UI Designer creates user experience and interface specifications.
+-
+
- User experience design +
- Interface mockups +
- Design system components +
+
+ Implementation Phase
+Developer builds the solution according to specifications.
+-
+
- Code implementation +
- Testing and validation +
- Documentation +
+
+
+
+
+
+
+## Progress Tracking Component
+
+
+
+
+ Compare BMAD Personas
+Select personas to compare their roles, expertise, and deliverables
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+*These interactive examples demonstrate how visual elements can enhance understanding and engagement with BMAD Method documentation.*
diff --git a/docs/workflow-diagram.md b/docs/workflow-diagram.md
index addbb184..e0700ccf 100644
--- a/docs/workflow-diagram.md
+++ b/docs/workflow-diagram.md
@@ -22,8 +22,20 @@ flowchart TD
PM_C --> PM_PRD
end
- %% Phase 2: Architect
- subgraph ARCH["Phase 2: Architect"]
+ %% Phase 2: UX/UI Design (NEW)
+ subgraph UXUI["Phase 2: v0 UX/UI Architect"]
+ UXUI_S["UX/UI Specification Creation"]
+ UXUI_P["Rapid Prototyping"]
+ UXUI_C["Component Design"]
+ UXUI_V["Design Validation"]
+
+ UXUI_S --> UXUI_P
+ UXUI_P --> UXUI_C
+ UXUI_C --> UXUI_V
+ end
+
+ %% Phase 3: Architect
+ subgraph ARCH["Phase 3: System Architect"]
ARCH_P["Architecture Package Creation"]
ARCH_C["Architect Checklist Verification"]
ARCH_D["PRD+Architecture and Artifacts"]
@@ -32,20 +44,30 @@ flowchart TD
ARCH_C --> ARCH_D
end
- %% Phase 3: PO
- subgraph PO["Phase 3: Product Owner"]
+ %% Phase 4: Design Architect (Frontend)
+ subgraph DESIGN["Phase 4: Design Architect"]
+ DESIGN_FE["Frontend Architecture"]
+ DESIGN_AI["AI UI Generation Prompts"]
+ DESIGN_C["Design System Integration"]
+
+ DESIGN_FE --> DESIGN_AI
+ DESIGN_AI --> DESIGN_C
+ end
+
+ %% Phase 5: PO
+ subgraph PO["Phase 5: Product Owner"]
PO_C["PO Checklist Verification"]
PO_A["Approval"]
end
- %% Phase 4: SM
- subgraph SM["Phase 4: Scrum Master"]
+ %% Phase 6: SM
+ subgraph SM["Phase 6: Scrum Master"]
SM_S["Draft Next Story"]
SM_A["User Story Approval"]
end
- %% Phase 5: Developer
- subgraph DEV["Phase 5: Developer"]
+ %% Phase 7: Developer
+ subgraph DEV["Phase 7: Developer"]
DEV_I["Implement Story"]
DEV_T["Test"]
DEV_D["Deploy"]
@@ -59,25 +81,38 @@ flowchart TD
%% Connections between phases
BA_P --> PM_M
User_Input[/"User Direct Input"/] --> PM_M
- PM_PRD --> ARCH_P
- ARCH_D --> PO_C
+ PM_PRD --> UXUI_S
+ UXUI_V --> ARCH_P
+ ARCH_D --> DESIGN_FE
+ DESIGN_C --> PO_C
PO_C --> PO_A
PO_A --> SM_S
SM_S --> SM_A
SM_A --> DEV_I
DEV_A --> SM_S
+ %% Optional paths
+ PM_PRD -.-> ARCH_P
+ UXUI_V -.-> DESIGN_FE
+
%% Completion condition
DEV_A -- "All stories complete" --> DONE["Project Complete"]
- %% Styling
+ %% Styling - Split into manageable chunks
classDef phase fill:#1a73e8,stroke:#0d47a1,stroke-width:2px,color:white,font-size:14px
classDef artifact fill:#43a047,stroke:#1b5e20,stroke-width:1px,color:white,font-size:14px
classDef process fill:#ff9800,stroke:#e65100,stroke-width:1px,color:white,font-size:14px
classDef approval fill:#d81b60,stroke:#880e4f,stroke-width:1px,color:white,font-size:14px
- class BA,PM,ARCH,PO,SM,DEV phase
- class BA_P,PM_PRD,ARCH_D artifact
- class BA_B,BA_R,PM_D,PM_M,ARCH_P,SM_S,DEV_I,DEV_T,DEV_D process
+ %% Apply phase styling
+ class BA,PM,UXUI,ARCH,DESIGN,PO,SM,DEV phase
+
+ %% Apply artifact styling
+ class BA_P,PM_PRD,UXUI_V,ARCH_D,DESIGN_C artifact
+
+ %% Apply process styling
+ class BA_B,BA_R,PM_D,PM_M,UXUI_S,UXUI_P,UXUI_C process
+ class ARCH_P,DESIGN_FE,DESIGN_AI,SM_S,DEV_I,DEV_T,DEV_D process
+
+ %% Apply approval styling
class PM_C,ARCH_C,PO_C,PO_A,SM_A,DEV_A approval
-```
diff --git a/examples/dashboard-component-code.md b/examples/dashboard-component-code.md
new file mode 100644
index 00000000..ed9eff4c
--- /dev/null
+++ b/examples/dashboard-component-code.md
@@ -0,0 +1,639 @@
+# Dashboard Component Code Implementation
+
+This file contains the complete code implementation for the dashboard component example.
+
+## Initial Implementation
+
+```tsx
+import React from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Users, Activity, DollarSign, BarChart, ArrowUp, ArrowDown, Bell, Settings } from 'lucide-react';
+
+interface DashboardProps {
+ metrics: {
+ totalUsers: number;
+ activeUsers: number;
+ revenue: number;
+ conversionRate: number;
+ };
+ recentActivity: Array<{
+ id: string;
+ user: {
+ name: string;
+ avatar?: string;
+ };
+ action: string;
+ timestamp: string;
+ }>;
+ userData: {
+ name: string;
+ email: string;
+ avatar?: string;
+ role: string;
+ };
+}
+
+export function Dashboard({ metrics, recentActivity, userData }: DashboardProps) {
+ return (
+
+
+
+
+
+ Sprint Progress Tracker
+
+ Sprint 2 Progress
+ 85%
+
+
+
+
+
+
+
+
+ ✅
+
+
+
+
+
+ ✅
+
+
+ Story 2.2: System Architecture Diagrams
+ 8 points
+
+
+
+ ✅
+
+
+ Story 2.3: User Journey Documentation
+ 8 points
+
+
+ 🔄
+
+
+ Story 2.4: Visual Documentation Elements
+ 5 points
+
+ {/* Header */}
+
+ );
+}
+
+interface MetricCardProps {
+ title: string;
+ value: string;
+ icon: React.ReactNode;
+ trend: number;
+ color: 'blue' | 'emerald' | 'slate';
+}
+
+function MetricCard({ title, value, icon, trend, color }: MetricCardProps) {
+ const colorClasses = {
+ blue: {
+ bg: 'bg-blue-50',
+ text: 'text-blue-600',
+ icon: 'bg-blue-100 text-blue-600',
+ },
+ emerald: {
+ bg: 'bg-emerald-50',
+ text: 'text-emerald-600',
+ icon: 'bg-emerald-100 text-emerald-600',
+ },
+ slate: {
+ bg: 'bg-slate-50',
+ text: 'text-slate-600',
+ icon: 'bg-slate-100 text-slate-600',
+ },
+ };
+
+ return (
+
+
+
+ {/* Metrics */}
+
+
+ Dashboard
+Welcome back, {userData.name}
+
+
+
+
+
+ {userData.name.split(' ').map(n => n[0]).join('')}
+
+
+
+
+
+
+ {/* Content Area */}
+
+ {/* Recent Activity */}
+
+
+ Recent Activity
+
+
+
+
+
+ {/* User Profile */}
+
+
+ Your Profile
+
+
+
+
+
+
+ {recentActivity.map((activity) => (
+
+
+
+
+ {activity.user.name.split(' ').map(n => n[0]).join('')}
+
+
+
+ ))}
+
+
+ {activity.user.name}
+{activity.action}
+{activity.timestamp}
+
+
+
+ {userData.name.split(' ').map(n => n[0]).join('')}
+
+
+
+
+
+ {userData.name}
+{userData.email}
++ {userData.role} +
+
+
+
+
+
+
+
+ {title}
+{value}
+
+ {icon}
+
+
+ {trend >= 0 ? (
+
+
+ {/* Header */}
+
+ );
+}
+
+interface MetricCardProps {
+ title: string;
+ value: string;
+ icon: React.ReactNode;
+ trend: number;
+ color: 'blue' | 'emerald' | 'slate';
+ ariaLabel: string;
+}
+
+function MetricCard({ title, value, icon, trend, color, ariaLabel }: MetricCardProps) {
+ const colorClasses = {
+ blue: {
+ bg: 'bg-blue-50',
+ text: 'text-blue-600',
+ icon: 'bg-blue-100 text-blue-600',
+ },
+ emerald: {
+ bg: 'bg-emerald-50',
+ text: 'text-emerald-600',
+ icon: 'bg-emerald-100 text-emerald-600',
+ },
+ slate: {
+ bg: 'bg-slate-50',
+ text: 'text-slate-600',
+ icon: 'bg-slate-100 text-slate-600',
+ },
+ };
+
+ const trendText = `${Math.abs(trend)}% ${trend >= 0 ? 'increase' : 'decrease'} compared to last month`;
+
+ return (
+
+
+
+ {/* Metrics */}
+
+
+ Dashboard
+Welcome back, {userData.name}
+
+
+
+ {userData.name.split(' ').map(n => n[0]).join('')}
+
+
+
+
+
+
+
+
+
+
+ {/* Content Area */}
+
+ {/* Recent Activity */}
+
+
+ Recent Activity
+
+
+
+
+
+ {/* User Profile */}
+
+
+ Your Profile
+
+
+
+
+
+
+ {recentActivity.length > 0 ? (
+ recentActivity.map((activity) => (
+
+
+
+
+ {activity.user.name.split(' ').map(n => n[0]).join('')}
+
+
+
+ ))
+ ) : (
+
+
+ {activity.user.name}
+{activity.action}
+{activity.timestamp}
+No recent activity
+ )} +
+
+
+ {userData.name.split(' ').map(n => n[0]).join('')}
+
+
+
+
+
+ {userData.name}
+{userData.email}
++ {userData.role} +
+
+
+
+
+
+
+
+
+ {title}
+{value}
+
+ {trend >= 0 ? (
+
+ ) : (
+
+ )}
+ = 0 ? 'text-emerald-500' : 'text-red-500'}>
+ {Math.abs(trend)}%
+
+ vs last month
+
+
+ {/* Header Skeleton */}
+
+ );
+}
+```
+
+## Example Usage
+
+```tsx
+// Example usage
+import { Dashboard } from './components/Dashboard';
+
+export default function DashboardPage() {
+ const [isLoading, setIsLoading] = useState(true);
+ const [dashboardData, setDashboardData] = useState({
+ metrics: {
+ totalUsers: 0,
+ activeUsers: 0,
+ revenue: 0,
+ conversionRate: 0
+ },
+ recentActivity: [],
+ userData: {
+ name: '',
+ email: '',
+ role: ''
+ }
+ });
+
+ useEffect(() => {
+ // Simulate API call
+ setTimeout(() => {
+ setDashboardData({
+ metrics: {
+ totalUsers: 12487,
+ activeUsers: 8761,
+ revenue: 48395,
+ conversionRate: 12.8
+ },
+ recentActivity: [
+ {
+ id: '1',
+ user: {
+ name: 'John Smith',
+ avatar: '/avatars/john.jpg'
+ },
+ action: 'Created a new project "Q4 Marketing Campaign"',
+ timestamp: '2 minutes ago'
+ },
+ {
+ id: '2',
+ user: {
+ name: 'Sarah Johnson',
+ avatar: '/avatars/sarah.jpg'
+ },
+ action: 'Updated the analytics dashboard settings',
+ timestamp: '1 hour ago'
+ },
+ {
+ id: '3',
+ user: {
+ name: 'Michael Brown',
+ avatar: '/avatars/michael.jpg'
+ },
+ action: 'Invited 3 new team members',
+ timestamp: '3 hours ago'
+ },
+ {
+ id: '4',
+ user: {
+ name: 'Emily Davis',
+ avatar: '/avatars/emily.jpg'
+ },
+ action: 'Completed the quarterly report',
+ timestamp: 'Yesterday'
+ }
+ ],
+ userData: {
+ name: 'Alex Morgan',
+ email: 'alex.morgan@example.com',
+ avatar: '/avatars/alex.jpg',
+ role: 'Admin'
+ }
+ });
+ setIsLoading(false);
+ }, 1500);
+ }, []);
+
+ return (
+
+
+
+ {/* Metrics Skeleton */}
+
+
+
+
+
+ {[1, 2, 3, 4].map((i) => (
+
+
+
+
+ ))}
+
+
+ {/* Content Area Skeleton */}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {[1, 2, 3, 4].map((i) => (
+
+
+
+ ))}
+
+
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/examples/dashboard-component-example.md b/examples/dashboard-component-example.md
new file mode 100644
index 00000000..8dd06376
--- /dev/null
+++ b/examples/dashboard-component-example.md
@@ -0,0 +1,117 @@
+# v0 UX/UI Architect Example: Dashboard Component
+
+This example demonstrates how to use the v0 UX/UI Architect persona to create a modern, responsive dashboard component for a SaaS application.
+
+## Project Brief
+
+**Requirement**: Create a dashboard component for a SaaS analytics platform that displays key metrics, recent activity, and user information.
+
+**Brand Colors**:
+- Primary: #3b82f6 (Blue)
+- Secondary: #64748b (Slate)
+- Accent: #10b981 (Emerald)
+- Background: #f8fafc (Light Gray)
+
+**Technical Requirements**:
+- React with TypeScript
+- Tailwind CSS for styling
+- Responsive design (mobile, tablet, desktop)
+- Accessibility compliance (WCAG AA)
+
+## Step 1: Initial Prompt to v0 UX/UI Architect
+
+```
+Veronica, I need you to design a dashboard component for our SaaS analytics platform.
+It should display key metrics (total users, active users, revenue, conversion rate),
+recent activity, and user information. Our brand colors are blue (#3b82f6),
+slate (#64748b), emerald (#10b981), and light gray (#f8fafc) for backgrounds.
+The design should be responsive and follow accessibility best practices.
+```
+
+## Step 2: Initial Design Concept
+
+The v0 UX/UI Architect generated an initial design concept with the following key features:
+
+- Header with user profile and action buttons
+- Four metric cards showing key performance indicators
+- Recent activity feed with user avatars and timestamps
+- User profile card with role information and actions
+
+## Step 3: Feedback and Iteration
+
+After reviewing the initial design, we provided feedback to improve the component:
+
+```
+The design looks good, but we need to make a few adjustments:
+1. Add a date range selector at the top
+2. Make the metrics more accessible with proper ARIA labels
+3. Ensure the activity list is scrollable when there are many items
+4. Add a loading state for when data is being fetched
+```
+
+## Step 4: Refined Implementation
+
+The v0 UX/UI Architect provided a refined implementation that included:
+
+- Date range selector in the header
+- ARIA labels for all interactive elements
+- Scrollable activity feed with proper height constraints
+- Loading skeleton state for all components
+- Improved accessibility throughout
+
+## Step 5: Quality Assurance
+
+We ran the component through our quality assurance process:
+
+### Accessibility Testing
+
+- ✅ Semantic HTML structure
+- ✅ ARIA labels for interactive elements
+- ✅ Proper focus management
+- ✅ Color contrast meets WCAG AA standards
+- ✅ Screen reader compatibility
+
+### Responsive Testing
+
+- ✅ Mobile layout (320px+)
+- ✅ Tablet layout (768px+)
+- ✅ Desktop layout (1024px+)
+- ✅ Touch-friendly targets
+- ✅ Proper content reflow
+
+### Performance Testing
+
+- ✅ Optimized rendering
+- ✅ Proper loading states
+- ✅ Efficient state management
+- ✅ Minimal bundle size impact
+
+## Step 6: Final Implementation
+
+The final dashboard component was integrated into our application with sample data and includes:
+
+- Fully responsive layout that works on all device sizes
+- Accessible design with proper ARIA attributes and keyboard navigation
+- Loading states for improved user experience
+- Date range selector for filtering data
+- Metric cards with trend indicators
+- Scrollable activity feed
+- User profile with role information
+
+## Lessons Learned
+
+1. **Clear Requirements**: Providing specific brand colors and technical requirements resulted in a more accurate initial design
+2. **Iterative Approach**: The feedback cycle improved the component significantly
+3. **Accessibility Focus**: Explicitly requesting accessibility features ensured they were properly implemented
+4. **Loading States**: Including loading states improved the user experience during data fetching
+
+## Next Steps
+
+1. Add data visualization components (charts, graphs)
+2. Implement dark mode support
+3. Add customization options for different user roles
+4. Create additional dashboard layouts for different use cases
+
+This example demonstrates the complete workflow of using the v0 UX/UI Architect persona to create a production-ready dashboard component, from initial requirements through final implementation.
+
+> **Note**: For the complete code implementation, see the [Dashboard Component Code](./dashboard-component-code.md) file.
diff --git a/templates/persona-documentation-template.md b/templates/persona-documentation-template.md
new file mode 100644
index 00000000..7b73318e
--- /dev/null
+++ b/templates/persona-documentation-template.md
@@ -0,0 +1,312 @@
+# Persona Documentation Template
+
+This template provides the standard structure for all BMAD Method persona documentation.
+
+## File Structure
+
+Each persona should have the following documentation files:
+
+```
+docs/
+├── {persona-name}-comprehensive-guide.md
+├── {persona-name}-integration-guide.md
+├── {persona-name}-quality-assurance.md
+└── {persona-name}-quickstart.md
+
+examples/
+├── {persona-name}-example-project.md
+└── {persona-name}-example-code.md (if applicable)
+
+bmad-agent/personas/
+├── {persona-name}.md (Web version)
+└── {persona-name}.ide.md (IDE version)
+```
+
+## Template: Comprehensive Guide
+
+```markdown
+# {Persona Name} Comprehensive Guide
+
+## Introduction
+
+Brief introduction to the persona, their role in the BMAD Method, and their core capabilities.
+
+## Table of Contents
+
+1. [Core Capabilities](#core-capabilities)
+2. [When to Use](#when-to-use)
+3. [Activation Methods](#activation-methods)
+4. [Working Process](#working-process)
+5. [Input Requirements](#input-requirements)
+6. [Output Expectations](#output-expectations)
+7. [Integration with Other Personas](#integration-with-other-personas)
+8. [Best Practices](#best-practices)
+9. [Troubleshooting](#troubleshooting)
+10. [Advanced Usage](#advanced-usage)
+
+## Core Capabilities
+
+List the primary capabilities and strengths of this persona:
+
+- **Capability 1**: Description of what the persona excels at
+- **Capability 2**: Another key strength
+- **Capability 3**: Additional capability
+
+## When to Use
+
+Describe the ideal scenarios for using this persona:
+
+- **Scenario 1**: When you need X
+- **Scenario 2**: During Y phase of the project
+- **Scenario 3**: For Z type of tasks
+
+## Activation Methods
+
+### Web Environment ({Web Persona Name})
+
+```
+"I need {Web Persona Name} to help with {task type}"
+"Activate the {persona role} for {specific task}"
+```
+
+### IDE Environment ({IDE Persona Name})
+
+```
+"{IDE Persona Name}, I need you to {action} using {tools/framework}"
+"Help me {task} that integrates with our existing {system}"
+```
+
+## Working Process
+
+Describe the typical workflow when using this persona:
+
+1. **Step 1**: Initial setup or requirements gathering
+2. **Step 2**: Analysis or planning phase
+3. **Step 3**: Implementation or execution
+4. **Step 4**: Review and refinement
+5. **Step 5**: Delivery and documentation
+
+## Input Requirements
+
+For optimal results, provide:
+
+- **Requirement 1**: What information is needed
+- **Requirement 2**: Context or constraints
+- **Requirement 3**: Technical specifications
+- **Requirement 4**: Success criteria
+
+## Output Expectations
+
+The persona produces:
+
+- **Output 1**: Type of deliverable
+- **Output 2**: Documentation or artifacts
+- **Output 3**: Recommendations or guidance
+
+## Integration with Other Personas
+
+Describe how this persona works with others in the BMAD Method:
+
+- **{Other Persona}**: How they collaborate
+- **{Another Persona}**: Handoff procedures
+- **{Third Persona}**: Shared responsibilities
+
+## Best Practices
+
+### Effective Usage
+
+1. **Practice 1**: How to get the best results
+2. **Practice 2**: Common optimization techniques
+3. **Practice 3**: Quality assurance approaches
+
+### Quality Assurance
+
+- Run the {Persona} Quality Checklist after completion
+- Validate outputs against requirements
+- Ensure integration with existing systems
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Problem 1 | How to resolve it |
+| Problem 2 | Step-by-step fix |
+| Problem 3 | Alternative approaches |
+
+## Advanced Usage
+
+### Advanced Techniques
+
+Describe sophisticated use cases and techniques for experienced users.
+
+### Integration Patterns
+
+Explain complex integration scenarios and patterns.
+
+---
+
+This comprehensive guide provides everything you need to effectively use the {Persona Name} persona in your development workflow.
+```
+```
+
+## Template: Integration Guide
+
+```markdown
+# {Persona Name} Integration Guide
+
+## Overview
+
+This guide explains how to integrate the {Persona Name} persona into your development workflow.
+
+## Table of Contents
+
+1. [Web Environment Integration](#web-environment-integration)
+2. [IDE Environment Integration](#ide-environment-integration)
+3. [BMAD Method Workflow Integration](#bmad-method-workflow-integration)
+4. [Third-Party Tool Integration](#third-party-tool-integration)
+5. [Configuration Options](#configuration-options)
+
+## Web Environment Integration
+
+### Setup Instructions
+
+1. **Access the Web Orchestrator**
+2. **Load the {Persona Name} Persona**
+3. **Activate the Persona**
+
+### Usage Examples
+
+Provide specific examples of how to use the persona in web environments.
+
+## IDE Environment Integration
+
+### Supported IDEs
+
+List supported development environments and setup instructions for each.
+
+### Usage Examples
+
+Show how to use the persona within different IDE environments.
+
+## BMAD Method Workflow Integration
+
+### Integration Points
+
+Describe where this persona fits in the overall BMAD workflow.
+
+### Workflow Diagram
+
+```
+Previous Persona → {Current Persona} → Next Persona
+```
+
+## Third-Party Tool Integration
+
+List and describe integrations with external tools and services.
+
+## Configuration Options
+
+Document available configuration options and their usage.
+
+---
+
+This integration guide provides comprehensive instructions for incorporating the {Persona Name} persona into your development workflow.
+```
+```
+
+## Template: Quality Assurance Guide
+
+```markdown
+# {Persona Name} Quality Assurance Guide
+
+This document provides comprehensive quality assurance procedures for evaluating outputs from the {Persona Name} persona.
+
+## Quality Assurance Process
+
+### Overview
+
+Describe the QA process specific to this persona's outputs.
+
+## Quality Checklists
+
+### Primary Quality Checklist
+
+- [ ] **Criterion 1**: Description of what to check
+- [ ] **Criterion 2**: Another quality measure
+- [ ] **Criterion 3**: Additional validation point
+
+### Secondary Quality Checklist
+
+- [ ] **Integration**: Works with other system components
+- [ ] **Documentation**: Properly documented
+- [ ] **Standards**: Follows established standards
+
+## Testing Procedures
+
+Describe specific testing procedures for this persona's outputs.
+
+## Success Metrics
+
+Define measurable success criteria for this persona's work.
+
+---
+
+This quality assurance guide ensures high-quality outputs from the {Persona Name} persona.
+```
+```
+
+## Template: Quick Start Guide
+
+```markdown
+# {Persona Name} Quick Start Guide
+
+Get up and running with the {Persona Name} persona in just 5 minutes.
+
+## 1. Choose Your Environment
+
+Brief description of environment options.
+
+## 2. Activate the Persona
+
+Simple activation instructions.
+
+## 3. Provide Clear Requirements
+
+What information to provide for best results.
+
+## 4. Review and Iterate
+
+How to refine and improve outputs.
+
+## 5. Implement and Test
+
+Final steps to complete the work.
+
+## Example: {Simple Use Case}
+
+Step-by-step example of a common use case.
+
+## Next Steps
+
+Links to comprehensive documentation and advanced guides.
+
+---
+
+Start using the {Persona Name} persona effectively today!
+```
+```
+
+## Usage Instructions
+
+1. **Copy the appropriate template**
+2. **Replace all {placeholder} text** with persona-specific information
+3. **Customize sections** based on the persona's unique capabilities
+4. **Add persona-specific examples** and use cases
+5. **Validate against the quality checklist**
+
+This template ensures consistency across all persona documentation while allowing for persona-specific customization.
+```
+
+Now let's begin standardizing the first persona - Product Manager (John):
diff --git a/web-build-sample/tasks.txt b/web-build-sample/tasks.txt
index 6a94ad7f..39f3495f 100644
--- a/web-build-sample/tasks.txt
+++ b/web-build-sample/tasks.txt
@@ -1,4 +1,4 @@
-==================== START: advanced-elicitation ====================
+==================== START: advanced-elicitation ====================
# Advanced Elicitation Task
## Purpose
@@ -15,7 +15,7 @@
**Present the numbered list (0-9) with this exact format:**
-```
+\`\`\`
**Advanced Reflective, Elicitation & Brainstorming Actions**
Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
@@ -29,7 +29,7 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
7. Explore Diverse Alternatives (ToT-Inspired)
8. Hindsight is 20/20: The 'If Only...' Reflection
9. Proceed / No Further Actions
-```
+\`\`\`
### 2. Processing Guidelines
@@ -199,9 +199,9 @@ The BMAD Method uses various checklists to ensure quality and completeness of di
- Look for evidence in the documentation that satisfies the requirement
- Consider both explicit mentions and implicit coverage
- Mark items as:
- - ✅ PASS: Requirement clearly met
- - ⌠FAIL: Requirement not met or insufficient coverage
- - âš ï¸ PARTIAL: Some aspects covered but needs improvement
+ - ✅ PASS: Requirement clearly met
+ - ❌ FAIL: Requirement not met or insufficient coverage
+ - ⚠️ PARTIAL: Some aspects covered but needs improvement
- N/A: Not applicable to this case
5. **Section Analysis**
@@ -1006,7 +1006,7 @@ To design a comprehensive infrastructure architecture that defines all aspects o
### 5. Implementation Feasibility Review & Collaboration
-- **Architect → DevOps/Platform Feedback Loop:**
+- **Architect → DevOps/Platform Feedback Loop:**
- Present architectural blueprint summary to DevOps/Platform Engineering Agent for feasibility review
- Request specific feedback on:
- **Operational Complexity:** Are the proposed patterns implementable with current tooling and expertise?
@@ -1126,7 +1126,7 @@ To identify the next logical story based on project progress and epic definition
- Verify its `Status` is 'Done' (or equivalent).
- If not 'Done', present an alert to the user:
- ```plaintext
+ \`\`\`plaintext
ALERT: Found incomplete story:
File: {lastEpicNum}.{lastStoryNum}.story.md
Status: [current status]
@@ -1137,7 +1137,7 @@ To identify the next logical story based on project progress and epic definition
3. Accept risk & Override to create the next story in draft
Please choose an option (1/2/3):
- ```
+ \`\`\`
- Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
- If proceeding: Check the Epic File for `{lastEpicNum}` for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
@@ -1215,7 +1215,7 @@ To implement a comprehensive platform infrastructure stack based on the Infrastr
### 1. Confirm Interaction Mode
- Ask the user: "How would you like to proceed with platform infrastructure implementation? We can work:
- A. **Incrementally (Default & Recommended):** We'll implement each platform layer step-by-step (Foundation → Container Platform → GitOps → Service Mesh → Developer Experience), validating integration at each stage. This ensures thorough testing and operational readiness.
+ A. **Incrementally (Default & Recommended):** We'll implement each platform layer step-by-step (Foundation → Container Platform → GitOps → Service Mesh → Developer Experience), validating integration at each stage. This ensures thorough testing and operational readiness.
B. **"YOLO" Mode:** I'll implement the complete platform stack in logical groups, with validation at major integration milestones. This is faster but requires comprehensive end-to-end testing."
- Request the user to select their preferred mode and proceed accordingly.
@@ -1230,7 +1230,7 @@ To implement a comprehensive platform infrastructure stack based on the Infrastr
### 3. Joint Implementation Planning Session
-- **Architect ↔ DevOps/Platform Collaborative Planning:**
+- **Architect ↔ DevOps/Platform Collaborative Planning:**
- **Architecture Alignment Review:**
- Confirm understanding of architectural decisions and rationale with Architect Agent
- Validate interpretation of infrastructure architecture document
@@ -1736,11 +1736,11 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
Each entry in `docs/index.md` should follow this format:
-```markdown
+\`\`\`markdown
### [Document Title](relative/path/to/file.md)
Brief description of the document's purpose and contents.
-```
+\`\`\`
### Rules of Operation
@@ -1772,7 +1772,7 @@ For each file referenced in the index but not found in the filesystem:
1. Present the entry:
- ```markdown
+ \`\`\`markdown
Missing file detected:
Title: [Document Title]
Path: relative/path/to/file.md
@@ -1785,7 +1785,7 @@ For each file referenced in the index but not found in the filesystem:
3. Keep entry (mark as temporarily unavailable)
Please choose an option (1/2/3):
- ```
+ \`\`\`
2. Wait for user confirmation before taking any action
3. Log the decision for the final report
@@ -1871,7 +1871,7 @@ To conduct a thorough review of existing infrastructure to identify improvement
### 6. Architectural Escalation Assessment
-- **DevOps/Platform → Architect Escalation Review:**
+- **DevOps/Platform → Architect Escalation Review:**
- Evaluate review findings for issues requiring architectural intervention:
- **Technical Debt Escalation:**
- Identify infrastructure technical debt that impacts system architecture
@@ -2003,7 +2003,7 @@ To comprehensively validate platform infrastructure changes against security, re
### 3. Architecture Design Review Gate
-- **DevOps/Platform → Architect Design Review:**
+- **DevOps/Platform → Architect Design Review:**
- Conduct systematic review of infrastructure architecture document for implementability
- Evaluate architectural decisions against operational constraints and capabilities:
- **Implementation Complexity:** Assess if proposed architecture can be implemented with available tools and expertise
diff --git a/web-build-sample/templates.txt b/web-build-sample/templates.txt
index 375a4fa5..30cf994d 100644
--- a/web-build-sample/templates.txt
+++ b/web-build-sample/templates.txt
@@ -1,4 +1,4 @@
-==================== START: architecture-tmpl ====================
+==================== START: architecture-tmpl ====================
# {Project Name} Architecture Document
## Introduction / Preamble
@@ -46,47 +46,47 @@ If the project includes a significant user interface, a separate Frontend Archit
{Provide an ASCII or Mermaid diagram representing the project's folder structure. The following is a general example. If a `front-end-architecture-tmpl.txt` (or equivalent) is in use, it will contain the detailed structure for the frontend portion (e.g., within `src/frontend/` or a dedicated `frontend/` root directory). Shared code structure (e.g., in a `packages/` directory for a monorepo) should also be detailed here.}
-```plaintext
+\`\`\`plaintext
{project-root}/
-├── .github/ # CI/CD workflows (e.g., GitHub Actions)
-│ └── workflows/
-│ └── main.yml
-├── .vscode/ # VSCode settings (optional)
-│ └── settings.json
-├── build/ # Compiled output (if applicable, often git-ignored)
-├── config/ # Static configuration files (if any)
-├── docs/ # Project documentation (PRD, Arch, etc.)
-│ ├── index.md
-│ └── ... (other .md files)
-├── infra/ # Infrastructure as Code (e.g., CDK, Terraform)
-│ └── lib/
-│ └── bin/
-├── node_modules/ / venv / target/ # Project dependencies (git-ignored)
-├── scripts/ # Utility scripts (build, deploy helpers, etc.)
-├── src/ # Application source code
-│ ├── backend/ # Backend-specific application code (if distinct frontend exists)
-│ │ ├── core/ # Core business logic, domain models
-│ │ ├── services/ # Business services, orchestrators
-│ │ ├── adapters/ # Adapters to external systems (DB, APIs)
-│ │ ├── controllers/ / routes/ # API endpoint handlers
-│ │ └── main.ts / app.py # Backend application entry point
-│ ├── frontend/ # Placeholder: See Frontend Architecture Doc for details if used
-│ ├── shared/ / common/ # Code shared (e.g., types, utils, domain models if applicable)
-│ │ └── types/
-│ └── main.ts / index.ts / app.ts # Main application entry point (if not using backend/frontend split above)
-├── stories/ # Generated story files for development (optional)
-│ └── epic1/
-├── test/ # Automated tests
-│ ├── unit/ # Unit tests (mirroring src structure)
-│ ├── integration/ # Integration tests
-│ └── e2e/ # End-to-end tests
-├── .env.example # Example environment variables
-├── .gitignore # Git ignore rules
-├── package.json / requirements.txt / pom.xml # Project manifest and dependencies
-├── tsconfig.json / pyproject.toml # Language-specific configuration (if applicable)
-├── Dockerfile # Docker build instructions (if applicable)
-└── README.md # Project overview and setup instructions
-```
+├── .github/ # CI/CD workflows (e.g., GitHub Actions)
+│ └── workflows/
+│ └── main.yml
+├── .vscode/ # VSCode settings (optional)
+│ └── settings.json
+├── build/ # Compiled output (if applicable, often git-ignored)
+├── config/ # Static configuration files (if any)
+├── docs/ # Project documentation (PRD, Arch, etc.)
+│ ├── index.md
+│ └── ... (other .md files)
+├── infra/ # Infrastructure as Code (e.g., CDK, Terraform)
+│ └── lib/
+│ └── bin/
+├── node_modules/ / venv / target/ # Project dependencies (git-ignored)
+├── scripts/ # Utility scripts (build, deploy helpers, etc.)
+├── src/ # Application source code
+│ ├── backend/ # Backend-specific application code (if distinct frontend exists)
+│ │ ├── core/ # Core business logic, domain models
+│ │ ├── services/ # Business services, orchestrators
+│ │ ├── adapters/ # Adapters to external systems (DB, APIs)
+│ │ ├── controllers/ / routes/ # API endpoint handlers
+│ │ └── main.ts / app.py # Backend application entry point
+│ ├── frontend/ # Placeholder: See Frontend Architecture Doc for details if used
+│ ├── shared/ / common/ # Code shared (e.g., types, utils, domain models if applicable)
+│ │ └── types/
+│ └── main.ts / index.ts / app.ts # Main application entry point (if not using backend/frontend split above)
+├── stories/ # Generated story files for development (optional)
+│ └── epic1/
+├── test/ # Automated tests
+│ ├── unit/ # Unit tests (mirroring src structure)
+│ ├── integration/ # Integration tests
+│ └── e2e/ # End-to-end tests
+├── .env.example # Example environment variables
+├── .gitignore # Git ignore rules
+├── package.json / requirements.txt / pom.xml # Project manifest and dependencies
+├── tsconfig.json / pyproject.toml # Language-specific configuration (if applicable)
+├── Dockerfile # Docker build instructions (if applicable)
+└── README.md # Project overview and setup instructions
+\`\`\`
(Adjust the example tree based on the actual project type - e.g., Python would have requirements.txt, etc. The structure above illustrates a potential separation for projects with distinct frontends; for simpler projects or APIs, the `src/` structure might be flatter.)
@@ -158,7 +158,7 @@ If the project includes a significant user interface, a separate Frontend Archit
- **Description:** {What does this entity represent?}
- **Schema / Interface Definition:**
- ```typescript
+ \`\`\`typescript
// Example using TypeScript Interface
export interface {EntityName} {
id: string; // {Description, e.g., Unique identifier}
@@ -166,7 +166,7 @@ If the project includes a significant user interface, a separate Frontend Archit
optionalProperty?: number; // {Description}
// ... other properties
}
- ```
+ \`\`\`
- **Validation Rules:** {List any specific validation rules beyond basic types - e.g., max length, format, range.}
### API Payload Schemas (If distinct)
@@ -176,14 +176,14 @@ If the project includes a significant user interface, a separate Frontend Archit
#### {API Endpoint / Purpose, e.g., Create Order Request, repeat the section as needed}
- **Schema / Interface Definition:**
- ```typescript
+ \`\`\`typescript
// Example
export interface CreateOrderRequest {
customerId: string;
items: { productId: string; quantity: number }[];
// ...
}
- ```
+ \`\`\`
### Database Schemas (If applicable)
@@ -193,7 +193,7 @@ If the project includes a significant user interface, a separate Frontend Archit
- **Purpose:** {What data does this table store?}
- **Schema Definition:**
- ```sql
+ \`\`\`sql
-- Example SQL
CREATE TABLE {TableName} (
id VARCHAR(36) PRIMARY KEY,
@@ -201,7 +201,7 @@ If the project includes a significant user interface, a separate Frontend Archit
numeric_column DECIMAL(10, 2),
-- ... other columns, indexes, constraints
);
- ```
+ \`\`\`
_(Alternatively, use ORM model definitions, NoSQL document structure, etc.)_
## Core Workflow / Sequence Diagrams
@@ -538,7 +538,7 @@ CRITICAL: **Index Management:** After creating the files, update `docs/index.md`
- **Framework & Core Libraries:** {e.g., React 18.x with Next.js 13.x, Angular 16.x, Vue 3.x with Nuxt.js}. **These are derived from the 'Definitive Tech Stack Selections' in the main Architecture Document.** This section elaborates on *how* these choices are applied specifically to the frontend.
- **Component Architecture:** {e.g., Atomic Design principles, Presentational vs. Container components, use of specific component libraries like Material UI, Tailwind CSS for styling approach. Specify chosen approach and any key libraries.}
-- **State Management Strategy:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx. Briefly describe the overall approach – global store, feature stores, context API usage. **Referenced from main Architecture Document and detailed further in "State Management In-Depth" section.**}
+- **State Management Strategy:** {e.g., Redux Toolkit, Zustand, Vuex, NgRx. Briefly describe the overall approach – global store, feature stores, context API usage. **Referenced from main Architecture Document and detailed further in "State Management In-Depth" section.**}
- **Data Flow:** {e.g., Unidirectional data flow (Flux/Redux pattern), React Query/SWR for server state. Describe how data is fetched, cached, passed to components, and updated.}
- **Styling Approach:** **{Chosen Styling Solution, e.g., Tailwind CSS / CSS Modules / Styled Components}**. Configuration File(s): {e.g., `tailwind.config.js`, `postcss.config.js`}. Key conventions: {e.g., "Utility-first approach for Tailwind. Custom components defined in `src/styles/components.css`. Theme extensions in `tailwind.config.js` under `theme.extend`. For CSS Modules, files are co-located with components, e.g., `MyComponent.module.css`.}
- **Key Design Patterns Used:** {e.g., Provider pattern, Hooks, Higher-Order Components, Service patterns for API calls, Container/Presentational. These patterns are to be consistently applied. Deviations require justification and documentation.}
@@ -549,46 +549,46 @@ CRITICAL: **Index Management:** After creating the files, update `docs/index.md`
### EXAMPLE - Not Prescriptive (for a React/Next.js app)
-```plaintext
+\`\`\`plaintext
src/
-├── app/ # Next.js App Router: Pages/Layouts/Routes. MUST contain route segments, layouts, and page components.
-│ ├── (features)/ # Feature-based routing groups. MUST group related routes for a specific feature.
-│ │ └── dashboard/
-│ │ ├── layout.tsx # Layout specific to the dashboard feature routes.
-│ │ └── page.tsx # Entry page component for a dashboard route.
-│ ├── api/ # API Routes (if using Next.js backend features). MUST contain backend handlers for client-side calls.
-│ ├── globals.css # Global styles. MUST contain base styles, CSS variable definitions, Tailwind base/components/utilities.
-│ └── layout.tsx # Root layout for the entire application.
-├── components/ # Shared/Reusable UI Components.
-│ ├── ui/ # Base UI elements (Button, Input, Card). MUST contain only generic, reusable, presentational UI elements, often mapped from a design system. MUST NOT contain business logic.
-│ │ ├── Button.tsx
-│ │ └── ...
-│ ├── layout/ # Layout components (Header, Footer, Sidebar). MUST contain components structuring page layouts, not specific page content.
-│ │ ├── Header.tsx
-│ │ └── ...
-│ └── (feature-specific)/ # Components specific to a feature but potentially reusable within it. This is an alternative to co-locating within features/ directory.
-│ └── user-profile/
-│ └── ProfileCard.tsx
-├── features/ # Feature-specific logic, hooks, non-global state, services, and components solely used by that feature.
-│ └── auth/
-│ ├── components/ # Components used exclusively by the auth feature. MUST NOT be imported by other features.
-│ ├── hooks/ # Custom React Hooks specific to the 'auth' feature. Hooks reusable across features belong in `src/hooks/`.
-│ ├── services/ # Feature-specific API interactions or orchestrations for the 'auth' feature.
-│ └── store.ts # Feature-specific state slice (e.g., Redux slice) if not part of a global store or if local state is complex.
-├── hooks/ # Global/sharable custom React Hooks. MUST be generic and usable by multiple features/components.
-│ └── useAuth.ts
-├── lib/ / utils/ # Utility functions, helpers, constants. MUST contain pure functions and constants, no side effects or framework-specific code unless clearly named (e.g., `react-helpers.ts`).
-│ └── utils.ts
-├── services/ # Global API service clients or SDK configurations. MUST define base API client instances and core data fetching/mutation services.
-│ └── apiClient.ts
-├── store/ # Global state management setup (e.g., Redux store, Zustand store).
-│ ├── index.ts # Main store configuration and export.
-│ ├── rootReducer.ts # Root reducer if using Redux.
-│ └── (slices)/ # Directory for global state slices (if not co-located in features).
-├── styles/ # Global styles, theme configurations (if not using `globals.css` or similar, or for specific styling systems like SCSS partials).
-└── types/ # Global TypeScript type definitions/interfaces. MUST contain types shared across multiple features/modules.
- └── index.ts
-```
+├── app/ # Next.js App Router: Pages/Layouts/Routes. MUST contain route segments, layouts, and page components.
+│ ├── (features)/ # Feature-based routing groups. MUST group related routes for a specific feature.
+│ │ └── dashboard/
+│ │ ├── layout.tsx # Layout specific to the dashboard feature routes.
+│ │ └── page.tsx # Entry page component for a dashboard route.
+│ ├── api/ # API Routes (if using Next.js backend features). MUST contain backend handlers for client-side calls.
+│ ├── globals.css # Global styles. MUST contain base styles, CSS variable definitions, Tailwind base/components/utilities.
+│ └── layout.tsx # Root layout for the entire application.
+├── components/ # Shared/Reusable UI Components.
+│ ├── ui/ # Base UI elements (Button, Input, Card). MUST contain only generic, reusable, presentational UI elements, often mapped from a design system. MUST NOT contain business logic.
+│ │ ├── Button.tsx
+│ │ └── ...
+│ ├── layout/ # Layout components (Header, Footer, Sidebar). MUST contain components structuring page layouts, not specific page content.
+│ │ ├── Header.tsx
+│ │ └── ...
+│ └── (feature-specific)/ # Components specific to a feature but potentially reusable within it. This is an alternative to co-locating within features/ directory.
+│ └── user-profile/
+│ └── ProfileCard.tsx
+├── features/ # Feature-specific logic, hooks, non-global state, services, and components solely used by that feature.
+│ └── auth/
+│ ├── components/ # Components used exclusively by the auth feature. MUST NOT be imported by other features.
+│ ├── hooks/ # Custom React Hooks specific to the 'auth' feature. Hooks reusable across features belong in `src/hooks/`.
+│ ├── services/ # Feature-specific API interactions or orchestrations for the 'auth' feature.
+│ └── store.ts # Feature-specific state slice (e.g., Redux slice) if not part of a global store or if local state is complex.
+├── hooks/ # Global/sharable custom React Hooks. MUST be generic and usable by multiple features/components.
+│ └── useAuth.ts
+├── lib/ / utils/ # Utility functions, helpers, constants. MUST contain pure functions and constants, no side effects or framework-specific code unless clearly named (e.g., `react-helpers.ts`).
+│ └── utils.ts
+├── services/ # Global API service clients or SDK configurations. MUST define base API client instances and core data fetching/mutation services.
+│ └── apiClient.ts
+├── store/ # Global state management setup (e.g., Redux store, Zustand store).
+│ ├── index.ts # Main store configuration and export.
+│ ├── rootReducer.ts # Root reducer if using Redux.
+│ └── (slices)/ # Directory for global state slices (if not co-located in features).
+├── styles/ # Global styles, theme configurations (if not using `globals.css` or similar, or for specific styling systems like SCSS partials).
+└── types/ # Global TypeScript type definitions/interfaces. MUST contain types shared across multiple features/modules.
+ └── index.ts
+\`\`\`
### Notes on Frontend Structure:
@@ -629,14 +629,14 @@ src/
| `{anotherState}`| `{type}` | `{value}` | {Description of state variable and its purpose.} |
- **Key UI Elements / Structure:**
{ Provide a pseudo-HTML or JSX-like structure representing the component\'s DOM. Include key conditional rendering logic if applicable. **This structure dictates the primary output for the AI agent.** }
- ```html
+ \`\`\`html
{userName}
{userEmail}
{variant === 'full' && onEdit && }