SDD Design UI/UX

Write the UI/UX Design section of a design document.

Scope

Cross-Cutting Roles

Note: Cross-cutting concerns are an extension to docs/sdd-guidelines.md for specialist coordination. See sdd-design for full mapping.

UI/UX is:

• Primary owner: Accessibility, Loading states
• Reviewer for: Error handling (owned by frontend)

Instructions

Step 1: Read Context

1. Design skeleton (from sdd-design)
2. All REQs in your section's @derives
3. Foundation anchors (especially SCOPE-*, CONSTRAINT-*, audience)

Step 2: Analyze Requirements

For each assigned REQ, extract UI/UX implications:

Tip: Focus on user goals and experience, not implementation.

Step 3: Design Layout Structure

Define spatial organization:

┌─────────────────────────────────┐
│           {Region}              │
├─────────────┬───────────────────┤
│  {Region}   │    {Region}       │
│             │                   │
└─────────────┴───────────────────┘

Principles:

• Content hierarchy reflects user priorities
• Related elements grouped
• Primary actions prominent

Document layout decisions with @derives linking to REQ.

Step 4: Define Responsive Strategy

Based on REQ viewport requirements:

Decision points:

• Adaptive (different layouts) vs Responsive (fluid)?
• What collapses/hides at each breakpoint?
• Touch targets for mobile?

Step 5: Design Interaction Patterns

For each user action in REQs:

Feedback types:

• Immediate: button states, hover
• Progress: loading, spinners
• Completion: success/error states

Step 6: Design Accessibility

Map REQ features to a11y requirements:

WCAG checklist:

• All interactive elements keyboard accessible
• Focus visible and logical
• Color not sole indicator
• Text contrast ≥4.5:1

Step 7: Define Visual Hierarchy

Prioritize content per REQs:

1. Primary: {what REQ emphasizes most}
2. Secondary: {supporting content}
3. Tertiary: {optional/advanced}

If REQ doesn't specify priority:

• User's primary task → Primary
• Supporting info → Secondary
• Edge cases/advanced features → Tertiary

Document with @derives linking to REQ.

Step 8: Design Loading States

For async operations in REQs:

Step 9: Write Section

## UI/UX Design

@derives: {REQ-IDs}

### Layout Structure
### Responsive Breakpoints
### Interaction Patterns
### Accessibility
### Visual Hierarchy
### Loading States

**Status:** draft

Step 10: Add Decisions

For non-obvious choices:

| ID | Decision | Rationale | Owner |
|----|----------|-----------|-------|
| DEC-00x | {what} | {why — connect to REQ} | uiux |

Step 11: Handoff

Per docs/sdd-guidelines.md §4.3 and §10.6.

1. Update Section Status

**Status:** verified

2. Update State File

# .sdd/state.yaml
documents:
  design:
    sections:
      uiux: verified

3. Create Handoff Record

# .sdd/handoffs/{timestamp}-uiux.yaml
from: sdd-design-uiux
to: sdd-design
timestamp: {ISO-8601}

completed:
  - design.uiux: verified

in_progress: []

blocked: []

gaps: []

next_steps:
  - sdd-design-frontend: Review accessibility — verify components support a11y props
  - sdd-design-perf: Review loading states for performance impact

4. Cross-Cutting Status

@derives Judgment

A layout/interaction @derives from a REQ when:

NOT @derives:

• Generic UX best practices not tied to REQ
• Aesthetic choices without REQ basis

Verification

• All assigned REQs have @derives coverage
• Layout supports all REQ features
• Breakpoints match REQ viewport requirements
• Interactions defined for all user actions in REQs
• Accessibility covers all interactive elements
• Loading states for all async operations
• Decisions logged with rationale
• Cross-cutting items flagged for reviewers

References

Examples