whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/specification-audit-workflow.md

@@ -0,0 +1,697 @@
+# Specification Audit Workflow
+
+**Phase:** 4 - UX Design  
+**Agent:** Freya (WDS Designer)  
+**Purpose:** Systematically validate page and scenario specifications for completeness, consistency, and quality
+
+---
+
+## When to Use This Workflow
+
+**Triggers:**
+- Before handoff to development (Phase 6)
+- After completing scenario specifications
+- When reviewing existing specifications
+- Quality gate before prototype creation
+- On-demand specification review
+
+---
+
+## Audit Levels
+
+### Quick Audit (15-30 minutes)
+Essential checks only - use for rapid validation during active design work.
+
+### Standard Audit (1-2 hours)
+Comprehensive review - use before development handoff.
+
+### Complete Audit (2-4 hours)
+Full validation including visual-spec alignment - use for critical pages or final quality gate.
+
+---
+
+## Audit Structure
+
+The audit follows a hierarchical approach from formatting → scenario → page → component → content.
+
+### Level 0: Specification Formatting & Standards
+**WDS Formatting Compliance**
+
+### Level 1: Scenario-Level Audit
+**Strategic Foundation**
+
+### Level 2: Page-Level Audit
+**Structure & Organization**
+
+### Level 3: Component-Level Audit
+**Componentization & Design System**
+
+### Level 4: Feature-Level Audit
+**Shared Functionality**
+
+### Level 5: Content Audit
+**Text & Accessibility Content**
+
+---
+
+## Level 0: Specification Formatting & Standards
+
+**Purpose:** Validate specification follows WDS formatting conventions and standards
+
+### Checklist
+
+**Markdown Structure:**
+- [ ] Proper heading hierarchy (H1 → H2 → H3 → H4, no skipped levels)
+- [ ] Only one H1 per page (page title)
+- [ ] H2 for major sections
+- [ ] H3 for subsections
+- [ ] H4 for component details
+
+**Area Label Format:**
+- [ ] Format: `**AREA LABEL**: `{label}`` (bold, all caps, backticks)
+- [ ] Naming convention: `{page}-{section}-{element}` (lowercase, hyphens)
+- [ ] Consistent throughout specification
+
+**Translation Format:**
+- [ ] Each language on separate line
+- [ ] Format: `- {LANG}: "{content}"`
+- [ ] All product languages present for each content item
+- [ ] Consistent language order throughout spec
+- [ ] No inline translations (e.g., "Text (EN), Text (SE)")
+
+**List Formatting:**
+- [ ] Use `-` for unordered lists (not `*` or `+`)
+- [ ] Consistent indentation (2 spaces per level)
+- [ ] Proper spacing (blank line before/after lists)
+- [ ] No unnecessary blank lines between items
+
+**Code Blocks:**
+- [ ] Language specified for syntax highlighting
+- [ ] Triple backticks used
+- [ ] Proper indentation
+
+**Section Organization:**
+- [ ] Sections in standard order (per template)
+- [ ] No missing required sections
+- [ ] No duplicate sections
+- [ ] Logical flow maintained
+- [ ] **Open Questions section present** (even if empty)
+
+**Spacing & Formatting:**
+- [ ] Consistent spacing between sections
+- [ ] Proper use of bold for field labels
+- [ ] No excessive blank lines
+- [ ] Consistent indentation throughout
+
+**Links:**
+- [ ] Descriptive link text (not "here" or "click here")
+- [ ] Valid relative paths for internal links
+- [ ] Proper markdown format: `[Text](path)`
+
+**File Naming:**
+- [ ] Follows WDS naming conventions
+- [ ] No generic names (README.md, GUIDE.md)
+- [ ] Descriptive and specific
+
+### Common Formatting Violations
+
+**Inline Translations:**
+```markdown
+❌ **Content:** "Sign In" (EN), "Logga In" (SE)
+
+✅ **Content:**
+   - EN: "Sign In"
+   - SE: "Logga In"
+```
+
+**Inconsistent Area Label Format:**
+```markdown
+❌ Area Label: signin-form-email
+❌ **area-label**: `signin-form-email`
+
+✅ **AREA LABEL**: `signin-form-email`
+```
+
+**Skipped Heading Levels:**
+```markdown
+❌ # Page Title
+   #### Component
+
+✅ # Page Title
+   ## Section
+   ### Subsection
+   #### Component
+```
+
+**Missing Translations:**
+```markdown
+❌ **Content:**
+   - EN: "Submit"
+   (Missing SE)
+
+✅ **Content:**
+   - EN: "Submit"
+   - SE: "Skicka"
+```
+
+### Navigation Best Practice
+
+**Navigation Placement (Required for Long Specs):**
+Long specifications must have navigation links in THREE locations so users can navigate without scrolling:
+```markdown
+✅ Above the sketch:
+**Previous Step:** ← [3.1 Page Name](path)
+**Next Step:** → [3.3 Page Name](path)
+
+![Page Sketch](Sketches/page-sketch.jpg)
+
+✅ Below the sketch (still in header area):
+**Previous Step:** ← [3.1 Page Name](path)
+**Next Step:** → [3.3 Page Name](path)
+
+... specification content ...
+
+✅ Bottom of document:
+**Previous Step:** ← [3.1 Page Name](path)
+**Next Step:** → [3.3 Page Name](path)
+```
+This is especially important for storyboards and multi-state specifications where sketches and content can be very long.
+
+### Output
+- List of formatting violations by type
+- Specific line numbers or sections with issues
+- Recommendations for corrections
+- Severity (Critical/Warning/Suggestion)
+
+**Reference:** `../../workflows/00-system/SPECIFICATION-FORMATTING-STANDARDS.md`
+
+---
+
+## Level 1: Scenario-Level Audit
+
+**Purpose:** Validate strategic foundation and navigation flow
+
+### Checklist
+
+**Strategic Foundation**
+- [ ] User situation clearly defined
+- [ ] Usage context documented
+- [ ] Trigger Value Chain (VTC) defined and linked
+- [ ] Scenario purpose stated
+- [ ] Success criteria defined
+
+**Navigation Flow**
+- [ ] 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
+- [ ] Dead ends identified and resolved
+
+**Scenario Overview**
+- [ ] Scenario overview file exists
+- [ ] Overview describes user journey
+- [ ] Page sequence makes sense
+- [ ] Links to all page specifications work
+
+### Output
+- List of missing strategic elements
+- Navigation flow gaps
+- Broken links or missing pages
+
+---
+
+## Level 2: Page-Level Audit
+
+**Purpose:** Validate page structure, organization, and visual alignment
+
+### A. Template Check
+
+**Determine which template applies:**
+- [ ] Single sketch → uses page-specification.template.md
+- [ ] Multiple sketches → uses storyboard extension
+- [ ] If storyboard: State Flow Overview present with ASCII diagram
+- [ ] If storyboard: State 1 fully documented as baseline
+- [ ] If storyboard: States 2+ document only changes
+
+### B. Structure & Organization
+
+**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
+- [ ] Layout structure diagram present
+- [ ] Navigation present (Previous/Next links: above sketch, below sketch, and at document bottom)
+
+**Structural Area Labels:**
+- [ ] Page container (`{page-name}-page`)
+- [ ] Header section (`{page-name}-header`)
+- [ ] Main content area (`{page-name}-main`)
+- [ ] Form container if applicable (`{page-name}-form`)
+- [ ] Section containers (`{page-name}-{section}-section`)
+- [ ] Section header bars if visible (`{page-name}-{section}-header-bar`)
+
+### C. Visual-Spec Alignment
+
+**Checklist:**
+- [ ] Sketch/visualization exists in Sketches/ folder
+- [ ] Sketch linked in specification
+- [ ] All objects in sketch documented in spec
+- [ ] All objects in spec visible in sketch
+- [ ] Visual hierarchy matches spec structure
+- [ ] Component placement matches sketch
+
+**Gap Analysis:**
+- Objects in sketch but missing from spec → Add to spec
+- Objects in spec but missing from sketch → Update sketch or remove from spec
+- Visual elements don't match description → Align sketch and spec
+
+### D. Area Label Coverage
+
+**Checklist:**
+- [ ] All interactive elements have Area Labels (OBJECT IDs)
+- [ ] Labels follow naming convention (`{page}-{section}-{element}`)
+- [ ] Labels are unique within page
+- [ ] ARIA labels match Area Labels
+- [ ] Labels support html.to.design layer naming
+
+### Output
+- Structure issues list
+- Visual-spec misalignment report
+- Missing Area Labels list
+- Recommendations for fixes
+
+---
+
+## Level 3: Component-Level Audit
+
+**Purpose:** Validate componentization and design system integration
+
+### A. Componentization
+
+**Checklist:**
+- [ ] Reusable sections identified (header, footer, navigation)
+- [ ] Components properly separated from page specs
+- [ ] Component specifications exist
+- [ ] Component references valid and linked
+- [ ] Shared patterns documented
+
+**Common Reusable Components:**
+- Navigation header
+- Footer
+- Form fields (inputs, selects, textareas)
+- Buttons (primary, secondary, tertiary)
+- Cards
+- Modals/dialogs
+- Error messages
+- Loading indicators
+
+### B. Design System Integration (if enabled)
+
+**Checklist:**
+- [ ] All components added to design system
+- [ ] Components at proper hierarchy level:
+  - Atomic: Buttons, inputs, icons, labels
+  - Molecular: Form fields, cards, list items
+  - Organism: Headers, forms, sections
+- [ ] Design tokens applied (colors, spacing, typography)
+- [ ] Figma components linked
+- [ ] Component variants documented
+
+### Output
+- List of components needing extraction
+- Design system gaps
+- Component hierarchy recommendations
+
+---
+
+## Level 4: Feature-Level Audit
+
+**Purpose:** Validate shared functionality is properly extracted
+
+### Checklist
+
+**Shared Features:**
+- [ ] Common features identified (e.g., image upload, validation)
+- [ ] Feature files created and documented
+- [ ] Feature references consistent across pages
+- [ ] Validation rules centralized
+- [ ] Error handling standardized
+
+**Common Shared Features:**
+- Image upload/cropping
+- Form validation
+- Authentication flows
+- Payment processing
+- Search functionality
+- Filtering/sorting
+- Pagination
+- Date/time selection
+
+### Output
+- List of features needing extraction
+- Feature documentation gaps
+- Inconsistencies across pages
+
+---
+
+## Level 5: Content Audit
+
+**Purpose:** Validate all content is defined and accessible
+
+### A. Text Content
+
+**Checklist:**
+- [ ] **All Text Defined** - No placeholder content?
+- [ ] **Error Messages** - All error states have messages in all languages?
+- [ ] **Success Messages** - Confirmation messages defined?
+- [ ] **Empty States** - Messages for no-data scenarios?
+- [ ] **Loading States** - Loading indicators and messages?
+- [ ] **Meta Content** - Page title and meta description for public pages?
+- [ ] **Social Sharing** - Social media title, description, and image for public pages?
+- [ ] Field labels present and clear
+- [ ] Button text defined and action-oriented
+- [ ] Help text/tooltips documented
+
+### B. Accessibility Content
+
+**Checklist:**
+
+**ARIA Labels:**
+- [ ] All interactive elements have aria-label attributes
+- [ ] ARIA labels descriptive and meaningful
+- [ ] ARIA labels match Area Labels
+
+**Images:**
+- [ ] All images have alt text specified
+- [ ] Alt text descriptive (not just filename)
+- [ ] Decorative images marked as such (alt="")
+
+**Forms:**
+- [ ] All inputs have associated labels (visible or aria-label)
+- [ ] Required fields marked with aria-required
+- [ ] Field instructions associated with aria-describedby
+- [ ] Error messages announced to screen readers
+
+**Keyboard Navigation:**
+- [ ] Tab order documented
+- [ ] Focus management specified
+- [ ] Keyboard shortcuts documented (if any)
+- [ ] Skip links present
+
+**Screen Reader Support:**
+- [ ] Semantic HTML specified (header, main, nav, section)
+- [ ] Heading hierarchy logical (H1 → H2 → H3)
+- [ ] ARIA live regions for dynamic content
+- [ ] Loading states announced
+
+**Visual Accessibility:**
+- [ ] Color contrast meets WCAG AA (4.5:1 for text)
+- [ ] Information not conveyed by color alone
+- [ ] Focus indicators visible (3:1 contrast)
+- [ ] Text readable at 200% zoom
+
+**WCAG Compliance:**
+- [ ] Target compliance level documented (AA/AAA)
+- [ ] Known accessibility issues documented
+- [ ] Testing approach specified
+
+### Output
+- Missing content list
+- Accessibility gaps
+- WCAG compliance issues
+- Recommendations for fixes
+
+---
+
+## Audit Report Template
+
+```markdown
+# Specification Audit Report
+
+**Date:** {YYYY-MM-DD}
+**Auditor:** {Name}
+**Scope:** {Scenario/Page name}
+**Audit Level:** {Quick/Standard/Complete}
+
+---
+
+## Executive Summary
+
+**Overall Status:** {Pass/Pass with Issues/Fail}
+
+**Critical Issues:** {count}
+**Warnings:** {count}
+**Suggestions:** {count}
+
+---
+
+## Level 1: Scenario-Level Findings
+
+### Strategic Foundation
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+### Navigation Flow
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+---
+
+## Level 2: Page-Level Findings
+
+### Structure & Organization
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+### Visual-Spec Alignment
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Misalignments: {list}
+
+### Area Label Coverage
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Missing Labels: {list}
+
+---
+
+## Level 3: Component-Level Findings
+
+### Componentization
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+### Design System Integration
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+---
+
+## Level 4: Feature-Level Findings
+
+### Shared Functionality
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Issues: {list}
+
+---
+
+## Level 5: Content Audit Findings
+
+### Text Content
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Missing content: {list}
+
+### Accessibility Content
+- ✅ Pass / ⚠️ Warning / ❌ Fail
+- Accessibility gaps: {list}
+
+---
+
+## Recommendations
+
+### Critical (Must Fix Before Development)
+1. {Issue and recommended fix}
+2. {Issue and recommended fix}
+
+### Warnings (Should Fix)
+1. {Issue and recommended fix}
+2. {Issue and recommended fix}
+
+### Suggestions (Nice to Have)
+1. {Issue and recommended fix}
+2. {Issue and recommended fix}
+
+---
+
+## Next Steps
+
+- [ ] {Action item}
+- [ ] {Action item}
+- [ ] Re-audit after fixes
+
+---
+
+**Audit Complete:** {YYYY-MM-DD}
+```
+
+---
+
+## Quick Audit Checklist
+
+For rapid validation during active design work:
+
+**Formatting (Level 0):**
+- [ ] Proper heading hierarchy
+- [ ] Area Label format correct
+- [ ] Translations on separate lines
+- [ ] All product languages present
+
+**Content (Levels 1-5):**
+- [ ] Page purpose clear
+- [ ] VTC reference present
+- [ ] Structural Area Labels complete
+- [ ] Interactive Area Labels complete
+- [ ] Multi-language content present
+- [ ] ARIA labels on interactive elements
+- [ ] Alt text on images
+- [ ] Form labels present
+- [ ] Error messages defined
+- [ ] Sketch exists and linked
+- [ ] **Open Questions section present** (populate using open-questions.instructions.md)
+
+---
+
+## Standard Audit Checklist
+
+For comprehensive review before development handoff:
+
+**All Quick Audit items, plus:**
+
+**Formatting (Level 0):**
+- [ ] Section organization follows template
+- [ ] Consistent spacing and indentation
+- [ ] Code blocks have language specified
+- [ ] Links properly formatted
+- [ ] No formatting violations
+
+**Content (Levels 1-5):**
+- [ ] Scenario navigation complete
+- [ ] Section purposes defined
+- [ ] Visual-spec alignment verified
+- [ ] Components properly extracted
+- [ ] Design system integration complete
+- [ ] Shared features documented
+- [ ] All content defined (no placeholders)
+- [ ] Open Questions section reviewed (all resolved or acceptable for dev handoff)
+- [ ] Accessibility requirements complete
+- [ ] WCAG compliance documented
+- [ ] API endpoints defined
+- [ ] Validation rules specified
+
+---
+
+## Complete Audit Checklist
+
+For full validation including visual verification:
+
+**All Standard Audit items, plus:**
+
+- [ ] Sketch matches spec exactly
+- [ ] All sketch objects documented
+- [ ] All spec objects in sketch
+- [ ] Component hierarchy optimal
+- [ ] Feature extraction complete
+- [ ] Keyboard navigation tested
+- [ ] Screen reader compatibility verified
+- [ ] Color contrast checked
+- [ ] Focus management validated
+- [ ] Responsive behavior specified
+
+---
+
+## Integration with WDS
+
+**Workflow Placement:**
+- Phase 4 (UX Design) - Before prototype creation
+- Phase 6 (Design Deliveries) - Before development handoff
+- Phase 8 (Ongoing Development) - When updating specifications
+
+**Agent Integration:**
+- Freya runs audits on page specifications
+- Idunn can request audits before development
+- Saga can audit for strategic alignment
+
+**Menu Trigger:**
+Add to Freya's menu:
+```yaml
+- trigger: audit-spec
+  exec: "{project-root}/{bmad_folder}/wds/workflows/4-ux-design/specification-audit-workflow.md"
+  description: "[AS] Audit page or scenario specifications for completeness and quality"
+```
+
+---
+
+## Related Resources
+
+### Templates
+- **Page Specification:** `./templates/page-specification.template.md`
+- **Storyboard Extension:** `./templates/storyboard-specification.template.md` (for multi-sketch pages)
+
+### Micro-Instructions (conditional sections)
+- **Open Questions (always):** `./templates/instructions/open-questions.instructions.md` ← Auto-populate questions
+- **SEO/Social:** `./templates/instructions/meta-content.instructions.md`
+- **Forms:** `./templates/instructions/form-validation.instructions.md`
+- **API Data:** `./templates/instructions/data-api.instructions.md`
+- **Responsive:** `./templates/instructions/responsive.instructions.md`
+- **Accessibility:** `./templates/instructions/accessibility.instructions.md`
+- **Accessibility Audit:** `./templates/instructions/accessibility-audit.workflow.md`
+
+### Guides
+- **Specification Quality Guide:** `../../data/agent-guides/freya/specification-quality.md`
+- **Accessibility Guidelines:** WCAG 2.1 Level AA
+
+---
+
+## Template Router
+
+**Before auditing, determine which template applies:**
+
+| Condition | Template |
+|-----------|----------|
+| Single sketch | page-specification.template.md |
+| Multiple sketches (states, flows) | page-specification + storyboard extension |
+
+**Check for required micro-instructions:**
+
+| Page Has | Include |
+|----------|---------|
+| **All pages** | **open-questions.instructions.md** (auto-populate questions) |
+| Public visibility | meta-content.instructions.md |
+| Forms/inputs | form-validation.instructions.md |
+| API data | data-api.instructions.md |
+| Multiple breakpoints | responsive.instructions.md |
+
+---
+
+## Object Hierarchy Check
+
+Verify specs follow the hierarchy:
+
+```
+Page
+└── Section (OBJECT ID: page-section)
+    ├── Object (OBJECT ID: page-object)
+    └── Group/Container (OBJECT ID: page-group)
+        └── Nested Object (OBJECT ID: page-group-object)
+```
+
+**Storyboard pages also need:**
+- State Flow Overview (ASCII diagram + state table)
+- State 1 fully documented (baseline)
+- States 2+ document only changes (reuse OBJECT IDs)
+
+---
+
+**Use this workflow to ensure specifications are complete, consistent, and ready for confident implementation.**