whiteport-design-studio 0.1.0

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

@@ -0,0 +1,54 @@
+---
+nextStepFile: './step-03-page-overview.md'
+---
+
+# Step 2: Validate Navigation Structure
+
+## Purpose
+
+Verify that page specification has proper navigation structure with H3 header, dual "Next Step" links, embedded sketch, and H1 page title.
+
+## Context for Agent
+
+Navigation structure provides immediate context for where the page fits in the user journey. Consistent navigation enables automated tooling, cross-linking, and ensures designers can quickly navigate between related pages. Embedded sketch gives visual reference without leaving the document.
+
+## Key Elements
+
+This step validates:
+- H3 header with page number and name
+- "Next Step" link before sketch (pointing to next page)
+- Embedded sketch image with proper path
+- "Next Step" link after sketch (same as first link)
+- H1 page title matching H3
+- Correct relative paths to adjacent pages
+- Page number consistency across all elements
+
+## Instructions
+
+Check navigation section at top of document. Verify H3 and H1 headers match and include correct page numbers. Confirm dual "Next Step" links exist (before and after sketch) and point to correct adjacent pages using relative paths.
+
+Verify embedded sketch image exists and path is correct (typically `Sketches/[page-number]-[page-name]_[viewport].jpg`).
+
+If navigation structure is missing or incomplete, report as CRITICAL. If links are broken or paths incorrect, report as WARNING.
+
+Generate diagnostic report showing what's missing, incorrect paths, and provide example of correct navigation structure.
+
+## Next Step
+
+After validating navigation structure, proceed to step-03-page-overview.md
+
+## Validation Checklist
+
+```yaml
+navigation_validated:
+  h3_header_present: [true/false]
+  h1_header_present: [true/false]
+  headers_match: [true/false]
+  page_numbers_consistent: [true/false]
+  next_step_before_sketch: [true/false]
+  next_step_after_sketch: [true/false]
+  links_match: [true/false]
+  sketch_embedded: [true/false]
+  paths_valid: [true/false]
+  status: [pass/warning/critical]
+```

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

@@ -0,0 +1,47 @@
+---
+nextStepFile: './step-04-page-sections.md'
+---
+
+# Step 3: Validate Page Overview
+
+## Purpose
+
+Verify that page specification includes strategic context through page description, User Situation, and Page Purpose sections.
+
+## Context for Agent
+
+Page Overview captures strategic intent (WHY) before implementation details (HOW). This section connects design decisions to user needs and trigger map, providing essential context for developers and stakeholders. Without clear overview, developers don't understand the purpose behind design choices.
+
+## Key Elements
+
+This step validates:
+- Page description paragraph (1-2 paragraphs explaining what page does)
+- User Situation section (user's context, needs, emotional state)
+- Page Purpose section (what job page must accomplish)
+- Success criteria or VTC reference
+- Emotional context and pain points addressed
+
+## Instructions
+
+Check for page description paragraph immediately after navigation section. Verify "User Situation" and "Page Purpose" sections exist with meaningful content that explains user context and page goals.
+
+If overview sections are missing, report as CRITICAL. If content is too brief or lacks strategic context, report as WARNING.
+
+Generate diagnostic report showing what's missing or insufficient, provide examples of strong overview content, and explain why strategic context matters.
+
+## Next Step
+
+After validating page overview, proceed to step-04-page-sections.md
+
+## Validation Checklist
+
+```yaml
+page_overview_validated:
+  description_paragraph_present: [true/false]
+  user_situation_section_present: [true/false]
+  page_purpose_section_present: [true/false]
+  emotional_context_included: [true/false]
+  success_criteria_defined: [true/false]
+  strategic_intent_clear: [true/false]
+  status: [pass/warning/critical]
+```

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

@@ -0,0 +1,58 @@
+---
+nextStepFile: './step-05-section-order.md'
+---
+
+# Step 4: Validate Page Sections
+
+## Purpose
+
+Verify that page specification has properly structured Page Sections with Object IDs, component references, and behavior specifications.
+
+## Context for Agent
+
+Page Sections define the actual UI components and their behavior. Object IDs enable traceability from spec → code → Figma. Component references ensure design system consistency. Behavior specs reduce developer guesswork. This is the core implementation guidance section.
+
+## Key Elements
+
+This step validates:
+- "## Page Sections" header present
+- Section Objects (H3) with clear purpose statements
+- Component specs (H4) with Object IDs in format `OBJECT ID: object-name`
+- Design system component references
+- Content specifications for each component
+- Behavior specifications (interactions, states, validation)
+- Proper hierarchy (H3 for sections, H4 for components)
+- **Responsive behavior documentation** (if page metadata declares responsive platform)
+
+## Instructions
+
+Check for "## Page Sections" header. Verify all sections use H3 headers with purpose statements. Confirm all components use H4 headers with Object IDs in correct format.
+
+Validate that components reference design system (links to component docs), specify content clearly, and document behavior/interactions.
+
+**Platform-Specific Validation:**
+If Page Metadata declares **Responsive Web Application** or **Primary Viewport: Mobile-first/Desktop-first**, check that responsive behavior is documented for key components (layout changes, navigation patterns, content reflow, viewport-specific interactions).
+
+If Page Sections missing, report as CRITICAL. If Object IDs missing or malformed, report as CRITICAL. If component references or behavior specs missing, report as WARNING. If responsive platform declared but no responsive behavior documented, report as WARNING.
+
+Generate diagnostic report showing missing Object IDs, incorrect formatting, missing component references, missing responsive documentation, and provide examples of correct structure.
+
+## Next Step
+
+After validating page sections, proceed to step-05-section-order.md
+
+## Validation Checklist
+
+```yaml
+page_sections_validated:
+  page_sections_header_present: [true/false]
+  sections_use_h3: [true/false]
+  components_use_h4: [true/false]
+  all_components_have_object_ids: [true/false]
+  object_id_format_correct: [true/false]
+  design_system_references_present: [true/false]
+  content_specified: [true/false]
+  behavior_documented: [true/false]
+  responsive_behavior_documented: [true/false/not_applicable]
+  status: [pass/warning/critical]
+```

package/src/workflows/4-ux-design/page-specification-quality/steps-v/step-05-section-order.md

@@ -0,0 +1,59 @@
+---
+nextStepFile: './step-06-object-registry.md'
+---
+
+# Step 5: Validate Section Order & Structure
+
+## Purpose
+
+Verify that page specification sections appear in standard WDS order with all required sections present and no duplicate or redundant sections.
+
+## Context for Agent
+
+Consistent section order makes specifications predictable and scannable. Developers and stakeholders know exactly where to find information. Standard order also enables automated tooling and ensures nothing is forgotten.
+
+## Key Elements
+
+This step validates:
+- Sections appear in standard WDS order
+- All required sections are present
+- Optional sections are appropriately placed
+- No duplicate sections
+- No redundant or orphaned content
+
+## Standard Section Order
+
+1. Page Metadata
+2. Navigation (H3 + Next Step + Sketch + Next Step + H1)
+3. Page description paragraph
+4. User Situation
+5. Page Purpose
+6. Page Sections
+7. Object Registry
+8. Reference Materials (optional)
+9. Technical Notes (optional)
+10. Development Checklist (optional)
+
+## Instructions
+
+Scan document structure and compare against standard section order. Identify sections that are out of order, missing required sections, or duplicate sections.
+
+If required sections are missing, report as CRITICAL. If sections are out of order or duplicated, report as WARNING.
+
+Generate diagnostic report showing current section order vs expected order, missing sections, and duplicates. Provide recommendation for correct ordering.
+
+## Next Step
+
+After validating section order, proceed to step-06-object-registry.md
+
+## Validation Checklist
+
+```yaml
+section_order_validated:
+  follows_standard_order: [true/false]
+  all_required_sections_present: [true/false]
+  no_duplicate_sections: [true/false]
+  no_orphaned_content: [true/false]
+  optional_sections_appropriate: [true/false]
+  status: [pass/warning/critical]
+```

package/src/workflows/4-ux-design/page-specification-quality/steps-v/step-06-object-registry.md

@@ -0,0 +1,52 @@
+---
+nextStepFile: './step-07-design-system-separation.md'
+---
+
+# Step 6: Validate Object Registry
+
+## Purpose
+
+Verify that page specification includes complete Object Registry with 100% coverage of all Object IDs defined in Page Sections.
+
+## Context for Agent
+
+Object Registry is the single source of truth for all page elements. It enables automated testing (test by Object ID), facilitates content updates and translations, supports Figma export workflows (aria-label mapping), and ensures complete traceability from spec to code to design.
+
+## Key Elements
+
+This step validates:
+- "## Object Registry" header present
+- Introduction paragraph explaining registry purpose
+- Master Object List table(s) with all Object IDs
+- 100% coverage (every Object ID from Page Sections appears in registry)
+- Proper table formatting (Object ID | Type | Description)
+- No orphaned Object IDs (IDs in registry but not in Page Sections)
+- Consistent naming conventions
+
+## Instructions
+
+Check for "## Object Registry" header. Verify introduction paragraph exists. Extract all Object IDs from Page Sections and compare against Object Registry table(s).
+
+Calculate coverage percentage. Identify missing Object IDs (in sections but not in registry) and orphaned Object IDs (in registry but not in sections).
+
+If Object Registry section is missing, report as CRITICAL. If coverage is below 100%, report as CRITICAL. If table formatting is incorrect, report as WARNING.
+
+Generate diagnostic report showing coverage percentage, missing Object IDs, orphaned Object IDs, and provide example of correct registry format.
+
+## Next Step
+
+After validating object registry, proceed to step-07-design-system-separation.md
+
+## Validation Checklist
+
+```yaml
+object_registry_validated:
+  registry_section_present: [true/false]
+  introduction_paragraph_present: [true/false]
+  table_properly_formatted: [true/false]
+  coverage_percentage: [0-100]
+  all_object_ids_registered: [true/false]
+  no_orphaned_ids: [true/false]
+  naming_conventions_consistent: [true/false]
+  status: [pass/warning/critical]
+```

package/src/workflows/4-ux-design/page-specification-quality/steps-v/step-07-design-system-separation.md

@@ -0,0 +1,64 @@
+---
+nextStepFile: './step-08-final-validation.md'
+---
+
+# Step 7: Validate Design System Separation & Unnecessary Information
+
+## Purpose
+
+Verify that page specification focuses on strategic design intent without CSS implementation details, and contains no unnecessary information like code snippets, version control notes, or duplicate content.
+
+## Context for Agent
+
+Page specs focus on WHAT/WHY (strategic), not HOW (implementation). Design System is the single source of truth for styling. Mixing CSS details into page specs causes maintenance nightmares when styles change. Unnecessary information clutters specs and confuses developers about what's actually required.
+
+## Key Elements - Design System Separation
+
+This step validates NO presence of:
+- CSS classes, hex codes, or color values
+- Font sizes, padding, margins, or layout measurements
+- Styling implementation details
+- Component references properly link to Design System
+- Color/typography references use Design System tokens
+
+## Key Elements - Unnecessary Information
+
+This step validates NO presence of:
+- Implementation code snippets (HTML, CSS, JavaScript)
+- Developer instructions or technical setup steps
+- Version control information (commit messages, PR notes)
+- Internal project management notes
+- Duplicate content across sections
+- Outdated/deprecated information
+- Design iteration history
+
+## Instructions
+
+Scan entire document for CSS implementation details (hex codes like #FF5733, pixel values like 16px, CSS classes like .button-primary, font specifications like font-size: 14px). Report each occurrence with line numbers.
+
+Check for code snippets in fenced code blocks, developer setup instructions, git commit references, duplicate sketches or content, and outdated notes.
+
+If CSS details found, report as CRITICAL. If unnecessary information found, report as WARNING.
+
+Generate diagnostic report showing all violations with line numbers, explain why each is problematic, and provide recommendations for where information should live instead (Design System for styling, separate docs for setup, etc.).
+
+## Next Step
+
+After validating design system separation, proceed to step-08-final-validation.md
+
+## Validation Checklist
+
+```yaml
+design_system_separation_validated:
+  no_css_classes: [true/false]
+  no_hex_codes: [true/false]
+  no_pixel_values: [true/false]
+  no_styling_details: [true/false]
+  component_references_present: [true/false]
+  design_system_tokens_used: [true/false]
+  no_code_snippets: [true/false]
+  no_version_control_info: [true/false]
+  no_duplicate_content: [true/false]
+  no_outdated_information: [true/false]
+  status: [pass/warning/critical]
+```

package/src/workflows/4-ux-design/page-specification-quality/steps-v/step-08-final-validation.md

@@ -0,0 +1,92 @@
+---
+# Final step - no nextStepFile
+---
+
+# Step 8: Final Validation & Quality Report
+
+## Purpose
+
+Cross-reference all sections, verify sketch coverage, check for broken links, validate naming conventions, and generate comprehensive quality report.
+
+## Context for Agent
+
+Final validation catches inconsistencies before handoff and ensures specification completeness. This step synthesizes findings from all previous steps and provides confidence for developers that the specification is production-ready.
+
+## Key Elements
+
+This step validates:
+- Cross-references between sections are consistent
+- All sketch elements are documented in Page Sections
+- All Object IDs in sections appear in Object Registry
+- Internal links are not broken
+- Naming conventions are consistent throughout
+- Page numbers match across all references
+- No orphaned or undocumented elements
+
+## Instructions
+
+Perform final cross-checks across all sections. Verify every element visible in the sketch has corresponding documentation in Page Sections. Confirm all internal links work (navigation links, design system references, etc.).
+
+Check naming consistency (page numbers, Object ID format, component names). Identify any orphaned content or undocumented sketch elements.
+
+Synthesize findings from Steps 1-7 into comprehensive quality report showing overall status, critical issues, warnings, and recommendations.
+
+Generate final quality report with:
+- Executive summary (overall status: PASS/NEEDS WORK/CRITICAL ISSUES)
+- Issues by category (Critical, Warning, Info)
+- Coverage metrics (Object Registry coverage, sketch coverage)
+- Recommendations prioritized by impact
+- Optional: Offer to add audit stamp to page spec for handoff tracking
+
+## Quality Report Format
+
+```markdown
+# Page Specification Quality Report
+
+**Page:** [Page Number] [Page Name]
+**Audit Date:** [Date]
+**Overall Status:** ✅ PASS / ⚠️ NEEDS WORK / ❌ CRITICAL ISSUES
+
+## Executive Summary
+[Brief overview of specification quality]
+
+## Critical Issues (Must Fix Before Handoff)
+[List critical issues from all steps]
+
+## Warnings (Should Fix)
+[List warnings from all steps]
+
+## Info (Nice to Have)
+[List informational items]
+
+## Coverage Metrics
+- Object Registry Coverage: X%
+- Sketch Coverage: X%
+- Design System References: X%
+
+## Recommendations
+[Prioritized list of fixes]
+
+## Next Steps
+[What to do next based on findings]
+```
+
+## Next Step
+
+This is the final step. After generating quality report, ask user if they want to:
+- [F] Fix issues (you help implement fixes)
+- [S] Add audit stamp to page spec (optional handoff tracking)
+- [D] Done (end workflow)
+
+## Validation Checklist
+
+```yaml
+final_validation_complete:
+  cross_references_consistent: [true/false]
+  sketch_coverage_complete: [true/false]
+  links_validated: [true/false]
+  naming_conventions_consistent: [true/false]
+  no_orphaned_content: [true/false]
+  quality_report_generated: [true/false]
+  overall_status: [pass/needs_work/critical]
+```

package/src/workflows/4-ux-design/page-specification-quality/templates/diagnostic-report-template.md

@@ -0,0 +1,227 @@
+# Diagnostic Report Template
+
+**Use this template for generating diagnostic reports during page specification validation.**
+
+---
+
+## Step-Specific Diagnostic Report
+
+```markdown
+🔍 [Step Name] Audit
+
+**Status:** ✅ PASS / ⚠️ WARNING / ❌ CRITICAL
+
+**Issues Found:**
+1. [Issue type] [Description]
+   - Location: Line X-Y
+   - Current: [what exists now]
+   - Should be: [what it should be]
+   - Why: [explanation of why this matters]
+
+2. [Issue type] [Description]
+   - Location: Line X-Y
+   - Current: [what exists now]
+   - Should be: [what it should be]
+   - Why: [explanation of why this matters]
+
+**Recommendation:**
+[Specific actionable fix with examples]
+
+**Example of Correct Format:**
+```[language]
+[code example showing correct implementation]
+```
+
+Would you like me to fix this?
+```
+
+---
+
+## Validation Checklist Format
+
+```yaml
+[section_name]_validated:
+  field_1: [true/false]
+  field_2: [true/false]
+  field_3: [true/false]
+  status: [pass/warning/critical]
+```
+
+---
+
+## Issue Severity Levels
+
+### ✅ PASS
+- All checks passed
+- No issues found
+- Specification meets standards
+
+### ⚠️ WARNING
+- Non-critical issues found
+- Specification functional but could be improved
+- Recommended fixes, not required
+
+### ❌ CRITICAL
+- Critical issues that must be fixed
+- Missing required sections
+- Specification incomplete or non-compliant
+- Blocks developer handoff
+
+---
+
+## Common Issue Types
+
+### Missing Section
+```markdown
+❌ Missing required section: [Section Name]
+   - Location: Should appear after [Previous Section]
+   - Why: [Explanation of why this section is required]
+   - Example: [Show what the section should look like]
+```
+
+### Incorrect Format
+```markdown
+⚠️ Incorrect format: [Element Name]
+   - Location: Line X
+   - Current: [what's there now]
+   - Should be: [correct format]
+   - Why: [Explanation of why format matters]
+```
+
+### Missing Object ID
+```markdown
+❌ Missing Object ID: [Component Name]
+   - Location: Line X
+   - Current: Component has no OBJECT ID declaration
+   - Should be: **OBJECT ID**: `component-name`
+   - Why: Object IDs enable traceability from spec → code → Figma
+```
+
+### Design System Violation
+```markdown
+❌ Design System violation: CSS details in page spec
+   - Location: Line X-Y
+   - Current: Contains hex codes, pixel values, CSS classes
+   - Should be: Component references with Design System links
+   - Why: Page specs focus on WHAT/WHY, Design System handles HOW
+```
+
+### Incomplete Coverage
+```markdown
+⚠️ Incomplete Object Registry coverage
+   - Missing: [list of Object IDs not in registry]
+   - Orphaned: [list of Object IDs in registry but not in sections]
+   - Coverage: X% (should be 100%)
+   - Why: Registry must be single source of truth for all elements
+```
+
+---
+
+## Recommendation Format
+
+### Simple Fix
+```markdown
+**Recommendation:**
+Add the missing section after [Previous Section]:
+
+```markdown
+## [Section Name]
+
+[Content template]
+```
+
+Would you like me to add this section?
+```
+
+### Complex Fix
+```markdown
+**Recommendation:**
+1. Extract CSS details to Design System documentation
+2. Replace inline styles with component references
+3. Add Design System links for colors/typography
+4. Keep page-specific layout notes (mobile vs desktop behavior)
+
+**Next Steps:**
+- Move color values to `Design-System/Foundation/Colors/`
+- Move typography to `Design-System/Foundation/Typography/`
+- Update page spec to reference Design System components
+
+Would you like me to help extract these styles to the Design System?
+```
+
+---
+
+## Final Validation Report Format
+
+```markdown
+# Page Specification Quality Report
+
+**Page:** [Page Number] [Page Name]
+**Audit Date:** [Date]
+**Overall Status:** ✅ PASS / ⚠️ NEEDS WORK / ❌ CRITICAL ISSUES
+
+## Executive Summary
+[Brief overview of specification quality]
+
+## Critical Issues (Must Fix Before Handoff)
+[List critical issues from all steps]
+
+## Warnings (Should Fix)
+[List warnings from all steps]
+
+## Info (Nice to Have)
+[List informational items]
+
+## Coverage Metrics
+- Object Registry Coverage: X%
+- Sketch Coverage: X%
+- Design System References: X%
+- Platform Metadata: Complete/Incomplete
+
+## Recommendations
+[Prioritized list of fixes]
+
+## Next Steps
+[What to do next based on findings]
+```
+
+---
+
+## Usage Guidelines
+
+1. **Be Specific:** Always include line numbers and exact examples
+2. **Be Helpful:** Explain WHY each issue matters
+3. **Be Actionable:** Provide clear recommendations with examples
+4. **Be Conversational:** Use friendly, collaborative tone
+5. **Be Respectful:** Let designer decide whether to implement fixes
+6. **Be Thorough:** Don't skip issues, but group related problems
+
+---
+
+## Example Complete Report
+
+```markdown
+🔍 Page Metadata Audit
+
+**Status:** ⚠️ WARNING
+
+**Issues Found:**
+1. ⚠️ Missing scenario inheritance reference (Line 17-23)
+   - Location: Page Metadata section
+   - Current: All platform fields present but no inheritance link
+   - Should be: "**Inherits From:** Scenario 03 Platform Strategy"
+   - Why: Creates explicit traceability from Product Brief → Scenario → Page
+
+**Recommendation:**
+Add inheritance reference after Navigation Context:
+
+```markdown
+**Navigation Context**: Authenticated - overlays calendar page
+
+**Inherits From**: Scenario 03 Platform Strategy (see scenario overview)
+```
+
+This creates explicit traceability chain and ensures platform context is properly inherited.
+
+Would you like me to add this reference?
+```