20 KiB

Raw Blame History

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

Open your page specification
Follow the 8 steps sequentially
Use the checklists in each step file
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

Audit Report Example:

🔍 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?

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 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 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
📖 Related: Page Specifications Deliverable

✅ 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 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:

Navigation (H3 + Next Step + Sketch + Next Step + H1)
Page description paragraph
User Situation
Page Purpose
Reference Materials
Page Sections
Page-Specific Layout Notes (optional)
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

Audit Report Example:

🔍 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
📖 Related: Prepare for Figma Export

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:

## 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:

🔍 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

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:

## 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:

---

## 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:

Run Step 1: Confirm page metadata from scenario
Run Step 2: Generate navigation structure
Run Step 3: Define page overview based on trigger map
Run Step 4: Analyze sketch, create sections and Object IDs
Run Step 5: Validate section order
Run Step 6: Auto-generate Object Registry from sections
Run Step 7: Check Design System separation
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:

Skip to Step 4: Check existing sections
Add new sections/objects from updated sketch
Run Step 6: Update Object Registry with new IDs
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:

Run entire workflow in "validation mode"
Step 1-7: Check each section against checklists
Step 8: Generate comprehensive quality report
Share report with team, fix critical issues
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:

Run Step 1-4 in "validation mode" to identify gaps
Fix missing navigation structure
Add missing Object IDs to all interactive elements
Create Object Registry if missing
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 - Creates initial page structure
Sketch Analysis - Identifies page elements

After:

Agentic Development - Builds HTML demos from specs
Design Deliveries - Packages specs for handoff
PRD Generation - 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:

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

20 KiB Raw Blame History Unescape Escape

Page Specification Quality Guide

Overview

When to Use Quality Workflow

During Page Creation ✨

After Page Updates 🔄

Quality Audits 🔍

Workflow Architecture

How to Execute Workflow

For AI Agents (Freya)

For Human Designers

What This Workflow Checks

✅ Step 1: Page Metadata

✅ Step 2: Navigation Structure

✅ Step 3: Page Overview

✅ Step 4: Page Sections

✅ Step 6: Object Registry

✅ Step 5: Section Order & Structure

✅ Step 7: Design System Separation

✅ Step 7 (continued): Unnecessary Information Detection

✅ Step 8: Final Validation

Example: Standard WDS Pattern

Output: Quality Report

Optional: Audit Stamp for Handoff

Common Use Cases

Use Case 1: New Page from Sketch

Use Case 2: Updated Sketch

Use Case 3: Quality Audit Before Handoff

Use Case 4: Fixing Legacy Spec

Benefits

For Designers 🎨

For Developers 💻

For Teams 👥

For Project Management 📊

Integration with WDS Workflows

Tips for Success

Do:

Don't:

Customization

For Your Project

Support

Questions or Issues?

Version History

20 KiB

Raw Blame History