Phase 2 — Normalize file naming (#59)

* docs(naming): drop scrum4me- prefix from doc filenames Rename 10 docs/scrum4me-*.md files to unprefixed kebab-case names. Update every internal link in docs/, CLAUDE.md, AGENTS.md, README.md. * docs(naming): lowercase API.md and MD3 filenames Rename docs/API.md → docs/api.md and docs/MD3_Color_Scheme_Documentation.md → docs/md3-color-scheme.md. Update all internal links across 7 files. * docs(naming): rename plan file to kebab-case ASCII Rename "docs/plans/Tweede Claude Agent — Planning Agent.md" → docs/plans/tweede-claude-agent-planning.md. No external links needed updating. * docs(naming): rename middleware.md to proxy.md (next 16) docs/patterns/middleware.md → docs/patterns/proxy.md following the Next.js 16 proxy.ts rename. Update link in CLAUDE.md. * docs(naming): polish CLAUDE.md doc-index after renames Fix doubled scrum4me-scrum4me-mcp repo references (cascade from prior sed) in CLAUDE.md, docs/architecture.md, backlog.md, agent-instruction-audit.md, and plans/ST-1109. Update 'Middleware' label to 'Proxy middleware' in patterns table.
2026-05-03 03:00:47 +02:00 · 2026-05-03 03:00:47 +02:00 · e10f8f81bc
commit e10f8f81bc
parent dc3832ad54
27 changed files with 101 additions and 101 deletions
--- a/docs/md3-color-scheme.md
+++ b/docs/md3-color-scheme.md
@ -0,0 +1,941 @@
+# Material Design 3 Color Scheme Documentation
+## Project Management Application for Scrum Teams
+
+**Version:** 1.0  
+**Date:** April 22, 2026  
+**Application:** Desktop-first fullstack web application for solo developers and small Scrum Teams
+
+---
+
+## Table of Contents
+
+1. [Color Philosophy](#color-philosophy)
+2. [Complete Color Palette](#complete-color-palette)
+3. [Surface Elevation System](#surface-elevation-system)
+4. [Color Roles](#color-roles)
+5. [Semantic States](#semantic-states)
+6. [Project Management Colors](#project-management-colors)
+7. [Usage Examples](#usage-examples)
+8. [Implementation Guide](#implementation-guide)
+9. [Accessibility](#accessibility)
+10. [Best Practices](#best-practices)
+
+---
+
+## Color Philosophy
+
+This color scheme follows Material Design 3 principles with three main color roles optimized for productivity software:
+
+- **Primary (Blue)** - Represents productivity, trust, and professionalism. Used for main actions and navigation.
+- **Secondary (Purple)** - Represents planning and organization. Used for supporting UI elements.
+- **Tertiary (Teal)** - Represents progress and data visualization. Used for highlights and metrics.
+
+The system uses **tonal elevation** instead of shadows to create depth, providing a modern, clean interface suitable for extended desktop work sessions.
+
+---
+
+## Complete Color Palette
+
+### Light Theme Colors
+
+#### Primary Colors (Blue - Productivity)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--primary` | `#0061a4` | Primary buttons, key actions |
+| `--primary-foreground` | `#ffffff` | Text on primary background |
+| `--primary-container` | `#d1e4ff` | Low emphasis primary elements |
+| `--primary-container-foreground` | `#001d36` | Text on primary container |
+
+#### Secondary Colors (Purple - Planning)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--secondary` | `#5b5e71` | Secondary buttons, less critical actions |
+| `--secondary-foreground` | `#ffffff` | Text on secondary background |
+| `--secondary-container` | `#dfe1f9` | Low emphasis secondary elements |
+| `--secondary-container-foreground` | `#181b2c` | Text on secondary container |
+
+#### Tertiary Colors (Teal - Progress)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--tertiary` | `#006874` | Highlights, progress indicators |
+| `--tertiary-foreground` | `#ffffff` | Text on tertiary background |
+| `--tertiary-container` | `#97f0ff` | Low emphasis tertiary elements |
+| `--tertiary-container-foreground` | `#001f24` | Text on tertiary container |
+
+#### Surface Colors (Elevation System)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--background` | `#fdfcff` | Main app background |
+| `--foreground` | `#1b1b1f` | Main text color |
+| `--surface-container-lowest` | `#ffffff` | Highest elevation (dialogs) |
+| `--surface-container-low` | `#f7f5fc` | Cards, elevated containers |
+| `--surface-container` | `#f1eff6` | Default container background |
+| `--surface-container-high` | `#ebeaf0` | Nested containers |
+| `--surface-container-highest` | `#e6e3ea` | Lowest elevation |
+
+#### Semantic State Colors
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--success` | `#006e1c` | Success states, completed items |
+| `--success-foreground` | `#ffffff` | Text on success background |
+| `--success-container` | `#92f894` | Low emphasis success |
+| `--warning` | `#735b00` | Warning states, attention needed |
+| `--warning-foreground` | `#ffffff` | Text on warning background |
+| `--warning-container` | `#ffdf9d` | Low emphasis warning |
+| `--error` | `#ba1a1a` | Error states, failures |
+| `--error-foreground` | `#ffffff` | Text on error background |
+| `--error-container` | `#ffdad6` | Low emphasis error |
+| `--info` | `#006493` | Information, neutral alerts |
+| `--info-foreground` | `#ffffff` | Text on info background |
+| `--info-container` | `#c9e6ff` | Low emphasis info |
+
+#### Project Management Specific Colors
+
+**Work Item Status**
+| Color Token | Hex Code | Status |
+|-------------|----------|--------|
+| `--status-todo` | `#6750a4` | Not started (Purple) |
+| `--status-in-progress` | `#0061a4` | Active work (Blue) |
+| `--status-done` | `#006e1c` | Completed (Green) |
+| `--status-blocked` | `#ba1a1a` | Blocked/Issues (Red) |
+
+**Priority Levels**
+| Color Token | Hex Code | Priority |
+|-------------|----------|----------|
+| `--priority-critical` | `#ba1a1a` | Critical (Red) |
+| `--priority-high` | `#c75300` | High (Orange) |
+| `--priority-medium` | `#735b00` | Medium (Yellow) |
+| `--priority-low` | `#006874` | Low (Teal) |
+
+---
+
+### Dark Theme Colors
+
+#### Primary Colors (Blue - Productivity)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--primary` | `#9fcbfa` | Primary buttons, key actions |
+| `--primary-foreground` | `#003257` | Text on primary background |
+| `--primary-container` | `#00497b` | Low emphasis primary elements |
+| `--primary-container-foreground` | `#d1e4ff` | Text on primary container |
+
+#### Secondary Colors (Purple - Planning)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--secondary` | `#c3c4dd` | Secondary buttons |
+| `--secondary-foreground` | `#2c2f42` | Text on secondary background |
+| `--secondary-container` | `#434659` | Low emphasis secondary elements |
+| `--secondary-container-foreground` | `#dfe1f9` | Text on secondary container |
+
+#### Tertiary Colors (Teal - Progress)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--tertiary` | `#4fd8eb` | Highlights, progress indicators |
+| `--tertiary-foreground` | `#00363d` | Text on tertiary background |
+| `--tertiary-container` | `#004f58` | Low emphasis tertiary elements |
+| `--tertiary-container-foreground` | `#97f0ff` | Text on tertiary container |
+
+#### Surface Colors (Elevation System)
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--background` | `#1b1b1f` | Main app background |
+| `--foreground` | `#e4e1e9` | Main text color |
+| `--surface-container-lowest` | `#0f0e13` | Highest elevation (dialogs) |
+| `--surface-container-low` | `#232227` | Cards, elevated containers |
+| `--surface-container` | `#27262b` | Default container background |
+| `--surface-container-high` | `#322f36` | Nested containers |
+| `--surface-container-highest` | `#3d3a41` | Lowest elevation |
+
+#### Semantic State Colors
+| Color Token | Hex Code | Usage |
+|-------------|----------|-------|
+| `--success` | `#77db77` | Success states |
+| `--success-container` | `#005313` | Low emphasis success |
+| `--warning` | `#efc047` | Warning states |
+| `--warning-container` | `#574400` | Low emphasis warning |
+| `--error` | `#ffb4ab` | Error states |
+| `--error-container` | `#93000a` | Low emphasis error |
+| `--info` | `#87ceff` | Information |
+| `--info-container` | `#004c6d` | Low emphasis info |
+
+#### Project Management Specific Colors (Dark)
+
+**Work Item Status**
+| Color Token | Hex Code | Status |
+|-------------|----------|--------|
+| `--status-todo` | `#cfbdfe` | Not started (Purple) |
+| `--status-in-progress` | `#9fcbfa` | Active work (Blue) |
+| `--status-done` | `#77db77` | Completed (Green) |
+| `--status-blocked` | `#ffb4ab` | Blocked/Issues (Red) |
+
+**Priority Levels**
+| Color Token | Hex Code | Priority |
+|-------------|----------|----------|
+| `--priority-critical` | `#ffb4ab` | Critical (Red) |
+| `--priority-high` | `#ffb68d` | High (Orange) |
+| `--priority-medium` | `#efc047` | Medium (Yellow) |
+| `--priority-low` | `#4fd8eb` | Low (Teal) |
+
+---
+
+## Surface Elevation System
+
+Material Design 3 uses **tonal elevation** to create depth. Higher surfaces are lighter (in light mode) or darker (in dark mode).
+
+### Hierarchy (from highest to lowest elevation)
+
+1. **surface-container-lowest** - Dialogs, modals, popovers
+2. **surface-container-low** - Cards, panels, elevated containers
+3. **surface-container** - Default container background
+4. **surface-container-high** - Nested containers, grouped elements
+5. **surface-container-highest** - Background-level containers
+
+### Tailwind Usage
+
+```tsx
+bg-surface-container-lowest
+bg-surface-container-low
+bg-surface-container
+bg-surface-container-high
+bg-surface-container-highest
+```
+
+---
+
+## Color Roles
+
+### Primary (Productivity & Trust)
+
+Use for:
+- Main action buttons
+- Navigation highlights
+- Active states
+- Key interactive elements
+
+**Examples:**
+```tsx
+// Filled button
+<button className="bg-primary text-primary-foreground">
+  Create Sprint
+</button>
+
+// Outline button (less emphasis)
+<button className="border-2 border-primary text-primary">
+  View Details
+</button>
+
+// Container variant (even less emphasis)
+<div className="bg-primary-container text-primary-container-foreground">
+  Selected item
+</div>
+```
+
+### Secondary (Planning & Support)
+
+Use for:
+- Secondary actions
+- Supporting UI elements
+- Less critical interactive elements
+- Toolbar items
+
+**Examples:**
+```tsx
+// Secondary action
+<button className="bg-secondary text-secondary-foreground">
+  Filter
+</button>
+
+// Subtle highlight
+<div className="bg-secondary-container text-secondary-container-foreground">
+  Planning phase
+</div>
+```
+
+### Tertiary (Progress & Highlights)
+
+Use for:
+- Progress indicators
+- Data visualization accents
+- Highlights and callouts
+- Metrics
+
+**Examples:**
+```tsx
+// Progress indicator
+<div className="bg-tertiary text-tertiary-foreground">
+  75% Complete
+</div>
+
+// Metric badge
+<span className="bg-tertiary-container text-tertiary-container-foreground">
+  +12 stories
+</span>
+```
+
+---
+
+## Semantic States
+
+### Success (Completed, Positive)
+
+Use for:
+- Completed tasks
+- Success messages
+- Positive confirmations
+- Achievement indicators
+
+```tsx
+<div className="bg-success text-success-foreground">
+  ✓ Sprint completed successfully
+</div>
+
+<div className="bg-success-container text-success-container-foreground">
+  8 stories completed this week
+</div>
+```
+
+### Warning (Attention Needed)
+
+Use for:
+- Warnings
+- Potential issues
+- Items needing attention
+- Approaching deadlines
+
+```tsx
+<div className="bg-warning text-warning-foreground">
+  ⚠ Sprint deadline in 2 days
+</div>
+
+<div className="bg-warning-container text-warning-container-foreground">
+  3 stories at risk
+</div>
+```
+
+### Error (Failures, Critical Issues)
+
+Use for:
+- Errors
+- Failed operations
+- Blocked items
+- Critical alerts
+
+```tsx
+<div className="bg-error text-error-foreground">
+  ✗ Failed to save changes
+</div>
+
+<div className="bg-error-container text-error-container-foreground">
+  1 story blocked
+</div>
+```
+
+### Info (Neutral Information)
+
+Use for:
+- Informational messages
+- Tips and hints
+- Neutral notifications
+- Help text
+
+```tsx
+<div className="bg-info text-info-foreground">
+  ℹ New feature available
+</div>
+
+<div className="bg-info-container text-info-container-foreground">
+  Tip: Use drag-and-drop to reorder
+</div>
+```
+
+---
+
+## Project Management Colors
+
+### Work Item Status Colors
+
+These colors are specifically designed for Scrum workflow states:
+
+#### To Do (Purple - #6750a4 / #cfbdfe)
+- Not started items
+- Backlog items
+- Planned work
+
+```tsx
+<span className="bg-status-todo text-white px-3 py-1 rounded-full">
+  To Do
+</span>
+```
+
+#### In Progress (Blue - #0061a4 / #9fcbfa)
+- Active development
+- Current sprint items
+- Work in flight
+
+```tsx
+<span className="bg-status-in-progress text-white px-3 py-1 rounded-full">
+  In Progress
+</span>
+```
+
+#### Done (Green - #006e1c / #77db77)
+- Completed items
+- Accepted work
+- Delivered features
+
+```tsx
+<span className="bg-status-done text-white px-3 py-1 rounded-full">
+  Done
+</span>
+```
+
+#### Blocked (Red - #ba1a1a / #ffb4ab)
+- Blocked items
+- Impediments
+- Issues preventing progress
+
+```tsx
+<span className="bg-status-blocked text-white px-3 py-1 rounded-full">
+  Blocked
+</span>
+```
+
+### Priority Level Colors
+
+#### Critical (Red - #ba1a1a / #ffb4ab)
+- Production issues
+- Show-stopper bugs
+- Immediate action required
+
+```tsx
+<span className="bg-priority-critical text-white px-2 py-1 rounded text-sm">
+  Critical
+</span>
+```
+
+#### High (Orange - #c75300 / #ffb68d)
+- Important features
+- Significant bugs
+- Near-term priorities
+
+```tsx
+<span className="bg-priority-high text-white px-2 py-1 rounded text-sm">
+  High
+</span>
+```
+
+#### Medium (Yellow - #735b00 / #efc047)
+- Standard priority
+- Regular backlog items
+- Scheduled work
+
+```tsx
+<span className="bg-priority-medium text-white px-2 py-1 rounded text-sm">
+  Medium
+</span>
+```
+
+#### Low (Teal - #006874 / #4fd8eb)
+- Nice-to-have features
+- Minor improvements
+- Future considerations
+
+```tsx
+<span className="bg-priority-low text-white px-2 py-1 rounded text-sm">
+  Low
+</span>
+```
+
+---
+
+## Usage Examples
+
+### Product Backlog Item Card
+
+```tsx
+<div className="bg-card text-card-foreground p-6 rounded-lg border border-border">
+  <div className="flex items-start justify-between mb-3">
+    <h3 className="text-lg">Implement OAuth2 Authentication</h3>
+    <span className="bg-priority-high text-white px-3 py-1 rounded-md text-sm">
+      High
+    </span>
+  </div>
+  
+  <p className="text-muted-foreground mb-4">
+    Add OAuth2 support for Google and GitHub authentication providers
+    with proper session management and refresh token handling.
+  </p>
+  
+  <div className="flex items-center justify-between">
+    <div className="flex gap-2">
+      <span className="bg-status-in-progress text-white px-3 py-1 rounded-full text-sm">
+        In Progress
+      </span>
+      <span className="text-muted-foreground text-sm">
+        Story Points: 8
+      </span>
+    </div>
+    
+    <div className="text-sm text-muted-foreground">
+      Assigned to: Sarah
+    </div>
+  </div>
+</div>
+```
+
+### Sprint Dashboard Card
+
+```tsx
+<div className="bg-surface-container-low p-6 rounded-xl">
+  <h2 className="mb-4">Sprint 12 Progress</h2>
+  
+  <div className="bg-surface-container p-4 rounded-lg mb-4">
+    <div className="space-y-3">
+      <div className="flex justify-between items-center">
+        <span className="text-muted-foreground">Total Stories</span>
+        <span className="text-xl">15</span>
+      </div>
+      
+      <div className="flex justify-between items-center">
+        <span className="text-muted-foreground">Completed</span>
+        <span className="text-xl text-success">10</span>
+      </div>
+      
+      <div className="flex justify-between items-center">
+        <span className="text-muted-foreground">In Progress</span>
+        <span className="text-xl text-info">4</span>
+      </div>
+      
+      <div className="flex justify-between items-center">
+        <span className="text-muted-foreground">Blocked</span>
+        <span className="text-xl text-error">1</span>
+      </div>
+    </div>
+  </div>
+  
+  <div className="space-y-2">
+    <div className="flex justify-between text-sm">
+      <span className="text-muted-foreground">Progress</span>
+      <span>67%</span>
+    </div>
+    <div className="w-full bg-surface-container-highest rounded-full h-3">
+      <div 
+        className="bg-success h-3 rounded-full transition-all" 
+        style={{ width: '67%' }}
+      />
+    </div>
+  </div>
+</div>
+```
+
+### Kanban Board Column
+
+```tsx
+<div className="bg-surface-container p-4 rounded-lg min-w-80">
+  <div className="flex items-center justify-between mb-4">
+    <h3 className="flex items-center gap-2">
+      <span className="w-3 h-3 rounded-full bg-status-in-progress" />
+      In Progress
+    </h3>
+    <span className="bg-surface-container-high text-muted-foreground px-2 py-1 rounded text-sm">
+      4
+    </span>
+  </div>
+  
+  <div className="space-y-3">
+    {/* Story card */}
+    <div className="bg-surface-container-low p-3 rounded-lg border border-border hover:border-primary cursor-pointer transition-colors">
+      <div className="flex items-start justify-between mb-2">
+        <h4 className="text-sm">Fix login redirect issue</h4>
+        <span className="bg-priority-critical text-white px-2 py-0.5 rounded text-xs">
+          Critical
+        </span>
+      </div>
+      <p className="text-xs text-muted-foreground mb-3">
+        Users are redirected to wrong page after login
+      </p>
+      <div className="flex items-center justify-between">
+        <span className="text-xs text-muted-foreground">SP: 3</span>
+        <div className="w-6 h-6 rounded-full bg-primary text-primary-foreground flex items-center justify-center text-xs">
+          JD
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Action Buttons
+
+```tsx
+{/* Primary action */}
+<button className="px-6 py-3 bg-primary text-primary-foreground rounded-lg hover:opacity-90 transition-opacity">
+  Start Sprint
+</button>
+
+{/* Secondary action */}
+<button className="px-6 py-3 bg-secondary text-secondary-foreground rounded-lg hover:opacity-90 transition-opacity">
+  Save as Draft
+</button>
+
+{/* Outlined action */}
+<button className="px-6 py-3 border-2 border-primary text-primary rounded-lg hover:bg-primary-container transition-colors">
+  View Backlog
+</button>
+
+{/* Tertiary/text action */}
+<button className="px-6 py-3 text-primary hover:bg-primary-container rounded-lg transition-colors">
+  Cancel
+</button>
+
+{/* Destructive action */}
+<button className="px-6 py-3 bg-error text-error-foreground rounded-lg hover:opacity-90 transition-opacity">
+  Delete Sprint
+</button>
+```
+
+### Status Badges
+
+```tsx
+{/* Pill-shaped status badges */}
+<div className="flex gap-2">
+  <span className="inline-flex items-center gap-1 px-3 py-1 bg-status-todo text-white rounded-full text-sm">
+    <svg className="w-3 h-3" fill="currentColor" viewBox="0 0 8 8">
+      <circle cx="4" cy="4" r="3" />
+    </svg>
+    To Do
+  </span>
+  
+  <span className="inline-flex items-center gap-1 px-3 py-1 bg-status-in-progress text-white rounded-full text-sm">
+    <svg className="w-3 h-3 animate-spin" fill="none" viewBox="0 0 24 24">
+      <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" />
+      <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
+    </svg>
+    In Progress
+  </span>
+  
+  <span className="inline-flex items-center gap-1 px-3 py-1 bg-status-done text-white rounded-full text-sm">
+    <svg className="w-3 h-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+      <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={3} d="M5 13l4 4L19 7" />
+    </svg>
+    Done
+  </span>
+  
+  <span className="inline-flex items-center gap-1 px-3 py-1 bg-status-blocked text-white rounded-full text-sm">
+    <svg className="w-3 h-3" fill="currentColor" viewBox="0 0 20 20">
+      <path fillRule="evenodd" d="M13.477 14.89A6 6 0 015.11 6.524l8.367 8.368zm1.414-1.414L6.524 5.11a6 6 0 018.367 8.367zM18 10a8 8 0 11-16 0 8 8 0 0116 0z" clipRule="evenodd" />
+    </svg>
+    Blocked
+  </span>
+</div>
+```
+
+---
+
+## Implementation Guide
+
+### Setting Up the Color System
+
+The color system is defined in `/src/styles/theme.css`. All colors use CSS custom properties (variables) for easy theming.
+
+### Tailwind CSS Configuration
+
+All color tokens are automatically available as Tailwind classes through the `@theme inline` directive:
+
+```css
+/* Colors are available as: */
+bg-primary
+text-primary-foreground
+border-primary-container
+bg-surface-container-low
+bg-status-in-progress
+bg-priority-high
+/* etc. */
+```
+
+### Dark Mode Toggle
+
+Toggle dark mode with JavaScript:
+
+```tsx
+// Toggle dark mode
+document.documentElement.classList.toggle('dark');
+
+// Set dark mode
+document.documentElement.classList.add('dark');
+
+// Set light mode
+document.documentElement.classList.remove('dark');
+
+// React component example
+function DarkModeToggle() {
+  const [isDark, setIsDark] = useState(false);
+  
+  const toggleDark = () => {
+    setIsDark(!isDark);
+    document.documentElement.classList.toggle('dark');
+  };
+  
+  return (
+    <button onClick={toggleDark}>
+      {isDark ? '☀️ Light Mode' : '🌙 Dark Mode'}
+    </button>
+  );
+}
+```
+
+### Using with shadcn Components
+
+All shadcn/ui components work seamlessly with this color system. The legacy color tokens (card, popover, muted, accent, destructive) are mapped to appropriate MD3 colors.
+
+```tsx
+// shadcn Button component automatically uses the color system
+<Button>Primary Action</Button>
+<Button variant="secondary">Secondary Action</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outlined</Button>
+```
+
+---
+
+## Accessibility
+
+### Contrast Ratios
+
+All color combinations meet **WCAG AA** standards:
+
+- **Normal text**: Minimum 4.5:1 contrast ratio
+- **Large text**: Minimum 3:1 contrast ratio
+- **UI components**: Minimum 3:1 contrast ratio
+
+### Color Blindness Considerations
+
+The color system is designed to be distinguishable for users with common types of color blindness:
+
+1. **Status colors** use distinct hues that remain distinguishable in deuteranopia, protanopia, and tritanopia
+2. **Priority levels** use a progression from cool (low) to warm (high) colors
+3. **All status indicators** should include text labels, not just color
+
+### Best Practices for Accessibility
+
+```tsx
+// ✅ Good: Color + Icon + Text
+<span className="bg-status-done text-white px-3 py-1 rounded-full">
+  <CheckIcon className="w-4 h-4 inline" />
+  Done
+</span>
+
+// ❌ Bad: Color only
+<span className="w-4 h-4 bg-status-done rounded-full" />
+
+// ✅ Good: Semantic HTML + ARIA
+<button 
+  className="bg-primary text-primary-foreground"
+  aria-label="Start new sprint"
+>
+  Start Sprint
+</button>
+
+// ✅ Good: Status with aria-label
+<div 
+  className="bg-status-blocked"
+  role="status"
+  aria-label="This item is blocked"
+>
+  Blocked
+</div>
+```
+
+---
+
+## Best Practices
+
+### 1. Use Surface Elevation for Depth
+
+❌ **Don't use shadows for elevation**
+```tsx
+<div className="shadow-lg">Card</div>
+```
+
+✅ **Do use surface tones**
+```tsx
+<div className="bg-surface-container-low">Card</div>
+```
+
+### 2. Use Container Variants for Lower Emphasis
+
+❌ **Don't reduce opacity**
+```tsx
+<button className="bg-primary opacity-50">Secondary Action</button>
+```
+
+✅ **Do use container variants**
+```tsx
+<button className="bg-primary-container text-primary-container-foreground">
+  Secondary Action
+</button>
+```
+
+### 3. Consistent Status Colors
+
+❌ **Don't use arbitrary colors**
+```tsx
+<span className="bg-green-500">Complete</span>
+<span className="bg-emerald-600">Finished</span>
+```
+
+✅ **Do use semantic status colors**
+```tsx
+<span className="bg-status-done">Complete</span>
+<span className="bg-status-done">Finished</span>
+```
+
+### 4. Semantic Color Usage
+
+❌ **Don't use colors for decoration only**
+```tsx
+<div className="bg-error">This is important information</div>
+```
+
+✅ **Do use colors for their semantic meaning**
+```tsx
+<div className="bg-error text-error-foreground">
+  Error: Failed to save changes
+</div>
+
+<div className="bg-info text-info-foreground">
+  This is important information
+</div>
+```
+
+### 5. Proper Text Contrast
+
+❌ **Don't forget foreground colors**
+```tsx
+<button className="bg-primary">Click me</button>
+```
+
+✅ **Do include foreground colors**
+```tsx
+<button className="bg-primary text-primary-foreground">Click me</button>
+```
+
+### 6. Layering and Nesting
+
+When nesting containers, move down the elevation scale:
+
+```tsx
+<div className="bg-surface-container-low p-6">
+  {/* Outer container */}
+  
+  <div className="bg-surface-container p-4">
+    {/* Inner container - lower elevation */}
+    
+    <div className="bg-surface-container-high p-3">
+      {/* Deepest container - lowest elevation */}
+    </div>
+  </div>
+</div>
+```
+
+### 7. Interactive States
+
+```tsx
+// Buttons with hover states
+<button className="bg-primary text-primary-foreground hover:opacity-90 transition-opacity">
+  Click me
+</button>
+
+// Cards with hover states
+<div className="bg-card border border-border hover:border-primary transition-colors cursor-pointer">
+  Interactive card
+</div>
+
+// Focus states (automatically handled by theme)
+<input className="border border-border focus:ring-2 focus:ring-primary" />
+```
+
+---
+
+## Quick Reference
+
+### Most Common Combinations
+
+```tsx
+// Primary button
+bg-primary text-primary-foreground
+
+// Secondary button
+bg-secondary text-secondary-foreground
+
+// Card
+bg-card text-card-foreground border border-border
+
+// Success message
+bg-success-container text-success-container-foreground
+
+// Warning banner
+bg-warning text-warning-foreground
+
+// Error alert
+bg-error text-error-foreground
+
+// Info panel
+bg-info-container text-info-container-foreground
+
+// Status badge - To Do
+bg-status-todo text-white
+
+// Status badge - In Progress
+bg-status-in-progress text-white
+
+// Status badge - Done
+bg-status-done text-white
+
+// Priority badge - High
+bg-priority-high text-white
+
+// Muted text
+text-muted-foreground
+
+// Border
+border-border
+```
+
+---
+
+## Additional Resources
+
+### Color Tools
+- **Material Theme Builder**: https://m3.material.io/theme-builder
+- **Contrast Checker**: https://webaim.org/resources/contrastchecker/
+- **Color Blind Simulator**: https://www.color-blindness.com/coblis-color-blindness-simulator/
+
+### Documentation
+- **Material Design 3**: https://m3.material.io
+- **Tailwind CSS**: https://tailwindcss.com
+- **shadcn/ui**: https://ui.shadcn.com
+
+---
+
+## Version History
+
+### Version 1.0 (April 22, 2026)
+- Initial color scheme based on Material Design 3
+- Complete light and dark theme support
+- Project management specific colors (status, priority)
+- Full shadcn/ui compatibility
+- Accessibility WCAG AA compliant
+
+---
+
+## Support
+
+For questions or issues with the color system:
+- Review the live demo in the application
+- Check `COLOR_SYSTEM.md` for additional examples
+- Refer to `/src/styles/theme.css` for color definitions
+
+---
+
+**End of Documentation**