---
name: principle-product-design
description: UX and product design principles — Nielsen's 10 usability heuristics, visual hierarchy, information architecture, interaction design patterns, design-system compliance, and responsive layout. Accessibility/WCAG conformance is delegated to `swe-workbench:principle-accessibility`. Auto-load when reviewing UX, evaluating usability, checking interaction patterns, assessing visual hierarchy or information architecture, auditing design-system compliance, or planning user-facing features.
---
<!-- preload-canary: SWB-PRELOAD-PRINCIPLE-PRODUCT-DESIGN -->

# Product Design Principles

## Usability Heuristics (Nielsen's 10)

Every user-facing component must satisfy these. Violations block progress.

| Heuristic | Rule | Common Violation |
|---|---|---|
| **Visibility of system status** | Users always know what's happening | No loading indicator during async operations; silent failures with no feedback |
| **Match between system and real world** | Use language and concepts users know | Developer jargon in UI labels ("null", "undefined", "404"); unfamiliar abbreviations |
| **User control and freedom** | Provide undo, cancel, and escape routes | Destructive action with no confirmation; no way to cancel an in-progress operation |
| **Consistency and standards** | Same action, same result, everywhere | Button styles that vary across views; inconsistent terminology for the same concept |
| **Error prevention** | Prevent errors before they happen | Allowing invalid input submission; no constraints on date ranges or numeric fields |
| **Recognition over recall** | Show options, don't force memorization | Hidden navigation requiring memorized paths; no search/filter on long lists |
| **Flexibility and efficiency** | Support both novice and expert users | No keyboard shortcuts for power users; no progressive disclosure for complex forms |
| **Aesthetic and minimalist design** | Every element earns its place | Cluttered layouts with competing visual weights; information overload on a single view |
| **Error recovery** | Clear error messages with actionable next steps | "Something went wrong" with no guidance; error messages using technical stack traces |
| **Help and documentation** | Contextual help where users need it | No tooltips on ambiguous icons; no onboarding for complex features |

## Visual Hierarchy

Users scan, they don't read. Guide their attention.

| Principle | Rule | Common Violation |
|---|---|---|
| **Size communicates importance** | Primary content largest, secondary smaller, tertiary smallest | All text same size; critical numbers not emphasized |
| **Weight directs attention** | Bold for key data, regular for supporting content | Everything bold (nothing stands out) or everything light (nothing anchors) |
| **Color creates meaning** | Semantic colors for states (profit/loss, success/error), muted for secondary | Arbitrary color usage; profit shown in red (wrong cultural mapping) |
| **Spacing creates grouping** | Related items closer together, unrelated items further apart | Uniform spacing everywhere; no visual relationship between elements |
| **Alignment creates order** | Consistent alignment grid; numbers right-aligned in tables | Mixed alignment; numbers left-aligned making comparison impossible |
| **Whitespace prevents overload** | Generous padding around content blocks; breathing room between sections | Cramped layouts; every pixel filled with content |

## Information Architecture

Apply when features involve navigation, content structure, or multi-step flows.

| Pattern | When to Use | Key Rule |
|---|---|---|
| **Clear navigation** | Any app with multiple views | User always knows where they are and how to get back |
| **Logical grouping** | Content with multiple categories | Group by user mental model, not implementation structure |
| **Content prioritization** | Views with mixed-importance content | Most important content visible first; progressive disclosure for details |
| **Search and filter** | Lists with >10 items | Provide search for text content, filters for categorical data |
| **Breadcrumbs** | Hierarchical navigation deeper than 2 levels | Show full path; each segment clickable |

## Interaction Design

Apply when building interactive components, forms, or stateful UI.

| Pattern | Rule | Common Violation |
|---|---|---|
| **Immediate feedback** | Every user action gets a visible response within 100ms | Button click with no visual change until async completes |
| **Loading states** | Show skeleton or spinner for operations >300ms | Blank screen during data fetch; layout shift when content loads |
| **Empty states** | Meaningful message + action when no data exists | Blank area with no explanation; "No results" with no guidance |
| **Error states** | Specific message + recovery action for every failure mode | Generic error; error shown far from the source; no retry option |
| **Confirmation for destructive actions** | Require explicit confirmation before delete/remove/reset | Single-click delete with no undo; confirmation dialog with unclear consequences |
| **Progressive disclosure** | Show simple view first, reveal complexity on demand | All options visible at once on complex forms; no way to access advanced settings |
| **Optimistic updates** | Update UI immediately, reconcile on server response | Wait for server round-trip before showing change |

## Design System Compliance

When a design system exists (check `CLAUDE.md` or `docs/design-system.md`), enforce consistency.

| Rule | Enforcement |
|---|---|
| **Use existing tokens** | Colors, spacing, typography from the design system — never raw hex/px values for themed properties |
| **Use existing components** | Check component library before building new ones |
| **Follow naming conventions** | Component names, CSS classes, token names match established patterns |
| **Maintain visual consistency** | New components match the visual language of existing ones |
| **Document deviations** | If a design system rule is broken, document why explicitly |

## Responsive and Adaptive Design

Apply when building layouts that must work across screen sizes.

| Pattern | Rule |
|---|---|
| **Mobile-first** | Start with smallest layout, enhance for larger screens |
| **Fluid layouts** | Use relative units (%, rem, fr) over fixed px for layout dimensions |
| **Breakpoint strategy** | Define breakpoints by content needs, not device names |
| **Touch-friendly** | 44px minimum touch targets; adequate spacing between tappable elements |
| **Content reflow** | Content reflows gracefully — no horizontal scroll, no truncated critical info |

**Accessibility/WCAG conformance** (keyboard navigation, color contrast, ARIA, semantic HTML, screen-reader patterns) → `swe-workbench:principle-accessibility`.

## Rationalization Tables

### Usability Violation Excuses

| Excuse | Reality |
|---|---|
| "Users will figure it out" | They won't. They'll leave, complain, or misuse the feature. Design for clarity. |
| "It's obvious from context" | What's obvious to the builder is rarely obvious to the user. Test with fresh eyes. |
| "We don't have time for empty/error states" | An app without error states is an app that breaks silently. Users lose trust faster than you think. |
| "Loading states are polish, not essential" | A blank screen with no feedback makes users click again, creating duplicate actions. Loading states prevent errors. |
| "The user will only do this once" | First impressions determine whether users return. One-time flows need the most guidance. |
| "Power users don't need hand-holding" | Even power users need system status visibility, error recovery, and consistent behavior. Heuristics apply universally. |

### Visual Design Violation Excuses

| Excuse | Reality |
|---|---|
| "It matches the mockup" | Mockups don't cover all states, screen sizes, or data variations. Validate against principles, not just pixels. |
| "Consistent spacing is nitpicking" | Inconsistent spacing creates subconscious unease. Users can't articulate why it feels "off" but they notice. |
| "The data determines the layout" | You determine how data is presented. No dataset should break your visual hierarchy. Design for extremes. |
| "We'll polish it in a design pass" | Polishing 50 components later costs more than getting 1 component right now. Visual quality is not a phase. |

## Red Flags — STOP and Reassess

- Interactive element using `<div>` or `<span>` instead of semantic HTML (see `swe-workbench:principle-accessibility` for the correct elements)
- Color as the only way to communicate state (red/green without icons or text)
- No loading indicator for any async operation
- Form with no validation feedback until submission
- Custom component that duplicates an existing design system component
- Layout that assumes specific data length (truncation without tooltip, overflow without scroll)
- Interactive element smaller than 44×44 px
- No visual feedback on hover, focus, or active states
- Error message that says "Error" or "Something went wrong" with no specifics

### If You Catch Yourself Thinking…

| Thought | What to Do Instead |
|---|---|
| "I'll add the loading state later" | Add it now. Define the three states (loading, content, error) before writing the content state. |
| "The contrast looks fine to me" | Check it. Use the project's semantic color tokens which should already meet WCAG AA. |
| "This doesn't need an empty state" | Every list, table, and data view needs an empty state. What does the user see when there's nothing to show? |
| "I'll match the existing pattern" | Check if the existing pattern meets usability heuristics first. Don't propagate violations. |
| "Users won't notice the inconsistent spacing" | They will — subconsciously. Use the design system's spacing tokens. |
| "This form is simple, no need for validation UX" | Every form needs inline validation, clear error messages, and prevented submission of invalid data. |
| "It works on my screen size" | Does it work at 320px? At 1440px? With 200% font scaling? Test the extremes. |

## UX Complexity Threshold

| Complexity | Interaction Pattern | States Required | Example |
|---|---|---|---|
| **Display only** | Static content, no interaction | Content, empty | Dashboard metric card, static label |
| **Simple interaction** | Single action, immediate result | Content, empty, loading, error, hover, focus | Toggle switch, single button action |
| **Form interaction** | User input with validation | Content, empty, loading, error, validation, disabled, success | Search input, settings form |
| **Complex flow** | Multi-step, stateful, conditional | All above + progress, confirmation, undo, partial error | Multi-step wizard, bulk operations, drag-and-drop |