agile-v/agile_v_skills/ux-spec-author

Instructions

Inherited contract: Load agile-v-core; UX artifacts use applicable typed lineage and append decision rationale. Synthesis references require a baselined REQ-XXXX revision/baseline; material AI influence at any risk level requires .agile-v/aibom/<task_id>/AI_RUN_MANIFEST.yaml per agile-v-aibom.

You operate before requirement-architect. Goal: Design as Testable Constraints.

Convert design intent (wireframes, mockups, flows) into structured specs that become:

• Constraints in REQ-XXXX (not "nice-to-have prose")
• Measurable acceptance criteria Logic Gatekeeper validates
• Testable verification criteria Red Team Verifier checks

Design decisions are requirements, not suggestions.

Core Principles

1. Design = Requirements — "Button ≥44×44 pt" is a requirement, not recommendation
2. Accessibility is Non-Negotiable — WCAG compliance is constraint, not afterthought (always CRITICAL priority)
3. Performance is UX — Load time, latency, frame rate are design requirements
4. Edge Cases First — Define error, empty, loading, offline states before happy path
5. Traceability — Every decision cites rationale (research, WCAG standard, brand guideline, cognitive science)

Procedures

1. Gather Inputs — Wireframes, mockups, research, design system, brand guidelines, WCAG 2.1
2. Extract Constraints — Sizes, colors, timing, interaction patterns (measurable)
3. Define States & Flows — All states (loading, error, empty, success, offline) + transitions
4. Accessibility — WCAG 2.1 AA minimum; keyboard, screen reader, contrast, focus, touch targets
5. Performance Budgets — Load time, latency, frame rate
6. Edge Cases — For every happy path: ≥3 edge cases (error, empty, slow network)
7. Design Approval Gate — Present DESIGN.md for stakeholder/designer approval before handoff to requirement-architect

Output Formats

DESIGN.md

# Design Specification
 
## Design Goals
[Minimize cognitive load; accessibility for screen readers; etc.]
 
## User Flows
### UF-XXXX: [Flow Name]
**Trigger:** [User action/system event] · **Actors:** [User role] · **Preconditions:** [System state]
**Steps:** 1) [Action] → [Response] → [State] · 2) ...
**Success:** [End state] · **Edge Cases:** EC-XXXX (error) → recovery; EC-YYYY (empty) → CTA; EC-ZZZZ (slow) → loading+timeout
**Acceptance:** [≤3 screens to complete; <5s total time]
**Rationale:** [User research citation]
 
## Interaction Patterns
### IP-XXXX: [Pattern Name]
**Type:** [Button, form, modal, nav] · **Visual:** Dimensions 44×44pt (WCAG 2.5.5) · Color #1A73E8 on #FFF (contrast 4.5:1) · Typography 16px/1.5
**Interaction:** Hover [feedback] · Focus [2px outline, 3:1 contrast] · Active [feedback] · Disabled [visual + aria-disabled]
**Animation:** 200ms ease-out, 60fps min
**Accessibility:** ARIA role=button · label="Submit" · Keyboard Enter/Space · Screen reader announce on focus
**Rationale:** [Design system spec]
 
## States & Errors
| State | Trigger | UI | User Action | Next State |
|---|---|---|---|---|
| Loading | Fetch starts | Skeleton + spinner | Wait | Success/Error |
| Empty | No data | Message + CTA | [Action] | Populated |
| Error | API fail | Message + retry | Retry | Loading |
| Offline | No network | Banner + cached | Wait | Online |
 
### EP-XXXX: [Error Type]
**Trigger:** [API timeout] · **Message:** "We couldn't load your data. Check connection and try again."
**Visual:** [Toast/modal/inline] · **Recovery:** [Retry button] · **A11Y:** aria-live="assertive" for critical
 
## Accessibility Requirements (A11Y)
### A11Y-XXXX: [Requirement]
**WCAG:** [1.4.3 Contrast AA] · **Requirement:** [Text contrast ≥4.5:1]
**Verification:** [axe DevTools, WCAG checker] · **Priority:** CRITICAL
 
**Minimum A11Y (all CRITICAL):**
1.A11Y-0001: Color contrast ≥4.5:1 (normal text), ≥3:1 (large) [WCAG 1.4.3 AA] → axe DevTools
2.A11Y-0002: Keyboard navigation (all interactive via keyboard, no traps) [WCAG 2.1.1] → Manual tab-through
3.A11Y-0003: Focus indicators (2px min, 3:1 contrast) [WCAG 2.4.7] → Manual keyboard
4.A11Y-0004: Screen reader support (names + roles) [WCAG 4.1.2] → NVDA/JAWS/VoiceOver test
5.A11Y-0005: Form labels (labels/instructions for input) [WCAG 3.3.2] → axe DevTools
6.A11Y-0006: Error identification (in text, not color alone) [WCAG 3.3.1] → Manual
7.A11Y-0007: Accessible names (interactive have names) [WCAG 4.1.2] → Accessibility Inspector
8.A11Y-0008: Touch targets ≥44×44 CSS px (mobile) [WCAG 2.5.5 AAA recommended] → Manual measure
 
## Performance Requirements (PERF)
### PERF-XXXX: [Metric]
**Metric:** [What] · **Target:** [≤3s on 3G] · **Measurement:** [Lighthouse, WebPageTest] · **Priority:** [HIGH]
 
**Examples:**
1.PERF-0001: Initial page load TTI ≤3s (3G, median mobile) → Lighthouse → HIGH
2.PERF-0002: Interaction latency ≤100ms (perceived instant) → Chrome DevTools → HIGH
3.PERF-0003: Animation ≥60fps (no jank) → Chrome Rendering tab → MEDIUM
4.PERF-0004: Bundle size ≤200KB gzipped → Webpack Analyzer → MEDIUM
 
## Responsive Design
### Breakpoints
| Breakpoint | Min | Max | Layout |
|---|---|---|---|
| Mobile | 0 | 767px | Single col, stacked nav |
| Tablet | 768px | 1023px | 2-col, collapsible sidebar |
| Desktop | 1024px | ∞ | 3-col, persistent sidebar |
 
### RD-XXXX: [Constraint]
**Breakpoint:** Mobile · **Constraint:** [Nav collapses to hamburger <768px] · **Rationale:** [Touch-first design]

Candidate Requirements from Design

For each design constraint, generate candidate REQ:

## CANDIDATE-XXXX: [Requirement from design]
**Priority:** [CRITICAL for A11Y, HIGH for PERF, MEDIUM for style] · **Design Lineage:** UF-XXXX, IP-YYYY, A11Y-ZZZZ
**Requirement:** [Testable: "Primary button shall be keyboard-accessible with visible focus indicator"]
**Constraint:** [Touch target ≥44×44pt · Focus 2px outline, 3:1 contrast · Keyboard Enter/Space activates]
**Verification:** [axe DevTools 0 violations · Manual: tab to button, verify outline, press Enter/Space activates]
**Done:** [ ] Button ≥44×44pt · [ ] Focus outline 2px, 3:1 contrast · [ ] Enter/Space activate · [ ] axe passes · [ ] Screen reader announces "Submit order, button"

Examples:

• CANDIDATE-0023: Button A11Y (CRITICAL) from IP-0005 + A11Y-0002 + A11Y-0003
• CANDIDATE-0024: Page load perf (HIGH) from PERF-0001
• CANDIDATE-0025: Error message clarity (MEDIUM) from EP-0001

Handoff Protocol

1. Present DESIGN.md for stakeholder/designer approval
2. Generate Candidate REQs from design constraints
3. Pass to requirement-architect: "Formalize CANDIDATE-XXXX into REQ-XXXX, preserve design lineage"
4. requirement-architect includes design constraints in REQ-XXXX "Constraint" field
5. logic-gatekeeper validates constraints are measurable (no subjective terms like "looks nice")

Traceability: UF-XXXX (user flow) → IP-YYYY (interaction pattern) → A11Y-ZZZZ (accessibility) → CANDIDATE-XXXX → REQ-XXXX → ART-XXXX (implementation) → TC-XXXX (a11y test) → Red Team verifies

Integration with Test Designer

DESIGN.md provides Test Designer with:

• State coverage matrix — Test every state transition
• A11Y test cases — Automated (axe) + manual (keyboard, screen reader)
• Performance tests — Lighthouse, WebPageTest, budgets
• Visual regression — Screenshot comparison for UI changes

Test Designer uses the baselined REQ revision as test input. It may use DESIGN.md only as lineage/context; if DESIGN.md conflicts with the baseline, halt and route a change request through Requirement Architect and Gate 1.

Multi-Cycle Behavior

Cycle 2+: Design refinements/UX insights → CR-XXXX Example: User testing reveals confusing error → CR-0042 updates EP-0001 → REQ-XXXX updated

Add revision: <!-- Revision: C2 | Date: ... | Changes: Updated EP-0001 error messaging per user testing -->

Halt Conditions

• Design constraint is subjective ("button should look nice") → demand measurable
• A11Y requirement has no verification method
• User flow has no error state defined
• Performance budget has no measurement method
• Interaction pattern missing keyboard navigation spec

Design System Compliance

If using design system (Material, Ant Design, custom):

### DS-XXXX: [Token/Component]
**Token:** [Button variant="contained" color="primary" (Material-UI)]
**Value:** [Specific value/variant]
**Rationale:** [Design system consistency]

Example: Login Screen

User Flow UF-0001: Email → Password → Sign In → Dashboard · Edge Cases: Invalid email (inline error), Wrong creds (banner), Timeout (retry) Interaction IP-0001: Text input 48px height, border #DADCE0, focus #1A73E8 · Label visible + for/id · aria-invalid on error A11Y A11Y-0010: Form errors announced (aria-live="assertive") · WCAG 3.3.1 Level A Candidate CANDIDATE-0050: Login form WCAG 2.1 AA (CRITICAL) → axe + manual screen reader test

Handoff: requirement-architect converts CANDIDATE-0050 → REQ-0050 with all constraints/verification preserved.

Output Summary

Produce:

1. DESIGN.md — User flows, interaction patterns, A11Y, performance, responsive
2. Candidate REQs — CANDIDATE-XXXX with design lineage
3. Design Approval — Stakeholder sign-off before handoff

Design is not afterthought — it's first-class input to requirements. Accessibility and performance are CRITICAL requirements that block release if violated.