wordle/.claude/skills/wds-4-ux-design/data/specification-audit-workflow.md

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 4 [H] Handover)
• 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:

❌ **Content:** "Sign In" (EN), "Logga In" (SE)

✅ **Content:**
   - EN: "Sign In"
   - SE: "Logga In"

Inconsistent Area Label Format:

❌ Area Label: signin-form-email
❌ **area-label**: `signin-form-email`

✅ **AREA LABEL**: `signin-form-email`

Skipped Heading Levels:

❌ # Page Title
   #### Component

✅ # Page Title
   ## Section
   ### Subsection
   #### Component

Missing Translations:

❌ **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:

✅ 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
• Strategic context (Trigger Map) 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
• Trigger Map 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. Cross-Page Duplicate Detection

Purpose: Compare sections across all pages in the scenario and flag identical or near-identical content that should be shared components.

Process:

1. Collect all section definitions from completed page specs in the scenario
2. Compare sections by structure (heading patterns, object types, layout)
3. Flag matches:
   • Exact duplicate — identical section structure and content across 2+ pages (e.g., navigation header, footer)
   • Near duplicate — same structure with minor content differences (e.g., hero sections with different text but identical layout)
   • Repeated pattern — same object types appearing in multiple pages (e.g., card grids, form fields)

Checklist:

• All completed pages in scenario scanned
• Exact duplicates flagged with source pages listed
• Near duplicates flagged with diff summary
• Repeated patterns identified
• Extraction recommendation for each finding (extract / leave as-is / parameterize)

Severity:

• Critical — Exact duplicate in 3+ pages (must extract)
• Warning — Exact duplicate in 2 pages or near duplicate in 3+ (should extract)
• Suggestion — Repeated pattern (consider extracting)

C. 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

• Cross-page duplicate report (from B)
• 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

# 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
• Trigger Map 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 4 [H] Handover (Design Deliveries) - Before development handoff
• Phase 8 (Product Evolution) - When updating specifications

Agent Integration:

• Freya runs audits on page specifications
• Freya can request audits before development
• Saga can audit for strategic alignment

Menu Trigger: Add to Freya's menu:

- trigger: audit-spec
  exec: "skill:wds-4-ux-design"
  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.