kiro-spec-engine 1.2.3 → 1.4.0

package/docs/examples/add-user-dashboard/design.md

@@ -0,0 +1,192 @@
+# User Dashboard - Design
+
+> Technical design for React dashboard feature
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## Architecture
+
+**Pattern:** Container/Presentational Components  
+**State Management:** React Context + Hooks  
+**Styling:** CSS Modules  
+**Charts:** Recharts library
+
+---
+
+## Component Design
+
+### Dashboard (Container)
+**File:** `src/pages/Dashboard.jsx`
+
+**Responsibilities:**
+- Fetch dashboard data
+- Manage loading/error states
+- Compose child components
+
+**State:**
+```javascript
+{
+  metrics: { total, completed, inProgress, pending },
+  chartData: [{ date, count }],
+  recentTasks: [{ id, title, status, date }],
+  loading: boolean,
+  error: string | null
+}
+```
+
+---
+
+### MetricCard (Presentational)
+**File:** `src/components/MetricCard.jsx`
+
+**Props:**
+```javascript
+{
+  title: string,
+  value: number,
+  change: number, // percentage
+  icon: ReactNode
+}
+```
+
+**Renders:**
+- Card container
+- Icon
+- Title
+- Value (large text)
+- Change indicator (↑/↓ with color)
+
+---
+
+### TaskCompletionChart (Presentational)
+**File:** `src/components/TaskCompletionChart.jsx`
+
+**Props:**
+```javascript
+{
+  data: [{ date: string, count: number }]
+}
+```
+
+**Implementation:**
+- Use Recharts LineChart
+- Format dates on X-axis
+- Show tooltip on hover
+- Responsive container
+
+---
+
+### TaskList (Presentational)
+**File:** `src/components/TaskList.jsx`
+
+**Props:**
+```javascript
+{
+  tasks: [{ id, title, status, date }],
+  onTaskClick: (id) => void
+}
+```
+
+---
+
+## State Management
+
+### DashboardContext
+**File:** `src/contexts/DashboardContext.jsx`
+
+```javascript
+const DashboardContext = createContext();
+
+export function DashboardProvider({ children }) {
+  const [state, dispatch] = useReducer(dashboardReducer, initialState);
+  
+  const fetchDashboardData = async () => {
+    // Fetch metrics, chart data, recent tasks
+  };
+  
+  return (
+    <DashboardContext.Provider value={{ state, fetchDashboardData }}>
+      {children}
+    </DashboardContext.Provider>
+  );
+}
+```
+
+---
+
+## API Integration
+
+### useDashboard Hook
+**File:** `src/hooks/useDashboard.js`
+
+```javascript
+export function useDashboard() {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    async function fetchData() {
+      try {
+        const [metrics, chartData, tasks] = await Promise.all([
+          api.get('/dashboard/metrics'),
+          api.get('/dashboard/chart-data'),
+          api.get('/tasks?limit=5&sort=recent')
+        ]);
+        setData({ metrics, chartData, tasks });
+      } catch (err) {
+        setError(err.message);
+      } finally {
+        setLoading(false);
+      }
+    }
+    fetchData();
+  }, []);
+
+  return { data, loading, error };
+}
+```
+
+---
+
+## Styling
+
+### Responsive Grid
+```css
+.dashboard {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 24px;
+  padding: 24px;
+}
+
+@media (max-width: 768px) {
+  .dashboard {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+---
+
+## Requirements Traceability
+
+| Requirement | Component | File |
+|-------------|-----------|------|
+| US-1 | MetricCard | MetricCard.jsx |
+| US-2 | TaskCompletionChart | TaskCompletionChart.jsx |
+| US-3 | TaskList | TaskList.jsx |
+| FR-1 | Dashboard | Dashboard.jsx |
+| FR-2 | MetricCard | MetricCard.jsx |
+| FR-3 | TaskCompletionChart | TaskCompletionChart.jsx |
+| FR-4 | TaskList | TaskList.jsx |
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23

package/docs/examples/add-user-dashboard/requirements.md

@@ -0,0 +1,143 @@
+# User Dashboard - Requirements
+
+> Example Spec demonstrating React UI feature development
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Spec Type**: Example - UI Feature
+
+---
+
+## Overview
+
+This Spec demonstrates how to structure requirements for a React dashboard feature. We'll build a user analytics dashboard with data visualization, covering common UI patterns like component composition, state management, API integration, and responsive design.
+
+**Learning Points:**
+- Component hierarchy design
+- State management patterns
+- Data visualization
+- Responsive layouts
+- API integration
+
+---
+
+## User Stories
+
+### US-1: View Dashboard Overview
+**As a** user  
+**I want to** see an overview of my key metrics  
+**So that** I can quickly understand my account status
+
+**Acceptance Criteria:**
+- WHEN I navigate to `/dashboard` THEN I see 4 metric cards (total tasks, completed, in progress, pending)
+- WHEN metrics load THEN I see loading skeletons
+- WHEN metrics fail to load THEN I see error message with retry button
+- WHEN I view on mobile THEN cards stack vertically
+
+### US-2: View Task Completion Chart
+**As a** user  
+**I want to** see a chart of my task completion over time  
+**So that** I can track my productivity
+
+**Acceptance Criteria:**
+- WHEN I view dashboard THEN I see a line chart showing last 7 days of task completions
+- WHEN I hover over data points THEN I see exact values in tooltip
+- WHEN chart loads THEN it animates smoothly
+- WHEN I view on mobile THEN chart is responsive
+
+### US-3: View Recent Tasks List
+**As a** user  
+**I want to** see my most recent tasks  
+**So that** I can quickly access current work
+
+**Acceptance Criteria:**
+- WHEN I view dashboard THEN I see 5 most recent tasks
+- WHEN I click a task THEN I navigate to task detail page
+- WHEN I have no tasks THEN I see empty state with "Create Task" button
+- WHEN tasks load THEN I see loading state
+
+---
+
+## Functional Requirements
+
+### FR-1: Dashboard Layout
+- Responsive grid layout (desktop: 2 columns, mobile: 1 column)
+- Header with user name and logout button
+- Metric cards section
+- Chart section
+- Recent tasks section
+
+### FR-2: Metric Cards
+- Display 4 metrics: Total, Completed, In Progress, Pending
+- Show count and percentage change from last week
+- Color-coded indicators (green: increase, red: decrease)
+- Loading skeleton during data fetch
+
+### FR-3: Task Completion Chart
+- Line chart showing last 7 days
+- X-axis: dates, Y-axis: task count
+- Interactive tooltips on hover
+- Smooth animations
+- Responsive sizing
+
+### FR-4: Recent Tasks List
+- Display 5 most recent tasks
+- Show task title, status, and date
+- Clickable to navigate to detail
+- Empty state when no tasks
+- Loading state during fetch
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+- Initial render < 1 second
+- Chart animation < 500ms
+- Smooth scrolling on mobile
+
+### NFR-2: Accessibility
+- WCAG 2.1 AA compliance
+- Keyboard navigation support
+- Screen reader friendly
+- Proper ARIA labels
+
+### NFR-3: Responsive Design
+- Desktop: 1024px+
+- Tablet: 768px-1023px
+- Mobile: 320px-767px
+
+---
+
+## Component Hierarchy
+
+```
+Dashboard
+├── DashboardHeader
+├── MetricsSection
+│   ├── MetricCard (x4)
+│   └── MetricCardSkeleton
+├── ChartSection
+│   ├── TaskCompletionChart
+│   └── ChartSkeleton
+└── RecentTasksSection
+    ├── TaskList
+    │   └── TaskListItem (x5)
+    ├── EmptyState
+    └── TaskListSkeleton
+```
+
+---
+
+## API Endpoints
+
+- `GET /api/v1/dashboard/metrics` - Fetch metric data
+- `GET /api/v1/dashboard/chart-data` - Fetch chart data
+- `GET /api/v1/tasks?limit=5&sort=recent` - Fetch recent tasks
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23

package/docs/examples/add-user-dashboard/tasks.md

@@ -0,0 +1,91 @@
+# User Dashboard - Tasks
+
+> Implementation plan for React dashboard
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23
+
+---
+
+## Phase 1: Setup
+
+- [ ] 1.1 Install dependencies (react, recharts, axios)
+- [ ] 1.2 Create component directory structure
+- [ ] 1.3 Set up CSS Modules configuration
+
+---
+
+## Phase 2: Core Components
+
+- [ ] 2.1 Create MetricCard component
+  - Implement props interface
+  - Add styling with CSS Modules
+  - Add loading skeleton variant
+  - Write unit tests
+
+- [ ] 2.2 Create TaskCompletionChart component
+  - Integrate Recharts LineChart
+  - Implement responsive container
+  - Add tooltip formatting
+  - Add loading skeleton
+  - Write unit tests
+
+- [ ] 2.3 Create TaskList component
+  - Implement task list rendering
+  - Add click handlers
+  - Add empty state
+  - Add loading skeleton
+  - Write unit tests
+
+---
+
+## Phase 3: Dashboard Container
+
+- [ ] 3.1 Create useDashboard hook
+  - Implement data fetching
+  - Handle loading states
+  - Handle error states
+  - Write unit tests
+
+- [ ] 3.2 Create Dashboard page component
+  - Compose all child components
+  - Implement responsive grid layout
+  - Add error boundary
+  - Write integration tests
+
+---
+
+## Phase 4: Styling & Polish
+
+- [ ] 4.1 Implement responsive design
+  - Desktop layout (2 columns)
+  - Tablet layout (2 columns)
+  - Mobile layout (1 column)
+  - Test on different screen sizes
+
+- [ ] 4.2 Add animations
+  - Chart entrance animation
+  - Card hover effects
+  - Loading skeleton animations
+
+- [ ] 4.3 Accessibility improvements
+  - Add ARIA labels
+  - Test keyboard navigation
+  - Test with screen reader
+  - Ensure color contrast
+
+---
+
+## Phase 5: Testing
+
+- [ ] 5.1 Unit tests for all components
+- [ ] 5.2 Integration tests for Dashboard
+- [ ] 5.3 Visual regression tests
+- [ ] 5.4 Accessibility tests
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23