Agent skill
ux-spec-author
Converts UX/design intent into testable design specifications that feed requirements. Use when defining user flows, accessibility, or design constraints.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/ux-spec-author
Metadata
Additional technical details for this skill
- author
- agile-v.org
- version
- 1.0
- standard
- Agile V
- sections index
-
[ "Procedures", "Output Formats", "Handoff Protocol" ]
SKILL.md
Instructions
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
- Design = Requirements — "Button ≥44×44 pt" is a requirement, not recommendation
- Accessibility is Non-Negotiable — WCAG compliance is constraint, not afterthought (always CRITICAL priority)
- Performance is UX — Load time, latency, frame rate are design requirements
- Edge Cases First — Define error, empty, loading, offline states before happy path
- Traceability — Every decision cites rationale (research, WCAG standard, brand guideline, cognitive science)
Procedures
- Gather Inputs — Wireframes, mockups, research, design system, brand guidelines, WCAG 2.1
- Extract Constraints — Sizes, colors, timing, interaction patterns (measurable)
- Define States & Flows — All states (loading, error, empty, success, offline) + transitions
- Accessibility — WCAG 2.1 AA minimum; keyboard, screen reader, contrast, focus, touch targets
- Performance Budgets — Load time, latency, frame rate
- Edge Cases — For every happy path: ≥3 edge cases (error, empty, slow network)
- 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
- Present DESIGN.md for stakeholder/designer approval
- Generate Candidate REQs from design constraints
- Pass to requirement-architect: "Formalize CANDIDATE-XXXX into REQ-XXXX, preserve design lineage"
- requirement-architect includes design constraints in REQ-XXXX "Constraint" field
- 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 reads DESIGN.md (alongside REQUIREMENTS.md) for comprehensive coverage.
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:
- DESIGN.md — User flows, interaction patterns, A11Y, performance, responsive
- Candidate REQs — CANDIDATE-XXXX with design lineage
- 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.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?