version: "1.0.0" name: principle-product-design description: UX and product design principles — Nielsen's 10 usability heuristics, visual hierarchy, 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, 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 | |