whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/templates/audit-report.template.md

@@ -0,0 +1,430 @@
+# Specification Audit Report
+
+**Date:** {YYYY-MM-DD}  
+**Auditor:** {Name/Agent}  
+**Scope:** {Scenario name or Page name}  
+**Audit Level:** {Quick/Standard/Complete}  
+**Project:** {Project name}
+
+---
+
+## Executive Summary
+
+**Overall Status:** {✅ Pass / ⚠️ Pass with Issues / ❌ Fail}
+
+**Issue Counts:**
+- 🔴 Critical Issues: {count}
+- 🟡 Warnings: {count}
+- 🔵 Suggestions: {count}
+
+**Recommendation:** {Ready for development / Needs fixes before development / Major rework required}
+
+---
+
+## Level 0: Specification Formatting & Standards
+
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+### Markdown Structure
+**Checklist:**
+- [ ] Proper heading hierarchy (H1 → H2 → H3 → H4)
+- [ ] Only one H1 per page
+- [ ] No skipped heading levels
+
+**Issues Found:**
+- {Issue description, line number, and severity}
+
+---
+
+### Area Label Format
+**Checklist:**
+- [ ] Format: `**AREA LABEL**: `{label}``
+- [ ] Naming convention: `{page}-{section}-{element}`
+- [ ] Consistent throughout
+
+**Issues Found:**
+- {Issue description, line number, and severity}
+
+---
+
+### Translation Format
+**Checklist:**
+- [ ] Each language on separate line
+- [ ] Format: `- {LANG}: "{content}"`
+- [ ] All product languages present
+- [ ] Consistent language order
+- [ ] No inline translations
+
+**Issues Found:**
+- {Issue description, line number, and severity}
+
+---
+
+### List & Code Formatting
+**Checklist:**
+- [ ] Use `-` for bullets (not `*` or `+`)
+- [ ] Consistent indentation
+- [ ] Code blocks have language specified
+- [ ] Proper spacing
+
+**Issues Found:**
+- {Issue description, line number, and severity}
+
+---
+
+### Section Organization
+**Checklist:**
+- [ ] Sections in standard order
+- [ ] No missing required sections
+- [ ] Logical flow maintained
+
+**Issues Found:**
+- {Issue description, line number, and severity}
+
+---
+
+### File Naming
+**Checklist:**
+- [ ] Follows WDS naming conventions
+- [ ] No generic names (README.md, GUIDE.md)
+- [ ] Descriptive and specific
+
+**Issues Found:**
+- {Issue description and severity}
+
+---
+
+## Level 1: Scenario-Level Findings
+
+### Strategic Foundation
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] User situation clearly defined
+- [ ] Usage context documented
+- [ ] Trigger Value Chain (VTC) defined and linked
+- [ ] Scenario purpose stated
+- [ ] Success criteria defined
+
+**Issues Found:**
+- {Issue description and severity}
+
+---
+
+### Navigation Flow
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] All pages in scenario identified
+- [ ] Entry points documented for each page
+- [ ] Exit points documented for each page
+- [ ] User can navigate through all pages
+- [ ] Navigation paths logical and complete
+
+**Issues Found:**
+- {Issue description and severity}
+
+---
+
+## Level 2: Page-Level Findings
+
+### Structure & Organization
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] Page purpose clearly stated
+- [ ] Success criteria defined
+- [ ] VTC reference present
+- [ ] Sections properly separated and named
+- [ ] Section purposes defined
+- [ ] Page layout logical and flows well
+
+**Structural Area Labels:**
+- [ ] Page container (`{page-name}-page`)
+- [ ] Header section (`{page-name}-header`)
+- [ ] Main content area (`{page-name}-main`)
+- [ ] Form container (`{page-name}-form`)
+- [ ] Section containers (`{page-name}-{section}-section`)
+- [ ] Section header bars (`{page-name}-{section}-header-bar`)
+
+**Issues Found:**
+- {Issue description and severity}
+
+---
+
+### Visual-Spec Alignment
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] Sketch/visualization exists
+- [ ] Sketch linked in specification
+- [ ] All objects in sketch documented in spec
+- [ ] All objects in spec visible in sketch
+- [ ] Visual hierarchy matches spec structure
+
+**Misalignments Found:**
+- **Objects in sketch but missing from spec:**
+  - {Object name and location}
+- **Objects in spec but missing from sketch:**
+  - {Object name and location}
+- **Visual discrepancies:**
+  - {Description of mismatch}
+
+---
+
+### Area Label Coverage
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] All interactive elements have Area Labels
+- [ ] Labels follow naming convention (`{page}-{section}-{element}`)
+- [ ] Labels are unique within page
+- [ ] ARIA labels match Area Labels
+
+**Missing Area Labels:**
+- {Element description and suggested label}
+
+**Naming Convention Issues:**
+- {ID that doesn't follow pattern and suggested fix}
+
+---
+
+## Level 3: Component-Level Findings
+
+### Componentization
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] Reusable sections identified
+- [ ] Components properly separated from page specs
+- [ ] Component specifications exist
+- [ ] Component references valid and linked
+
+**Issues Found:**
+- **Components needing extraction:**
+  - {Component name and pages where it appears}
+- **Missing component specs:**
+  - {Component name}
+- **Broken component references:**
+  - {Reference location and issue}
+
+---
+
+### Design System Integration
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail / N/A}
+
+**Checklist:**
+- [ ] All components added to design system
+- [ ] Components at proper hierarchy level
+- [ ] Design tokens applied
+- [ ] Figma components linked
+
+**Issues Found:**
+- {Issue description and severity}
+
+---
+
+## Level 4: Feature-Level Findings
+
+### Shared Functionality
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] Common features identified
+- [ ] Feature files created and documented
+- [ ] Feature references consistent across pages
+- [ ] Validation rules centralized
+
+**Issues Found:**
+- **Features needing extraction:**
+  - {Feature name and pages where it appears}
+- **Inconsistent implementations:**
+  - {Feature name and inconsistency description}
+
+---
+
+## Level 5: Content Audit Findings
+
+### Text Content
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**Checklist:**
+- [ ] All content defined (no placeholders)
+- [ ] Multi-language content complete
+- [ ] Field labels present and clear
+- [ ] Button text defined
+- [ ] Error messages in all languages
+- [ ] Success messages in all languages
+- [ ] Empty state messages defined
+- [ ] Loading state messages defined
+- [ ] Meta content (page title, meta description) for public pages
+- [ ] Social sharing content (title, description, image) for public pages
+
+**Missing Content:**
+- {Element and missing content type}
+
+**Language Gaps:**
+- {Content that's missing in specific languages}
+
+**Meta Content Issues:**
+- {Missing or incomplete meta tags for public pages}
+
+---
+
+### Accessibility Content
+**Status:** {✅ Pass / ⚠️ Warning / ❌ Fail}
+
+**ARIA Labels:**
+- [ ] All interactive elements have aria-label
+- [ ] ARIA labels descriptive and meaningful
+
+**Missing ARIA Labels:**
+- {Element description}
+
+**Images:**
+- [ ] All images have alt text
+- [ ] Alt text descriptive
+
+**Missing Alt Text:**
+- {Image location and suggested alt text}
+
+**Forms:**
+- [ ] All inputs have labels
+- [ ] Required fields marked
+- [ ] Field instructions present
+
+**Form Issues:**
+- {Issue description}
+
+**Keyboard Navigation:**
+- [ ] Tab order documented
+- [ ] Focus management specified
+- [ ] Skip links present
+
+**Keyboard Issues:**
+- {Issue description}
+
+**Screen Reader Support:**
+- [ ] Semantic HTML specified
+- [ ] Heading hierarchy logical
+- [ ] ARIA live regions for dynamic content
+
+**Screen Reader Issues:**
+- {Issue description}
+
+**Visual Accessibility:**
+- [ ] Color contrast meets WCAG AA
+- [ ] Information not color-dependent
+- [ ] Focus indicators visible
+
+**Visual Accessibility Issues:**
+- {Issue description}
+
+**WCAG Compliance:**
+- [ ] Target level documented
+- [ ] Known issues documented
+
+**WCAG Issues:**
+- {Issue description}
+
+---
+
+## Summary of Issues
+
+### 🔴 Critical Issues (Must Fix Before Development)
+
+1. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this is critical}
+   - **Recommended Fix:** {Specific action to take}
+
+2. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this is critical}
+   - **Recommended Fix:** {Specific action to take}
+
+---
+
+### 🟡 Warnings (Should Fix)
+
+1. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this matters}
+   - **Recommended Fix:** {Specific action to take}
+
+2. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this matters}
+   - **Recommended Fix:** {Specific action to take}
+
+---
+
+### 🔵 Suggestions (Nice to Have)
+
+1. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this would improve quality}
+   - **Recommended Fix:** {Specific action to take}
+
+2. **{Issue Title}**
+   - **Location:** {Page/Section}
+   - **Problem:** {Description}
+   - **Impact:** {Why this would improve quality}
+   - **Recommended Fix:** {Specific action to take}
+
+---
+
+## Recommendations
+
+### Immediate Actions
+1. {Action item with priority and owner}
+2. {Action item with priority and owner}
+
+### Before Development Handoff
+1. {Action item with priority and owner}
+2. {Action item with priority and owner}
+
+### Future Improvements
+1. {Action item with priority and owner}
+2. {Action item with priority and owner}
+
+---
+
+## Next Steps
+
+- [ ] Fix critical issues
+- [ ] Address warnings
+- [ ] Consider suggestions
+- [ ] Re-audit after fixes
+- [ ] Update specifications
+- [ ] Update sketches if needed
+- [ ] Notify development team when ready
+
+---
+
+## Audit Metrics
+
+**Specification Completeness:** {percentage}%
+- Structural Area Labels: {X/Y complete}
+- Interactive Area Labels: {X/Y complete}
+- Content defined: {X/Y complete}
+- Accessibility: {X/Y complete}
+
+**Quality Score:** {percentage}%
+- Based on critical issues, warnings, and suggestions
+
+**Development Readiness:** {Ready / Not Ready / Needs Review}
+
+---
+
+**Audit Completed:** {YYYY-MM-DD HH:MM}  
+**Next Audit Scheduled:** {YYYY-MM-DD or "After fixes"}
+
+---
+
+_Generated using WDS Specification Audit Workflow_

package/src/workflows/4-ux-design/templates/instructions/accessibility-audit.workflow.md

@@ -0,0 +1,166 @@
+# Accessibility Audit Workflow
+
+**Purpose:** Agent-led accessibility review with explanations and suggestions
+
+---
+
+## How This Works
+
+1. Agent reads the page specification and/or prototype code
+2. Agent evaluates each area against WCAG 2.1 AA
+3. Agent explains findings in plain language
+4. Agent proposes specific fixes
+5. User approves, rejects, or asks for alternatives
+
+---
+
+## Agent Instructions
+
+### Step 1: Analyze Color Contrast
+
+Read the design system colors and check:
+
+```
+For each text element:
+- Calculate contrast ratio against background
+- WCAG AA requires: 4.5:1 for normal text, 3:1 for large text (18px+)
+
+Report:
+"The button text (#FFFFFF) on primary background (#2563EB)
+has a contrast ratio of 8.6:1 ✓ Passes WCAG AA
+
+The helper text (#9CA3AF) on white (#FFFFFF)
+has a contrast ratio of 2.9:1 ✗ Fails WCAG AA
+→ Suggestion: Darken to #6B7280 (4.6:1) or #4B5563 (7:1)"
+```
+
+**Ask user:** "Should I darken the helper text to #6B7280?"
+
+---
+
+### Step 2: Analyze Keyboard Navigation
+
+Read the page structure and determine logical tab order:
+
+```
+Looking at the page layout, the logical keyboard flow should be:
+
+1. Skip to main content link (hidden until focused)
+2. Logo (if clickable) → Home
+3. Navigation items left to right
+4. Main content, top to bottom
+5. Form fields in visual order
+6. Submit/action buttons
+7. Footer links
+
+Current spec has these interactive elements:
+- `header-logo` ✓ Has behavior defined
+- `nav-home` ✓ Link
+- `form-email` ✗ Missing keyboard info
+- `submit-btn` ✗ Missing focus state
+
+→ Suggestion: Add to form-email:
+  | Keyboard | Tab to focus, type to enter |
+  | Focus | 2px blue ring (#2563EB) |
+```
+
+**Ask user:** "Should I add keyboard properties to these elements?"
+
+---
+
+### Step 3: Analyze Screen Reader Experience
+
+Check each element has appropriate labels:
+
+```
+Reviewing interactive elements:
+
+`booking-submit` - Button with text "Book"
+→ Issue: "Book" alone may be unclear out of context
+→ Suggestion: aria-label="Book this walk slot"
+
+`booking-cancel` - Icon button with X
+→ Issue: No text, screen reader says nothing
+→ Suggestion: aria-label="Cancel booking"
+
+`status-indicator` - Colored dot (green/red/gray)
+→ Issue: Color only, no text alternative
+→ Suggestion: Add aria-label="Status: Available" and visually hidden text
+```
+
+**Ask user:** "Should I add these aria-labels to the spec?"
+
+---
+
+### Step 4: Analyze Dynamic Content
+
+Check state changes and notifications:
+
+```
+This page has dynamic content:
+
+State changes (drawer opens/closes):
+→ Need: aria-expanded on trigger, focus management
+→ Suggestion: When drawer opens, move focus to drawer header
+
+Loading states:
+→ Need: aria-busy="true" on container, "Loading..." announcement
+→ Suggestion: Add aria-live="polite" region for status updates
+
+Error messages:
+→ Need: aria-live="assertive" so errors are announced immediately
+→ Suggestion: Link error to field with aria-describedby
+```
+
+**Ask user:** "Should I add these dynamic content specifications?"
+
+---
+
+### Step 5: Summary Report
+
+```
+## Accessibility Audit Summary
+
+### Passes ✓
+- Color contrast on primary buttons (8.6:1)
+- Semantic HTML structure (header, main, nav)
+- Form labels present
+
+### Needs Attention ⚠
+- Helper text contrast (2.9:1 → needs 4.5:1)
+- 3 buttons missing aria-labels
+- Tab order not documented
+- Focus states not specified
+
+### Recommendations
+1. Darken helper text to #6B7280
+2. Add aria-labels to icon buttons
+3. Document keyboard flow
+4. Specify focus ring style (2px #2563EB)
+
+Implement these changes? [Yes to all / Review each / Skip]
+```
+
+---
+
+## Quick Reference for Agent
+
+| Check | WCAG Rule | Requirement |
+|-------|-----------|-------------|
+| Text contrast | 1.4.3 | 4.5:1 normal, 3:1 large |
+| Focus visible | 2.4.7 | Clear visual indicator |
+| Labels | 1.3.1 | All inputs labeled |
+| Keyboard | 2.1.1 | All functions keyboard accessible |
+| Error ID | 3.3.1 | Errors identified and described |
+| Name/Role | 4.1.2 | Interactive elements have accessible names |
+
+---
+
+## Agent Prompts
+
+Use these to guide the conversation:
+
+- "I found {N} contrast issues. Want me to explain each one?"
+- "This button has no accessible name. Should I suggest one based on its purpose?"
+- "The tab order seems unclear. Can you confirm the intended flow?"
+- "Screen readers won't announce this status change. Should I add aria-live?"

package/src/workflows/4-ux-design/templates/instructions/accessibility.instructions.md

@@ -0,0 +1,102 @@
+# Accessibility Specification
+
+**Include when:** Specifying interactive elements, forms, or navigation
+
+---
+
+## For Each Interactive Element
+
+When documenting buttons, links, inputs, add:
+
+```markdown
+| Property | Value |
+|----------|-------|
+| aria-label | "{What it does}" |
+| Keyboard | {Enter / Space / Arrow keys} |
+| Focus style | {ring / outline / highlight} |
+```
+
+**Example:**
+```markdown
+#### Submit Button
+**OBJECT ID:** `form-submit`
+
+| Property | Value |
+|----------|-------|
+| aria-label | "Submit booking request" |
+| Keyboard | Enter or Space |
+| Focus | 2px blue ring |
+| Disabled state | aria-disabled="true", gray, no focus |
+```
+
+---
+
+## Tab Order
+
+Document the logical sequence:
+
+```markdown
+## Keyboard Flow
+
+1. `header-logo` → Home link
+2. `header-nav` → Main navigation
+3. `main-content` → Skip to here
+4. `form-name` → First input
+5. `form-email` → Second input
+6. `form-submit` → Submit button
+```
+
+---
+
+## Dynamic Content
+
+When content changes without page reload:
+
+```markdown
+| Element | Announces |
+|---------|-----------|
+| `toast-success` | aria-live="polite" — "Booking confirmed" |
+| `error-message` | aria-live="assertive" — Error text |
+| `loading-spinner` | aria-busy="true" on parent |
+```
+
+---
+
+## Color Independence
+
+For status indicators, ensure alternatives:
+
+| Status | Color | Also Has |
+|--------|-------|----------|
+| Success | Green | Checkmark icon + "Complete" text |
+| Error | Red | Warning icon + error message |
+| Active | Blue | Bold text + underline |
+
+---
+
+## Form Errors
+
+Link errors to fields:
+
+```markdown
+#### Email Error
+**OBJECT ID:** `form-email-error`
+
+| Property | Value |
+|----------|-------|
+| aria-describedby | Links to `form-email` |
+| Role | "alert" |
+| Content | "Please enter a valid email" |
+```
+
+---
+
+## Quick Checks
+
+Before finalizing:
+
+- [ ] Every button has aria-label or visible text
+- [ ] Every image has alt (or alt="" if decorative)
+- [ ] Every input has associated label
+- [ ] Focus visible on all interactive elements
+- [ ] Status not conveyed by color alone