UI/UX Design
Design user interfaces from a senior engineer's perspective. This isn't about pixel-perfect mockups — it's about defining user flows, interaction patterns, and UI states clearly enough that implementation is unambiguous. Engineers do this when there's no dedicated designer, or when translating vague designs into complete specifications.
Core Principle
Design the states, not just the happy path. Every screen has at least 5 states: loading, empty, partial data, full data, and error. Designing only the "full data" state is the #1 cause of poor user experience.
Scope boundary: naming the owner is not the same as answering anyway
State-management library choice (Zustand vs Redux Toolkit vs Context), the
server/client state split, data fetching, and component folder structure belong
to frontend-architecture. When the ask turns to those, hand off and stop:
name the skill, carry the approved flows and screen states forward as the
constraints the architecture has to satisfy, and leave the choice to it.
Do not pick the library "just as a starting point". A recommendation offered in
passing is the one the reader acts on, and it pre-empts the trade-off the owning
skill exists to work through — with none of its reasoning attached.
Workflow
Step 1: Map the User Flow
Before designing any screen, map the complete user journey:
- Entry point: How does the user arrive? (Direct link, navigation, notification, redirect)
- Happy path: The ideal sequence of screens and actions
- Branch points: Where can the user make different choices?
- Edge paths: What happens on errors, cancellation, timeout, or edge cases?
- Exit points: Where does the user end up after completing (or abandoning) the flow?
Document as an ASCII flow diagram or structured list:
[Landing] → [Sign Up Form] → [Email Verification] → [Onboarding] → [Dashboard]
↓ ↓
[Login Instead] [Resend Email]
↓ ↓
[Login Form] [Verification Timeout] → [Support]
Step 2: Design Each Screen's States
For every screen in the flow, define all states:
| State |
What the user sees |
When it occurs |
| Loading |
Skeleton or spinner |
Data is being fetched |
| Empty |
Illustration + CTA |
No data exists yet |
| Partial |
Content + loading indicator |
Some data loaded, more coming |
| Loaded |
Full content |
Data fetch complete |
| Error |
Error message + retry action |
Fetch failed |
| Offline |
Cached content + offline banner |
No network (if applicable) |
The empty state is a design opportunity, not just a blank page. "You have no projects yet. Create your first one →" is better than an empty table.
Step 3: Specify Layouts and Hierarchy
For each screen, define the content hierarchy. Use the structure at templates/screen-spec.md:
- Primary action: The one thing the user should do on this screen
- Content hierarchy: What's most important → least important (top → bottom, left → right)
- Secondary actions: Available but not prominent
- Navigation: How to move forward, backward, and sideways
Don't design pixel-perfect layouts — design information architecture. What goes where, why, and in what priority order.
Step 4: Define Interaction Patterns
For each interactive element, specify:
Forms:
- Validation timing: On blur, on submit, or real-time?
- Error display: Inline per field, summary at top, or both?
- Multi-step forms: Progress indicator, save on each step, back navigation?
- Submission feedback: Button loading state → success message or redirect
Lists and Tables:
- Pagination, infinite scroll, or load more?
- Sorting and filtering: Which columns, client-side or server-side?
- Bulk actions: Selection model, confirmation for destructive actions
- Empty/filtered-empty states
Modals and Overlays:
- When to use modal vs inline vs new page
- Close behavior (X, click outside, Escape key)
- Focus trapping and restoration
Feedback and Notifications:
- Success: Toast, inline message, or redirect?
- Error: Inline, toast, or modal for critical errors?
- Progress: Determinate bar, indeterminate spinner, skeleton?
See references/interaction-patterns.md for common patterns.
Step 5: Plan Responsive Behavior
Define how the layout adapts across breakpoints:
| Breakpoint |
Target |
Layout Adaptation |
| < 640px |
Mobile |
Single column, bottom nav, full-width inputs |
| 640-1024px |
Tablet |
Two columns, collapsible sidebar |
| > 1024px |
Desktop |
Multi-column, persistent sidebar, hover states |
For each major layout section, specify what changes:
- Navigation: Hamburger menu on mobile vs sidebar on desktop
- Data tables: Card view on mobile vs table on desktop
- Images: Aspect ratio changes, cropping strategy
- Forms: Stacked on mobile vs side-by-side on desktop
Step 6: Produce the Specification
Output using the template at templates/screen-spec.md. Save as docs/ui/feature-name.md. Link from the PRD if one exists.
Principles Applied
- KISS: Design the simplest interface that serves the user's goal. Every additional element competes for attention.
- Progressive disclosure: Show the most important information first. Reveal complexity only when the user needs it.
- Consistency: Reuse patterns across the app. If lists everywhere use pagination, don't switch to infinite scroll for one page.
- Forgiveness: Every destructive action should have undo or confirmation. Users make mistakes.
1---2name: ui-ux-design3description: Design user experiences from an engineer's perspective — user flows, wireframes, interaction patterns, responsive strategy, navigation, loading/error/empty states. Triggers: design the UI, user flow, wireframe, how should this screen look, loading state, error state, empty state, responsive design, navigation, page layout, form design, mockup.4---56# UI/UX Design78Design user interfaces from a senior engineer's perspective. This isn't about pixel-perfect mockups — it's about defining user flows, interaction patterns, and UI states clearly enough that implementation is unambiguous. Engineers do this when there's no dedicated designer, or when translating vague designs into complete specifications.910## Core Principle1112**Design the states, not just the happy path.** Every screen has at least 5 states: loading, empty, partial data, full data, and error. Designing only the "full data" state is the #1 cause of poor user experience.1314## Scope boundary: naming the owner is not the same as answering anyway1516State-management library choice (Zustand vs Redux Toolkit vs Context), the17server/client state split, data fetching, and component folder structure belong18to `frontend-architecture`. When the ask turns to those, hand off **and stop**:19name the skill, carry the approved flows and screen states forward as the20constraints the architecture has to satisfy, and leave the choice to it.2122Do not pick the library "just as a starting point". A recommendation offered in23passing is the one the reader acts on, and it pre-empts the trade-off the owning24skill exists to work through — with none of its reasoning attached.2526## Workflow2728### Step 1: Map the User Flow2930Before designing any screen, map the complete user journey:31321. **Entry point**: How does the user arrive? (Direct link, navigation, notification, redirect)332. **Happy path**: The ideal sequence of screens and actions343. **Branch points**: Where can the user make different choices?354. **Edge paths**: What happens on errors, cancellation, timeout, or edge cases?365. **Exit points**: Where does the user end up after completing (or abandoning) the flow?3738Document as an ASCII flow diagram or structured list:3940```41[Landing] → [Sign Up Form] → [Email Verification] → [Onboarding] → [Dashboard]42 ↓ ↓43 [Login Instead] [Resend Email]44 ↓ ↓45 [Login Form] [Verification Timeout] → [Support]46```4748### Step 2: Design Each Screen's States4950For every screen in the flow, define all states:5152| State | What the user sees | When it occurs |53|-------|-------------------|----------------|54| **Loading** | Skeleton or spinner | Data is being fetched |55| **Empty** | Illustration + CTA | No data exists yet |56| **Partial** | Content + loading indicator | Some data loaded, more coming |57| **Loaded** | Full content | Data fetch complete |58| **Error** | Error message + retry action | Fetch failed |59| **Offline** | Cached content + offline banner | No network (if applicable) |6061The empty state is a design opportunity, not just a blank page. "You have no projects yet. Create your first one →" is better than an empty table.6263### Step 3: Specify Layouts and Hierarchy6465For each screen, define the content hierarchy. Use the structure at [templates/screen-spec.md](templates/screen-spec.md):6667- **Primary action**: The one thing the user should do on this screen68- **Content hierarchy**: What's most important → least important (top → bottom, left → right)69- **Secondary actions**: Available but not prominent70- **Navigation**: How to move forward, backward, and sideways7172Don't design pixel-perfect layouts — design **information architecture**. What goes where, why, and in what priority order.7374### Step 4: Define Interaction Patterns7576For each interactive element, specify:7778**Forms:**79- Validation timing: On blur, on submit, or real-time?80- Error display: Inline per field, summary at top, or both?81- Multi-step forms: Progress indicator, save on each step, back navigation?82- Submission feedback: Button loading state → success message or redirect8384**Lists and Tables:**85- Pagination, infinite scroll, or load more?86- Sorting and filtering: Which columns, client-side or server-side?87- Bulk actions: Selection model, confirmation for destructive actions88- Empty/filtered-empty states8990**Modals and Overlays:**91- When to use modal vs inline vs new page92- Close behavior (X, click outside, Escape key)93- Focus trapping and restoration9495**Feedback and Notifications:**96- Success: Toast, inline message, or redirect?97- Error: Inline, toast, or modal for critical errors?98- Progress: Determinate bar, indeterminate spinner, skeleton?99100See [references/interaction-patterns.md](references/interaction-patterns.md) for common patterns.101102### Step 5: Plan Responsive Behavior103104Define how the layout adapts across breakpoints:105106| Breakpoint | Target | Layout Adaptation |107|-----------|--------|-------------------|108| < 640px | Mobile | Single column, bottom nav, full-width inputs |109| 640-1024px | Tablet | Two columns, collapsible sidebar |110| > 1024px | Desktop | Multi-column, persistent sidebar, hover states |111112For each major layout section, specify what changes:113- **Navigation**: Hamburger menu on mobile vs sidebar on desktop114- **Data tables**: Card view on mobile vs table on desktop115- **Images**: Aspect ratio changes, cropping strategy116- **Forms**: Stacked on mobile vs side-by-side on desktop117118### Step 6: Produce the Specification119120Output using the template at [templates/screen-spec.md](templates/screen-spec.md). Save as `docs/ui/feature-name.md`. Link from the PRD if one exists.121122## Principles Applied123124- **KISS**: Design the simplest interface that serves the user's goal. Every additional element competes for attention.125- **Progressive disclosure**: Show the most important information first. Reveal complexity only when the user needs it.126- **Consistency**: Reuse patterns across the app. If lists everywhere use pagination, don't switch to infinite scroll for one page.127- **Forgiveness**: Every destructive action should have undo or confirmation. Users make mistakes.
SWEStash