whiteport-design-studio 0.1.0

package/src/workflows/4-ux-design/page-specification-quality/quality-guide.md

@@ -0,0 +1,653 @@
+# Page Specification Quality Guide
+
+**Purpose:** Reference guide explaining what the Page Specification Quality Workflow checks and why each validation matters.
+
+**Note:** This is a reference document. To execute the workflow, see `workflow.md`.
+
+---
+
+## Overview
+
+The Page Specification Quality Workflow ensures every WDS page specification meets quality standards with complete structure, Object IDs, and traceability. This guide explains each validation check and its importance.
+
+---
+
+## When to Use Quality Workflow
+
+### During Page Creation ✨
+Build specifications correctly from the start:
+- Creating a new page specification from a sketch
+- Converting rough notes into proper spec format
+- Building specs incrementally as design evolves
+
+### After Page Updates 🔄
+Validate changes maintain standards:
+- Updated sketch with new elements
+- Content revisions
+- Added sections or components
+- Design iteration
+
+### Quality Audits 🔍
+Check existing specifications:
+- Pre-handoff quality check
+- Sprint review preparation
+- Onboarding new team members
+- Fixing legacy specs
+
+---
+
+## Workflow Architecture
+
+The workflow uses **BMAD v6 micro-step architecture** with 8 sequential validation steps:
+
+```
+Step 1: Page Metadata
+    ↓
+Step 2: Navigation Structure
+    ↓
+Step 3: Page Overview
+    ↓
+Step 4: Page Sections & Objects
+    ↓
+Step 5: Section Order & Structure
+    ↓
+Step 6: Object Registry
+    ↓
+Step 7: Design System Separation & Unnecessary Information
+    ↓
+Step 8: Final Validation
+```
+
+**Workflow Philosophy:**
+- **Diagnose, don't rewrite** - Identify issues and suggest specific fixes
+- **Report findings** - Generate clear, actionable reports for each section
+- **Recommend solutions** - Provide examples of correct patterns
+- **Let designer decide** - Agent suggests, designer implements (unless asked to fix)
+
+---
+
+## How to Execute Workflow
+
+### For AI Agents (Freya)
+Load and execute: `workflow.md` or `instructions.md`
+
+### For Human Designers
+1. Open your page specification
+2. Follow the 8 steps sequentially
+3. Use the checklists in each step file
+4. Generate quality report at Step 8
+
+---
+
+## What This Workflow Checks
+
+### ✅ Step 1: Page Metadata
+- Platform declaration present
+- Page type specified
+- Primary viewport identified
+- Interaction model documented
+- Navigation context defined
+- Inherits from scenario platform strategy
+
+**Why This Matters:**
+- Establishes technical context before design decisions
+- Ensures platform-appropriate design patterns
+- Clarifies device priorities and constraints
+- Guides responsive design approach
+- Prevents platform-incompatible features
+- 📖 **Reference:** [Page Specification Template](../templates/page-specification.template.md)
+
+**Audit Report Example:**
+```markdown
+🔍 Page Metadata Audit
+
+**Status:** ⚠️ WARNING - Missing platform metadata
+
+**Issues Found:**
+1. ❌ No Page Metadata section (should be after page title)
+   - Missing: Platform, Page Type, Viewport, Interaction Model
+   - Should add: Complete Page Metadata section
+   - Why: Developers need platform context before implementation
+
+2. ℹ️ Platform not inherited from scenario
+   - Check: Does scenario overview define platform strategy?
+   - Action: Confirm platform strategy in scenario, then add to page
+
+**Recommendation:**
+Add Page Metadata section with:
+- Platform (from Product Brief/Scenario)
+- Page Type (Full Page, Modal, etc.)
+- Primary Viewport (Mobile-first, Desktop-first, etc.)
+- Interaction Model (Touch, Mouse/keyboard, etc.)
+- Navigation Context (Public, Authenticated, etc.)
+
+Would you like me to add the Page Metadata section?
+```
+
+### ✅ Step 2: Navigation Structure
+- H3 and H1 headers with page numbers
+- "Next Step" links before and after sketch
+- Embedded sketch image
+- Correct relative paths
+
+**Why This Matters:**
+- Provides immediate context for where page fits in user journey
+- Embedded sketch gives visual reference without leaving document
+- Consistent navigation enables automated tooling and cross-linking
+- 📖 **Reference:** [step-01-navigation.md](step-01-navigation.md)
+
+### ✅ Step 3: Page Overview
+- Page description (1-2 paragraphs)
+- User Situation section
+- Page Purpose section
+- Emotional context and pain points
+
+**Why This Matters:**
+- Captures strategic intent (WHY) before implementation details (HOW)
+- Connects design decisions to user needs and trigger map
+- Provides context for developers and stakeholders
+- 📖 **Reference:** [step-02-page-overview.md](step-02-page-overview.md)
+
+### ✅ Step 4: Page Sections
+- "## Page Sections" header
+- Section Objects (H3) with Purpose
+- Component specs (H4) with Object IDs
+- Design system links
+- Content specifications
+- Behavior specifications
+
+**Why This Matters:**
+- OBJECT IDs enable traceability from spec → code → Figma
+- Component references ensure design system consistency
+- Content with language tags prevents "lorem ipsum" in production
+- Behavior specs reduce developer guesswork
+- 📖 **Reference:** [step-03-page-sections.md](step-03-page-sections.md)
+- 📖 **Related:** [Page Specifications Deliverable](../../../docs/deliverables/page-specifications.md)
+
+### ✅ Step 6: Object Registry
+- "## Object Registry" header
+- Introduction paragraph
+- Master Object List tables
+- 100% coverage of all Object IDs
+- Proper table formatting
+
+**Why This Matters:**
+- Single source of truth for all page elements
+- Enables automated testing (test by OBJECT ID)
+- Facilitates content updates and translations
+- Supports Figma export workflows (aria-label mapping)
+- 📖 **Reference:** [step-04-object-registry.md](step-04-object-registry.md)
+
+### ✅ Step 5: Section Order & Structure
+- Sections appear in standard WDS order
+- Required sections are present
+- Optional sections are appropriately placed
+- No duplicate or redundant sections
+
+**Standard Section Order:**
+1. Navigation (H3 + Next Step + Sketch + Next Step + H1)
+2. Page description paragraph
+3. User Situation
+4. Page Purpose
+5. Reference Materials
+6. Page Sections
+7. Page-Specific Layout Notes (optional)
+8. Object Registry
+
+**Why This Matters:**
+- Consistent structure across all page specifications
+- Strategic context (WHY) before implementation (WHAT)
+- Easy navigation for developers and stakeholders
+- Enables automated tooling and validation
+- 📖 **Reference:** [Page Specification Standards](../../../docs/deliverables/page-specifications.md)
+
+**Audit Report Example:**
+```markdown
+🔍 Section Structure Audit
+
+**Status:** ⚠️ WARNING - Sections out of order
+
+**Issues Found:**
+1. ⚠️ "Reference Materials" appears after "Page Sections" (Line 250)
+   - Should be: Before "Page Sections" (around Line 20)
+   - Why: Strategic context should come before implementation details
+
+2. ⚠️ Missing "Object Registry" section
+   - Should be: At end of document
+   - Why: Required for traceability and automated testing
+
+Would you like me to reorder these sections?
+```
+
+### ✅ Step 7: Design System Separation
+- NO CSS classes, hex codes, or styling values in page specs
+- NO font sizes, padding, margins, or layout measurements
+- Component references link to Design System
+- Color/typography references use Design System tokens
+- Styling details documented in Design System, not page specs
+
+**Why This Matters:**
+- Page specs focus on WHAT/WHY (strategic), not HOW (implementation)
+- Prevents specifications from becoming outdated when styles change
+- Enables design system to be single source of truth for styling
+- Reduces specification maintenance burden
+- Prevents "reverse-engineering from Figma" anti-pattern
+- 📖 **Reference:** [Design System Deliverable](../../../docs/deliverables/design-system.md)
+- 📖 **Related:** [Prepare for Figma Export](../../../docs/tools/prepare-for-figma-export.md)
+
+**Common Violations to Check:**
+- ❌ CSS class names in component descriptions (`.btn-primary`, `.hero-section`)
+- ❌ Color hex codes in content (`#2F1A0C`, `rgb(255, 100, 50)`)
+- ❌ Font sizes and weights (`18px Fredoka SemiBold`, `font-size: 2rem`)
+- ❌ Spacing values (`padding: 20px`, `margin-bottom: 16px`)
+- ❌ Layout measurements (`max-width: 1200px`, `border-radius: 8px`)
+- ✅ Component references (`[Button Primary]`, `H1 heading`)
+- ✅ Design System links (`See [Color Palette]`, `Uses [Typography System]`)
+
+**Audit Report Example:**
+```markdown
+## Design System Separation Audit
+
+**Status:** ❌ FAIL - CSS implementation details found in specification
+
+**Critical Issues:**
+1. ❌ CSS styling in Hero section (Lines 45-78)
+   - Found: Font sizes, colors, padding values
+   - Example: "18px Fredoka SemiBold, #2F1A0C, padding: 20px"
+   - Should be: Component references and Design System links
+   - Action: Move to /docs/D-Design-System/03-Components/
+
+2. ❌ Responsive CSS in component descriptions (Lines 120-145)
+   - Found: Media queries and breakpoint values
+   - Example: "@media (min-width: 768px) { ... }"
+   - Should be: High-level layout notes only
+   - Action: Move to Design System Breakpoints documentation
+
+**Recommendation:**
+- Keep: OBJECT IDs, content, behavior, strategic rationale
+- Remove: All CSS classes, hex codes, measurements, styling
+- Add: Links to Design System components
+- Add: "Page-Specific Layout Notes" section for high-level responsive behavior
+
+**Next Steps:**
+1. Extract styling to Design System documentation
+2. Replace CSS details with component references
+3. Add Design System links for colors/typography
+4. Keep page-specific layout notes (mobile vs desktop behavior)
+
+Would you like me to help extract these styles to the Design System?
+```
+
+### ✅ Step 7 (continued): Unnecessary Information Detection
+- NO implementation code snippets (HTML, CSS, JavaScript)
+- NO developer instructions or technical setup steps
+- NO version control information (commit messages, PR notes)
+- NO internal project management notes
+- NO duplicate content across sections
+- NO outdated/deprecated information
+
+**Why This Matters:**
+- Keeps specifications focused on design intent
+- Prevents confusion between spec and implementation
+- Reduces maintenance burden (less to update)
+- Improves readability for all stakeholders
+- Separates concerns (design specs vs. developer docs)
+
+**Common Unnecessary Content:**
+- ❌ Code examples (`<div class="hero">`, `const handleClick = () => {}`)
+- ❌ Build instructions ("Run npm install", "Deploy to staging")
+- ❌ Git history ("Added in PR #123", "Fixed by John on 2024-01-15")
+- ❌ Internal notes ("TODO: Ask PM about this", "Waiting for approval")
+- ❌ Duplicate sketches or redundant descriptions
+- ❌ Old design iterations that are no longer relevant
+- ✅ OBJECT IDs, content, behavior, strategic rationale
+- ✅ Component references and Design System links
+- ✅ User context and page purpose
+
+**Audit Report Example:**
+```markdown
+🔍 Unnecessary Information Audit
+
+**Status:** ⚠️ WARNING - Non-specification content found
+
+**Issues Found:**
+1. ⚠️ HTML code snippets in component descriptions (Lines 85-92)
+   - Found: `<button class="btn-primary">Click me</button>`
+   - Why problematic: Implementation details, not design intent
+   - Action: Remove code, keep OBJECT ID and behavior description
+
+2. ⚠️ Developer setup instructions (Lines 200-215)
+   - Found: "Run npm install, configure .env file..."
+   - Why problematic: Belongs in developer documentation
+   - Action: Move to /docs/developer-setup.md or remove
+
+3. ⚠️ Duplicate sketch references (Lines 15, 45, 120)
+   - Found: Same sketch linked multiple times
+   - Why problematic: Clutters document, causes confusion
+   - Action: Keep sketch in navigation section only
+
+4. ℹ️ Old design iteration notes (Lines 300-320)
+   - Found: "Previous version used blue, changed to green"
+   - Why problematic: Historical notes not needed in final spec
+   - Action: Remove or move to design decision log
+
+Would you like me to clean up this unnecessary content?
+```
+
+### ✅ Step 8: Final Validation
+- Cross-reference all sections
+- Verify sketch coverage
+- Check for broken links
+- Validate naming conventions
+- Generate quality report
+
+**Why This Matters:**
+- Catches inconsistencies before handoff
+- Ensures specification completeness
+- Provides confidence for developers
+- Documents quality metrics for project tracking
+- 📖 **Reference:** [step-05-final-validation.md](step-05-final-validation.md)
+
+---
+
+## Example: Standard WDS Pattern
+
+This workflow ensures all WDS page specifications follow a consistent, high-quality pattern.
+
+**Key Pattern Elements:**
+- Clear navigation with scenario context
+- Embedded sketch images
+- Section Objects with Purpose statements
+- Component specs with Object IDs
+- Complete Object Registry table
+- Design system component links
+
+---
+
+## Output: Quality Report
+
+At the end of Step 5, you'll have:
+
+**Comprehensive Quality Report** including:
+- Pass/Fail status for each section
+- List of critical issues (must fix) with **specific line numbers**
+- List of warnings (should fix) with **examples of violations**
+- List of recommendations (nice to have)
+- Object ID audit (duplicates, missing, orphans)
+- Sketch coverage analysis (missing elements)
+- Broken links report
+- **Suggested fixes** with before/after examples
+- Next actions for handoff
+
+**Report Format Example:**
+```markdown
+## Navigation Structure Audit
+
+**Status:** ❌ FAIL
+
+**Issues Found:**
+1. ❌ Missing H3 header before H1
+   - Location: Line 1
+   - Current: `# 1.1 Start Page`
+   - Should be: `### 1.1 Start Page` (add H3 before H1)
+   
+2. ❌ Missing embedded sketch in navigation
+   - Location: Between lines 3-5
+   - Should add: `![Start Page Concept](sketches/...)`
+   
+**Recommendation:**
+Add H3 header and embed sketch between dual "Next Step" links.
+See: step-01-navigation.md for correct format.
+```
+
+**Report Status Levels:**
+- ✅ **READY FOR HANDOFF** - Zero critical issues, ready for dev
+- ⚠️ **NEEDS REVISION** - 1-3 critical issues, fixable quickly
+- ❌ **INCOMPLETE** - 4+ critical issues, needs substantial work
+
+**Agent Behavior:**
+- **Report findings** - Don't automatically fix unless asked
+- **Provide line numbers** - Make issues easy to locate
+- **Show examples** - Include correct patterns for reference
+- **Ask before editing** - "Would you like me to fix these issues?"
+- **Offer audit stamp** - "Would you like me to add an audit stamp to the page for handoff tracking?"
+
+---
+
+## Optional: Audit Stamp for Handoff
+
+When a page specification passes all quality checks and is ready for development handoff, the agent can offer to add a brief audit stamp at the bottom of the document.
+
+**When to Add:**
+- Page passes all quality checks (✅ READY FOR HANDOFF)
+- Designer confirms page is ready for development
+- Team wants handoff tracking in the document itself
+
+**When NOT to Add:**
+- Page still has critical issues
+- Specification is work-in-progress
+- Team prefers external audit tracking
+
+**Audit Stamp Format:**
+```markdown
+---
+
+## Quality Audit
+
+**Status:** ✅ READY FOR HANDOFF  
+**Audit Date:** 2026-01-21  
+**Audited By:** Freya (WDS Page Audit Workflow v1.0)
+
+**Compliance:**
+- ✅ Navigation Structure (WDS Standard)
+- ✅ Page Overview (Strategic Context)
+- ✅ Section Order & Structure
+- ✅ Object Registry (100% Coverage)
+- ✅ Design System Separation
+- ✅ No Unnecessary Information
+
+**Notes:** All OBJECT IDs validated, Design System references confirmed, ready for implementation.
+```
+
+**Agent Dialog:**
+```
+🎉 Audit Complete - All Checks Passed!
+
+**Status:** ✅ READY FOR HANDOFF
+
+This page specification meets all WDS quality standards and is ready for development.
+
+Would you like me to add a quality audit stamp at the bottom of the page?
+This can be useful for:
+- Tracking when the page was validated
+- Confirming handoff readiness to developers
+- Project documentation and history
+
+[Yes, add audit stamp] [No, keep page clean]
+```
+
+**Removing Audit Stamp:**
+The audit stamp can be easily removed later if needed (it's always at the bottom of the document). Some teams prefer to remove it after implementation is complete.
+
+---
+
+## Common Use Cases
+
+### Use Case 1: New Page from Sketch
+
+**Scenario:** Designer uploads a new sketch and needs to create specification.
+
+**Process:**
+1. Run Step 1: Confirm page metadata from scenario
+2. Run Step 2: Generate navigation structure
+3. Run Step 3: Define page overview based on trigger map
+4. Run Step 4: Analyze sketch, create sections and Object IDs
+5. Run Step 5: Validate section order
+6. Run Step 6: Auto-generate Object Registry from sections
+7. Run Step 7: Check Design System separation
+8. Run Step 8: Validate and generate report
+
+**Outcome:** Complete, validated specification ready for handoff.
+
+---
+
+### Use Case 2: Updated Sketch
+
+**Scenario:** Designer updates existing sketch with new elements.
+
+**Process:**
+1. Skip to Step 4: Check existing sections
+2. Add new sections/objects from updated sketch
+3. Run Step 6: Update Object Registry with new IDs
+4. Run Step 8: Validate changes and generate report
+
+**Outcome:** Updated specification with change tracking.
+
+---
+
+### Use Case 3: Quality Audit Before Handoff
+
+**Scenario:** Team lead wants to verify spec quality before developer handoff.
+
+**Process:**
+1. Run entire workflow in "validation mode"
+2. Step 1-7: Check each section against checklists
+3. Step 8: Generate comprehensive quality report
+4. Share report with team, fix critical issues
+5. Re-run Step 8 after fixes
+
+**Outcome:** Confidence in specification completeness.
+
+---
+
+### Use Case 4: Fixing Legacy Spec
+
+**Scenario:** Old specification doesn't follow WDS standards.
+
+**Process:**
+1. Run Step 1-4 in "validation mode" to identify gaps
+2. Fix missing navigation structure
+3. Add missing Object IDs to all interactive elements
+4. Create Object Registry if missing
+5. Run Step 5 to verify all issues resolved
+
+**Outcome:** Legacy spec brought up to current standards.
+
+---
+
+## Benefits
+
+### For Designers 🎨
+- Clear checklist to follow
+- Confidence nothing is missed
+- Professional, consistent output
+- Easy communication with developers
+
+### For Developers 💻
+- Complete, trustworthy specifications
+- All interactive elements have Object IDs
+- Clear implementation order (top to bottom)
+- Easy to test (Object IDs as test targets)
+
+### For Teams 👥
+- Shared quality standards
+- Consistent specification format
+- Easy onboarding for new members
+- Reduced back-and-forth during handoff
+
+### For Project Management 📊
+- Clear completion criteria
+- Quality metrics tracking
+- Reduced rework
+- Faster handoffs
+
+---
+
+## Integration with WDS Workflows
+
+This quality workflow integrates with:
+
+**Before:** 
+- [Page Init Workflow](../steps/step-02-substeps/page-init/) - Creates initial page structure
+- [Sketch Analysis](../substeps/4b-sketch-analysis.md) - Identifies page elements
+
+**After:**
+- [Agentic Development](../agentic-development/) - Builds HTML demos from specs
+- [Design Deliveries](../../../6-design-deliveries/) - Packages specs for handoff
+- [PRD Generation](../../../3-prd-platform/) - Creates developer stories from specs
+
+---
+
+## Tips for Success
+
+### Do:
+- ✅ Run the workflow every time you create or update a page
+- ✅ Use checklists systematically (don't skip items)
+- ✅ Fix critical issues before proceeding to next step
+- ✅ Save quality reports for project history
+- ✅ Track metrics over time to improve process
+
+### Don't:
+- ❌ Skip steps (each builds on the previous)
+- ❌ Ignore warnings (they become critical issues later)
+- ❌ Rush through validation (thoroughness matters)
+- ❌ Mix validation with creation (separate concerns)
+- ❌ Forget to re-validate after fixes
+
+---
+
+## Customization
+
+### For Your Project
+
+You can customize this workflow by:
+
+**Adjusting Standards:**
+- Modify Object ID naming conventions
+- Add project-specific sections
+- Extend validation checklists
+- Add custom quality metrics
+
+**Adding Steps:**
+- Step 3.5: Accessibility audit
+- Step 4.5: Content strategy review
+- Step 5.5: Stakeholder approval
+
+**Location:**
+Customizations should be documented in:
+`/examples/[PROJECT]/docs/quality-standards.md`
+
+---
+
+## Support
+
+### Questions or Issues?
+
+**Documentation:**
+- [WDS Specification Pattern](../WDS-SPECIFICATION-PATTERN.md)
+- [Object Types](../object-types/)
+- [Component File Structure](../COMPONENT-FILE-STRUCTURE.md)
+
+**Examples:**
+- See fictional TaskFlow examples in workflow steps
+- Check existing WDS project specifications for real-world patterns
+
+**Contact:**
+- File issues in project repo
+- Discuss in team channel
+- Reference this workflow in PRs
+
+---
+
+## Version History
+
+**v1.0.0** - 2025-12-28
+- Initial release
+- Pattern extracted from successful WDS projects
+- 6-step sequential workflow
+- Quality report generation
+
+---
+
+**Start the workflow:** [instructions.md](instructions.md)
+

package/src/workflows/4-ux-design/page-specification-quality/steps-v/step-01-page-metadata.md

@@ -0,0 +1,55 @@
+---
+nextStepFile: './step-02-navigation.md'
+---
+
+# Step 1: Validate Page Metadata
+
+## Purpose
+
+Verify that page specification declares platform, page type, viewport, and interaction model inherited from scenario platform strategy.
+
+## Context for Agent
+
+Page Metadata establishes technical context before any design decisions. Without this section, developers don't know if they're building for mobile-first responsive web, native mobile app, desktop application, or other platforms. This affects every implementation decision.
+
+## Key Elements
+
+This step validates presence and completeness of:
+- Platform declaration (from Product Brief/Scenario)
+- Page type (Full Page, Modal, Drawer, etc.)
+- Primary viewport (Mobile-first, Desktop-first, etc.)
+- Interaction model (Touch, Mouse/keyboard, etc.)
+- Navigation context (Public, Authenticated, etc.)
+- Inheritance reference to scenario platform strategy
+
+## Instructions
+
+Check if Page Metadata section exists immediately after page title and frontmatter. Verify all required fields are present and properly inherited from scenario platform strategy.
+
+If Page Metadata section is missing, report as CRITICAL issue. If section exists but fields are incomplete or don't reference scenario inheritance, report as WARNING.
+
+Generate diagnostic report showing:
+- What's missing or incomplete
+- Where it should be located (after page title)
+- Example of correct Page Metadata section
+- Why this matters for developers
+
+If issues found, ask user if they want you to add/fix the Page Metadata section.
+
+## Next Step
+
+After validating page metadata, proceed to step-02-navigation.md
+
+## Validation Checklist
+
+```yaml
+page_metadata_validated:
+  section_exists: [true/false]
+  platform_declared: [true/false]
+  page_type_specified: [true/false]
+  viewport_identified: [true/false]
+  interaction_model_documented: [true/false]
+  navigation_context_defined: [true/false]
+  inherits_from_scenario: [true/false]
+  status: [pass/warning/critical]
+```