From 0342498f63400a821dbe40d0a8fc2d8eb0ff2e65 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Sun, 3 May 2026 01:00:01 +0200 Subject: [PATCH] docs(split): merge md3-color-scheme into design/styling --- docs/INDEX.md | 1 - docs/design/md3-color-scheme.md | 949 ----------------------- docs/design/styling.md | 923 ++++++++++++++++++++++ docs/plans/docs-restructure-ai-lookup.md | 2 +- docs/plans/docs-restructure-pbi-spec.md | 6 +- 5 files changed, 927 insertions(+), 954 deletions(-) delete mode 100644 docs/design/md3-color-scheme.md diff --git a/docs/INDEX.md b/docs/INDEX.md index 6fd6d7e..9e4c214 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -73,7 +73,6 @@ Auto-generated on 2026-05-02 from front-matter and headings. | [Scrum4Me — Implementatie Backlog](./backlog/index.md) | `backlog/index.md` | active | 2026-05-03 | | [DevPlanner — Product Backlog](./backlog/product-historical.md) | `backlog/product-historical.md` | active | 2026-05-03 | | [Agent Instruction Audit](./decisions/agent-instructions-history.md) | `decisions/agent-instructions-history.md` | active | 2026-05-03 | -| [Material Design 3 Color Scheme Documentation](./design/md3-color-scheme.md) | `design/md3-color-scheme.md` | active | 2026-05-03 | | [Scrum4Me — Styling & Design System](./design/styling.md) | `design/styling.md` | active | 2026-05-03 | | [Obsidian as Personal Authoring Layer](./obsidian-authoring.md) | `obsidian-authoring.md` | active | 2026-05-02 | | [Scrum4Me — API Test Plan](./qa/api-test-plan.md) | `qa/api-test-plan.md` | active | 2026-05-03 | diff --git a/docs/design/md3-color-scheme.md b/docs/design/md3-color-scheme.md deleted file mode 100644 index 90f75b3..0000000 --- a/docs/design/md3-color-scheme.md +++ /dev/null @@ -1,949 +0,0 @@ ---- -title: "Material Design 3 Color Scheme Documentation" -status: active -audience: [maintainer, contributor] -language: en -last_updated: 2026-05-03 ---- - -# 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 - - -// Outline button (less emphasis) - - -// Container variant (even less emphasis) -
- Selected item -
-``` - -### Secondary (Planning & Support) - -Use for: -- Secondary actions -- Supporting UI elements -- Less critical interactive elements -- Toolbar items - -**Examples:** -```tsx -// Secondary action - - -// Subtle highlight -
- Planning phase -
-``` - -### Tertiary (Progress & Highlights) - -Use for: -- Progress indicators -- Data visualization accents -- Highlights and callouts -- Metrics - -**Examples:** -```tsx -// Progress indicator -
- 75% Complete -
- -// Metric badge - - +12 stories - -``` - ---- - -## Semantic States - -### Success (Completed, Positive) - -Use for: -- Completed tasks -- Success messages -- Positive confirmations -- Achievement indicators - -```tsx -
- ✓ Sprint completed successfully -
- -
- 8 stories completed this week -
-``` - -### Warning (Attention Needed) - -Use for: -- Warnings -- Potential issues -- Items needing attention -- Approaching deadlines - -```tsx -
- ⚠ Sprint deadline in 2 days -
- -
- 3 stories at risk -
-``` - -### Error (Failures, Critical Issues) - -Use for: -- Errors -- Failed operations -- Blocked items -- Critical alerts - -```tsx -
- ✗ Failed to save changes -
- -
- 1 story blocked -
-``` - -### Info (Neutral Information) - -Use for: -- Informational messages -- Tips and hints -- Neutral notifications -- Help text - -```tsx -
- ℹ New feature available -
- -
- Tip: Use drag-and-drop to reorder -
-``` - ---- - -## 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 - - To Do - -``` - -#### In Progress (Blue - #0061a4 / #9fcbfa) -- Active development -- Current sprint items -- Work in flight - -```tsx - - In Progress - -``` - -#### Done (Green - #006e1c / #77db77) -- Completed items -- Accepted work -- Delivered features - -```tsx - - Done - -``` - -#### Blocked (Red - #ba1a1a / #ffb4ab) -- Blocked items -- Impediments -- Issues preventing progress - -```tsx - - Blocked - -``` - -### Priority Level Colors - -#### Critical (Red - #ba1a1a / #ffb4ab) -- Production issues -- Show-stopper bugs -- Immediate action required - -```tsx - - Critical - -``` - -#### High (Orange - #c75300 / #ffb68d) -- Important features -- Significant bugs -- Near-term priorities - -```tsx - - High - -``` - -#### Medium (Yellow - #735b00 / #efc047) -- Standard priority -- Regular backlog items -- Scheduled work - -```tsx - - Medium - -``` - -#### Low (Teal - #006874 / #4fd8eb) -- Nice-to-have features -- Minor improvements -- Future considerations - -```tsx - - Low - -``` - ---- - -## Usage Examples - -### Product Backlog Item Card - -```tsx -
-
-

Implement OAuth2 Authentication

- - High - -
- -

- Add OAuth2 support for Google and GitHub authentication providers - with proper session management and refresh token handling. -

- -
-
- - In Progress - - - Story Points: 8 - -
- -
- Assigned to: Sarah -
-
-
-``` - -### Sprint Dashboard Card - -```tsx -
-

Sprint 12 Progress

- -
-
-
- Total Stories - 15 -
- -
- Completed - 10 -
- -
- In Progress - 4 -
- -
- Blocked - 1 -
-
-
- -
-
- Progress - 67% -
-
-
-
-
-
-``` - -### Kanban Board Column - -```tsx -
-
-

- - In Progress -

- - 4 - -
- -
- {/* Story card */} -
-
-

Fix login redirect issue

- - Critical - -
-

- Users are redirected to wrong page after login -

-
- SP: 3 -
- JD -
-
-
-
-
-``` - -### Action Buttons - -```tsx -{/* Primary action */} - - -{/* Secondary action */} - - -{/* Outlined action */} - - -{/* Tertiary/text action */} - - -{/* Destructive action */} - -``` - -### Status Badges - -```tsx -{/* Pill-shaped status badges */} -
- - - - - To Do - - - - - - - - In Progress - - - - - - - Done - - - - - - - Blocked - -
-``` - ---- - -## 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 ( - - ); -} -``` - -### 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 - - - - -``` - ---- - -## 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 - - - Done - - -// ❌ Bad: Color only - - -// ✅ Good: Semantic HTML + ARIA - - -// ✅ Good: Status with aria-label -
- Blocked -
-``` - ---- - -## Best Practices - -### 1. Use Surface Elevation for Depth - -❌ **Don't use shadows for elevation** -```tsx -
Card
-``` - -✅ **Do use surface tones** -```tsx -
Card
-``` - -### 2. Use Container Variants for Lower Emphasis - -❌ **Don't reduce opacity** -```tsx - -``` - -✅ **Do use container variants** -```tsx - -``` - -### 3. Consistent Status Colors - -❌ **Don't use arbitrary colors** -```tsx -Complete -Finished -``` - -✅ **Do use semantic status colors** -```tsx -Complete -Finished -``` - -### 4. Semantic Color Usage - -❌ **Don't use colors for decoration only** -```tsx -
This is important information
-``` - -✅ **Do use colors for their semantic meaning** -```tsx -
- Error: Failed to save changes -
- -
- This is important information -
-``` - -### 5. Proper Text Contrast - -❌ **Don't forget foreground colors** -```tsx - -``` - -✅ **Do include foreground colors** -```tsx - -``` - -### 6. Layering and Nesting - -When nesting containers, move down the elevation scale: - -```tsx -
- {/* Outer container */} - -
- {/* Inner container - lower elevation */} - -
- {/* Deepest container - lowest elevation */} -
-
-
-``` - -### 7. Interactive States - -```tsx -// Buttons with hover states - - -// Cards with hover states -
- Interactive card -
- -// Focus states (automatically handled by theme) - -``` - ---- - -## 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** diff --git a/docs/design/styling.md b/docs/design/styling.md index 5bb00fe..f56d37b 100644 --- a/docs/design/styling.md +++ b/docs/design/styling.md @@ -676,3 +676,926 @@ components/ --- *Bijlage bij CLAUDE.md — lees beide voor je begint met bouwen.* + + +--- + +## MD3 Color Scheme + +## 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 + + +// Outline button (less emphasis) + + +// Container variant (even less emphasis) +
+ Selected item +
+``` + +### Secondary (Planning & Support) + +Use for: +- Secondary actions +- Supporting UI elements +- Less critical interactive elements +- Toolbar items + +**Examples:** +```tsx +// Secondary action + + +// Subtle highlight +
+ Planning phase +
+``` + +### Tertiary (Progress & Highlights) + +Use for: +- Progress indicators +- Data visualization accents +- Highlights and callouts +- Metrics + +**Examples:** +```tsx +// Progress indicator +
+ 75% Complete +
+ +// Metric badge + + +12 stories + +``` + +--- + +## Semantic States + +### Success (Completed, Positive) + +Use for: +- Completed tasks +- Success messages +- Positive confirmations +- Achievement indicators + +```tsx +
+ ✓ Sprint completed successfully +
+ +
+ 8 stories completed this week +
+``` + +### Warning (Attention Needed) + +Use for: +- Warnings +- Potential issues +- Items needing attention +- Approaching deadlines + +```tsx +
+ ⚠ Sprint deadline in 2 days +
+ +
+ 3 stories at risk +
+``` + +### Error (Failures, Critical Issues) + +Use for: +- Errors +- Failed operations +- Blocked items +- Critical alerts + +```tsx +
+ ✗ Failed to save changes +
+ +
+ 1 story blocked +
+``` + +### Info (Neutral Information) + +Use for: +- Informational messages +- Tips and hints +- Neutral notifications +- Help text + +```tsx +
+ ℹ New feature available +
+ +
+ Tip: Use drag-and-drop to reorder +
+``` + +--- + +## 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 + + To Do + +``` + +#### In Progress (Blue - #0061a4 / #9fcbfa) +- Active development +- Current sprint items +- Work in flight + +```tsx + + In Progress + +``` + +#### Done (Green - #006e1c / #77db77) +- Completed items +- Accepted work +- Delivered features + +```tsx + + Done + +``` + +#### Blocked (Red - #ba1a1a / #ffb4ab) +- Blocked items +- Impediments +- Issues preventing progress + +```tsx + + Blocked + +``` + +### Priority Level Colors + +#### Critical (Red - #ba1a1a / #ffb4ab) +- Production issues +- Show-stopper bugs +- Immediate action required + +```tsx + + Critical + +``` + +#### High (Orange - #c75300 / #ffb68d) +- Important features +- Significant bugs +- Near-term priorities + +```tsx + + High + +``` + +#### Medium (Yellow - #735b00 / #efc047) +- Standard priority +- Regular backlog items +- Scheduled work + +```tsx + + Medium + +``` + +#### Low (Teal - #006874 / #4fd8eb) +- Nice-to-have features +- Minor improvements +- Future considerations + +```tsx + + Low + +``` + +--- + +## Usage Examples + +### Product Backlog Item Card + +```tsx +
+
+

Implement OAuth2 Authentication

+ + High + +
+ +

+ Add OAuth2 support for Google and GitHub authentication providers + with proper session management and refresh token handling. +

+ +
+
+ + In Progress + + + Story Points: 8 + +
+ +
+ Assigned to: Sarah +
+
+
+``` + +### Sprint Dashboard Card + +```tsx +
+

Sprint 12 Progress

+ +
+
+
+ Total Stories + 15 +
+ +
+ Completed + 10 +
+ +
+ In Progress + 4 +
+ +
+ Blocked + 1 +
+
+
+ +
+
+ Progress + 67% +
+
+
+
+
+
+``` + +### Kanban Board Column + +```tsx +
+
+

+ + In Progress +

+ + 4 + +
+ +
+ {/* Story card */} +
+
+

Fix login redirect issue

+ + Critical + +
+

+ Users are redirected to wrong page after login +

+
+ SP: 3 +
+ JD +
+
+
+
+
+``` + +### Action Buttons + +```tsx +{/* Primary action */} + + +{/* Secondary action */} + + +{/* Outlined action */} + + +{/* Tertiary/text action */} + + +{/* Destructive action */} + +``` + +### Status Badges + +```tsx +{/* Pill-shaped status badges */} +
+ + + + + To Do + + + + + + + + In Progress + + + + + + + Done + + + + + + + Blocked + +
+``` + +--- + +## 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 ( + + ); +} +``` + +### 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 + + + + +``` + +--- + +## 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 + + + Done + + +// ❌ Bad: Color only + + +// ✅ Good: Semantic HTML + ARIA + + +// ✅ Good: Status with aria-label +
+ Blocked +
+``` + +--- + +## Best Practices + +### 1. Use Surface Elevation for Depth + +❌ **Don't use shadows for elevation** +```tsx +
Card
+``` + +✅ **Do use surface tones** +```tsx +
Card
+``` + +### 2. Use Container Variants for Lower Emphasis + +❌ **Don't reduce opacity** +```tsx + +``` + +✅ **Do use container variants** +```tsx + +``` + +### 3. Consistent Status Colors + +❌ **Don't use arbitrary colors** +```tsx +Complete +Finished +``` + +✅ **Do use semantic status colors** +```tsx +Complete +Finished +``` + +### 4. Semantic Color Usage + +❌ **Don't use colors for decoration only** +```tsx +
This is important information
+``` + +✅ **Do use colors for their semantic meaning** +```tsx +
+ Error: Failed to save changes +
+ +
+ This is important information +
+``` + +### 5. Proper Text Contrast + +❌ **Don't forget foreground colors** +```tsx + +``` + +✅ **Do include foreground colors** +```tsx + +``` + +### 6. Layering and Nesting + +When nesting containers, move down the elevation scale: + +```tsx +
+ {/* Outer container */} + +
+ {/* Inner container - lower elevation */} + +
+ {/* Deepest container - lowest elevation */} +
+
+
+``` + +### 7. Interactive States + +```tsx +// Buttons with hover states + + +// Cards with hover states +
+ Interactive card +
+ +// Focus states (automatically handled by theme) + +``` + +--- + +## 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** diff --git a/docs/plans/docs-restructure-ai-lookup.md b/docs/plans/docs-restructure-ai-lookup.md index 7e54ca8..89751c6 100644 --- a/docs/plans/docs-restructure-ai-lookup.md +++ b/docs/plans/docs-restructure-ai-lookup.md @@ -66,7 +66,7 @@ Bij elke turn die met `CLAUDE.md` start, wordt minimaal 340 regels orientation i | `product-backlog.md` | 454 | `docs/backlog/product-historical.md` (referentie, zie noot in CLAUDE.md) | | `personas.md` | 138 | `docs/specs/personas.md` | | `styling.md` | 670 | `docs/design/styling.md` | -| `md3-color-scheme.md` | 941 | `docs/design/md3-color-scheme.md` (overlapt deels met `styling.md` — kandidaat voor merge) | +| `md3-color-scheme.md` | 941 | `docs/design/styling.md` (overlapt deels met `styling.md` — kandidaat voor merge) | | `test-plan.md` | 454 | `docs/qa/api-test-plan.md` | | `pbi-dialog.md` | 120 | `docs/specs/dialogs/pbi.md` | | `story-dialog.md` | 163 | `docs/specs/dialogs/story.md` | diff --git a/docs/plans/docs-restructure-pbi-spec.md b/docs/plans/docs-restructure-pbi-spec.md index d6d2869..539e48a 100644 --- a/docs/plans/docs-restructure-pbi-spec.md +++ b/docs/plans/docs-restructure-pbi-spec.md @@ -287,7 +287,7 @@ pbi: description: "Two files use non-kebab capitalization." implementation_plan: | git mv docs/api/rest-contract.md docs/api/rest-contract.md - git mv docs/design/md3-color-scheme.md docs/design/md3-color-scheme.md + git mv docs/design/styling.md docs/design/styling.md grep -rln "API\.md\|MD3_Color_Scheme" docs/ CLAUDE.md AGENTS.md README.md \ | xargs sed -i '' 's|API\.md|api.md|g; s|md3-color-scheme|md3-color-scheme|g' npm run docs:index @@ -372,7 +372,7 @@ pbi: description: "Bulk move per topic." implementation_plan: | git mv docs/design/styling.md docs/design/styling.md - git mv docs/design/md3-color-scheme.md docs/design/md3-color-scheme.md + git mv docs/design/styling.md docs/design/styling.md git mv docs/api/rest-contract.md docs/api/rest-contract.md git mv docs/qa/api-test-plan.md docs/qa/api-test-plan.md git mv docs/backlog/index.md docs/backlog/index.md @@ -441,7 +441,7 @@ pbi: implementation_plan: | Append md3-color-scheme.md content as H2 sections inside docs/design/styling.md. Drop redundant intro paragraphs. - git rm docs/design/md3-color-scheme.md + git rm docs/design/styling.md grep -rln "md3-color-scheme" docs/ CLAUDE.md AGENTS.md README.md \ | xargs sed -i '' 's|docs/design/md3-color-scheme\.md|docs/design/styling.md|g' commit: docs(split): merge md3-color-scheme into design/styling