bi-agents/_bmad/wds/workflows/4-ux-design/data/validation-standards.md

Page Specification Validation Standards

Purpose: Reference standards for validating WDS page specifications.

---

Standard Section Order

Page specifications must follow this section order:

1. Page Metadata (after title)
2. Navigation (H3 + Next Step + Sketch + Next Step + H1)
3. Page Description (1-2 paragraphs)
4. User Situation
5. Page Purpose
6. Page Sections
7. Object Registry
8. Reference Materials (optional)
9. Technical Notes (optional)
10. Development Checklist (optional)

---

Required Sections

Mandatory

• Page Metadata
• Navigation structure
• Page description
• User Situation
• Page Purpose
• Page Sections
• Object Registry

Optional

• Reference Materials
• Technical Notes
• Development Checklist
• Responsive Behavior (if responsive platform)

---

Page Metadata Requirements

Required Fields:

• Platform (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.)
• Inherits From (Scenario reference)

Example:

## Page Metadata

**Platform**: Mobile web app (responsive PWA)
**Page Type**: Full Page
**Primary Viewport**: Mobile-first (< 768px)
**Interaction Model**: Touch-first
**Navigation Context**: Authenticated

**Inherits From**: Scenario 03 Platform Strategy (see scenario overview)

---

Object ID Format

Standard Format: object-name (lowercase, hyphen-separated)

Examples:

• ✅ booking-detail-header
• ✅ calendar-week-navigation
• ✅ user-profile-avatar
• ❌ bookingDetailHeader (camelCase)
• ❌ Booking_Detail_Header (PascalCase with underscores)

Component Declaration:

#### Component Name
**OBJECT ID**: `object-name`
- **Component**: [Component Name](link-to-design-system)
- **Content**: Description
- **Behavior**: Interactions

---

Design System Separation

Forbidden in Page Specs:

• ❌ CSS classes (.button-primary, .flex-container)
• ❌ Hex color codes (#FF5733, #000000)
• ❌ Pixel values (16px, margin: 20px)
• ❌ Font specifications (font-size: 14px, font-family: Inter)
• ❌ Layout measurements (padding: 10px 20px)
• ❌ CSS properties (display: flex, justify-content: center)

Allowed in Page Specs:

• ✅ Component references with Design System links
• ✅ Design System token references (primary-color, heading-large)
• ✅ Behavioral descriptions ("button changes to active state")
• ✅ Layout intent ("elements stack vertically on mobile")
• ✅ Content specifications ("displays user's full name")

---

Responsive Behavior Documentation

When Required:

• Platform: Responsive Web Application
• Primary Viewport: Mobile-first or Desktop-first

What to Document:

• Layout changes across viewports
• Navigation pattern adaptations
• Content reflow strategies
• Viewport-specific interactions
• Breakpoint behavior

Example:

**Responsive Behavior:**
- **Mobile (< 768px)**: Navigation collapses to hamburger menu
- **Tablet (768px - 1024px)**: Side-by-side layout with condensed sidebar
- **Desktop (≥ 1024px)**: Full three-column layout with expanded navigation

---

Object Registry Requirements

Coverage: 100% of all Object IDs from Page Sections

Format:

## Object Registry

This registry provides a complete index of all interactive and structural elements on this page, enabling traceability from specification to code to Figma.

| Object ID | Type | Description |
|-----------|------|-------------|
| object-name | Component Type | Brief description |

Validation:

• Every Object ID in Page Sections must appear in registry
• No orphaned Object IDs (in registry but not in sections)
• Consistent naming across sections and registry

---

Unnecessary Information

Should NOT appear in page specs:

• Implementation code snippets (HTML, CSS, JavaScript)
• Developer setup instructions
• Version control information (commit messages, PR notes)
• Internal project management notes
• Duplicate content across sections
• Outdated/deprecated information
• Design iteration history

Belongs elsewhere:

• Code → Implementation files
• Setup → Developer documentation
• Version control → Git history
• Project management → Project management tools
• Design decisions → Design decision log

---

Navigation Structure

Required Elements:

1. H3 header with page number and name
2. "Previous Step" and "Next Step" links before sketch
3. Embedded sketch image
4. "Previous Step" and "Next Step" links after sketch (duplicate)
5. H1 header matching H3

Format:

### X.X Page Name

**Previous Step**: ← [Link] | **Next Step**: → [Link]

![Sketch Description](Sketches/filename.jpg)

**Previous Step**: ← [Link] | **Next Step**: → [Link]

# X.X Page Name

---

File Size Limits

Step Files: < 250 lines (< 200 recommended) Reference Documents: No strict limit (quality-guide.md can be larger) Data Files: < 500 lines (use sharding for larger datasets)

---

Validation Checklist Template

validation_checklist:
  section_exists: [true/false]
  required_fields_present: [true/false]
  format_correct: [true/false]
  standards_compliant: [true/false]
  status: [pass/warning/critical]