interface-design

name	interface-design
description	UI/UX design patterns for software. Trigger: When designing user interfaces, planning UX flows, or evaluating UI decisions.
license	Apache 2.0
metadata	{"version":"1.0","type":"domain","skills":["a11y"]}

Interface Design

Plan UI with intentional aesthetic direction, user flows, component hierarchy, and visual system. Design decisions before implementation.

When to Use

• Planning UI for a new feature or page
• Designing user flows and interactions
• Evaluating UI/UX decisions
• Building wireframes or component hierarchies
• User asks "how should this look?" or "what's the best UX for X?"

Don't use for:

• Implementation (react, mui, css skills)
• Accessibility (a11y)
• Backend APIs (architecture-patterns)

---

Critical Patterns

✅ REQUIRED: Commit to a Bold Aesthetic Direction

Before writing any UI code, define a clear conceptual direction and commit to it.

## Aesthetic Direction

**Purpose**: What problem does this interface solve? Who uses it?
**Domain**: 5+ concepts, metaphors, or vocabulary from this product's world
**Color world**: 5+ colors that exist naturally in this domain's physical space
**Tone**: Pick ONE — brutally minimal, maximalist, editorial, luxury, brutalist,
          retro-futuristic, soft/pastel, industrial, organic... commit to an extreme.
**Differentiation**: What's the one element that could only exist for THIS product?
**Defaults rejected**: Three obvious patterns you're explicitly not doing.

"Bold maximalism and refined minimalism both work — the key is intentionality, not intensity."

Typography: choose distinctive, characterful faces over generic defaults. Color: a palette that feels like it came FROM the product's world, not applied to it. Composition: unexpected layouts, asymmetry, diagonal flow, generous negative space or controlled density — all valid when intentional. Backgrounds: gradient meshes, noise textures, geometric patterns, grain overlays, layered transparencies, dramatic shadows — atmosphere and depth beyond solid colors. Complexity: match implementation to vision — maximalist design = elaborate animations and effects; minimalist = restraint, precision, and whitespace.

✅ REQUIRED: User-First Design Process

## Design Process

1. **Understand** → Who is the user? What's the goal?
2. **Map** → What's the user flow? (entry → action → result)
3. **Structure** → What components are needed? (hierarchy)
4. **Validate** → Does the design meet the requirements?
5. **Implement** → Build with technology skills (react, css, mui)

✅ REQUIRED: Define User Flows Before UI

## User Flow: Checkout

**Entry:** User clicks "Checkout" from cart
**Goal:** Complete purchase

Flow:
1. Review cart items → [Edit quantities] → [Remove items]
2. Enter shipping address → [Auto-fill from saved] → [Validate address]
3. Select shipping method → [Show estimated delivery]
4. Enter payment → [Validate card] → [Show errors inline]
5. Review order → [Edit any section] → [Place order]
6. Confirmation → [Order number] → [Email sent]

**Edge cases:**
- Empty cart → Redirect to shop with message
- Payment failure → Show error, keep form state, retry
- Session timeout → Save progress, prompt re-login

✅ REQUIRED: Component Hierarchy

Map the UI structure before building components.

## Component Hierarchy: Dashboard

DashboardPage
├── DashboardHeader
│   ├── PageTitle
│   └── DateRangePicker
├── MetricsRow
│   ├── MetricCard (revenue)
│   ├── MetricCard (orders)
│   └── MetricCard (customers)
├── ChartsSection
│   ├── RevenueChart
│   └── OrdersChart
└── RecentOrdersTable
    ├── TableHeader
    ├── TableRow[]
    └── Pagination

✅ REQUIRED: State Identification

Identify what state each component needs before implementing.

## State Analysis: Checkout

| Component       | State Needed              | Source             |
|-----------------|---------------------------|--------------------|
| CartReview      | items, quantities         | Redux store        |
| ShippingForm    | address fields, errors    | Local form state   |
| ShippingMethod  | methods[], selected       | API + local        |
| PaymentForm     | card fields, errors       | Local form state   |
| OrderSummary    | totals, tax, shipping     | Derived from above |
| CheckoutPage    | currentStep, isSubmitting | Local state        |

✅ REQUIRED: Depth Strategy — Pick One

Choose ONE depth approach and apply it consistently. Mixing strategies breaks visual coherence.

Borders-only      → technical, precise feel; no shadows
Subtle shadows    → layered surfaces with soft elevation
Surface shifts    → elevation via lightness (dark mode: higher = slightly lighter)
Borders + shadows → reserved for emphasis elements only

❌ Don't mix approaches — inconsistent depth is the clearest sign of no system.

Inputs: slightly darker than surroundings (signals "type here"). Sidebars: same background as canvas with a subtle border — not a different hue that fragments space.

✅ REQUIRED: Interactive States — All 5

Every interactive element needs all five states defined before shipping.

Default  → resting appearance
Hover    → cursor over element
Active   → pressed/clicked (brief; gives physical feel)
Focus    → keyboard navigation — visible ring, never hidden
Disabled → reduced opacity + cursor:not-allowed

❌ Missing focus = broken keyboard accessibility
❌ Missing disabled = broken form UX

✅ REQUIRED: Validation Checkpoints

## Checkpoint 1: User Flow
- [ ] All user goals are achievable
- [ ] Error cases handled (empty, invalid, failure)
- [ ] Navigation is clear (user always knows where they are)

## Checkpoint 2: Component Structure
- [ ] Each component has single responsibility
- [ ] No component handles 3+ unrelated concerns
- [ ] Hierarchy reflects visual nesting

## Checkpoint 3: State Design
- [ ] State is colocated (closest to where it's used)
- [ ] No redundant state (derived values computed, not stored)
- [ ] Loading and error states accounted for

## Checkpoint 4: Craft Self-Evaluation
- [ ] Swap Test: replacing the typeface/layout with generic alternatives changes how it feels
- [ ] Squint Test: hierarchy is perceivable without reading — contrast/scale carry it
- [ ] Signature Test: 3+ specific elements feel unique to THIS product
- [ ] Token Test: CSS variable names evoke this product's world, not any generic project

✅ REQUIRED: Design Critique Framework

Use when evaluating existing UI — a mockup, PR, or shipped feature. Run all 5 dimensions in order.

1. First Impression (2 seconds)

• What draws the eye first? Is that the right element for the user's goal?
• Is the purpose immediately clear without reading any text?

2. Usability

• Can the user accomplish their goal with the current flow?
• Are interactive elements obvious — buttons look pressable, links distinguishable?
• Are there unnecessary steps between intent and outcome?

3. Visual Hierarchy

• Is there a clear reading order? Do size, weight, and contrast guide it?
• Is whitespace used deliberately — not just as leftover space?

4. Consistency

• Does it follow the established design system (spacing tokens, color tokens, typography scale)?
• Do similar elements (same action type, same data type) look and behave the same?

5. Accessibility (use a11y skill for full audit)

• Color contrast ≥ 4.5:1 for text, ≥ 3:1 for UI elements
• Touch targets ≥ 44×44px
• All interactive elements reachable and operable by keyboard

Feedback rules: Be specific (cite element and reason). Suggest alternatives alongside issues. Acknowledge what works.

---

❌ NEVER: Generic AI Defaults

❌ Generic fonts (Inter, Roboto, Arial, system-ui) when context calls for character
❌ Purple/blue gradients on white — the most overused AI aesthetic
❌ Predictable card-grid-dashboard layouts without context-specific differentiation
❌ "Clean and modern" without defining what those mean for THIS product
❌ Same aesthetic repeated — vary light/dark themes, typefaces, and palettes across projects

"No design should be the same. Make unexpected choices that feel genuinely designed
for this context."
"Extraordinary creative work is possible here — don't hold back."

❌ NEVER: Design in Code

# ❌ WRONG
"Let me create the components and figure it out as I go."

# ✅ CORRECT
"Let me commit to an aesthetic direction, map the user flow,
define the component hierarchy, identify state needs, then implement."

---

Conventions

Visual system: Modular type scale (0.75rem → 3rem), line-height (headings 1.1–1.3, body 1.5–1.7), fluid clamp(). Spacing: 8pt grid (4px → 64px). Color: semantic tokens, WCAG ratios (4.5:1 text, 3:1 UI). See visual-design.md.

Responsive: Mobile-first, content-driven breakpoints. dvh for mobile browser compatibility. Touch targets 44×44px minimum. See responsive-design.md.

Motion: transform/opacity for 60fps. In React, use the Motion library for complex sequences. Timing: 100–150ms (feedback), 200–300ms (toggles), 300–500ms (modals). Support prefers-reduced-motion. One well-orchestrated page-load reveal creates more delight than scattered micro-interactions. See interaction-design.md.

---

Decision Tree

Designing a new page/feature?
  → Aesthetic direction → User flow → Component hierarchy → State analysis
  → Visual design → Responsive → Motion → Implementation

Committing to aesthetic direction?
  → Define tone (pick ONE extreme), differentiation, and 3 defaults you reject

Planning visual design?
  → See references/visual-design.md

Planning responsive behavior?
  → See references/responsive-design.md

Adding interactions/animations?
  → See references/interaction-design.md

Choosing between UI patterns?
  → See Examples table below or references/design-thinking.md

Evaluating existing UI?
  → Run Design Critique Framework (5 dimensions: impression, usability, hierarchy, consistency, a11y)
  → Run 4 craft checkpoints → Verify depth strategy is consistent
  → Confirm all 5 interactive states are covered

Accessibility concerns?
  → Use a11y skill; Checkpoint 4 for planning; visual-design.md for contrast ratios

---

Examples

Pattern	Use When	Example
List → Detail	Browsing collections	Products list → Product page
Wizard/Steps	Multi-step processes	Checkout, onboarding
Dashboard	Overview + drill-down	Admin panel, analytics
Master-Detail	List with inline preview	Email client, file manager
Modal/Dialog	Focused action, confirmation	Delete confirm, quick edit
Tabs	Related content sections	Settings, profile sections
Search + Filter	Large datasets	Product catalog, user list
Infinite scroll	Content feeds	Social feed, news

---

Edge Cases

Responsive: Mobile-first, then expand.

Loading states: Every async operation needs loading, success, error, and empty states.

Empty states: Design for zero data (first use, no results, filtered to nothing).

Error recovery: Always provide a way forward — never a dead end.

---

Checklist

• Aesthetic direction committed (domain explored, color world, tone, differentiation, 3 defaults rejected)
• User flow mapped with entry, goal, and edge cases
• Component hierarchy reflects visual structure
• State identified and colocated appropriately
• All 4 validation checkpoints passed (including craft self-evaluation)
• Depth strategy chosen and applied consistently
• All 5 interactive states defined per interactive element
• Loading, error, and empty states designed
• Responsive behavior planned
• Accessibility considerations included

---

Resources

• design-thinking.md — Design process, wireframing, UI pattern comparisons, validation questions
• visual-design.md — Typography scale, spacing system, color contrast, iconography, layout foundations
• interaction-design.md — Motion timing, micro-interactions, feedback patterns, gesture interactions, performance optimization
• responsive-design.md — Mobile-first strategy, breakpoints, container queries, fluid typography, touch targets
• a11y — Accessibility patterns and ARIA
• react — React implementation patterns
• composition-pattern — Component composition API design
• mui — Material UI component library
• tailwindcss — Utility-first CSS implementation