Skill v1.0.1
currentAutomated scan100/1008 files
version: "1.0.1" 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 Process1.**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 purchaseFlow: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: DashboardDashboardPage├── 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 shadowsSubtle shadows → layered surfaces with soft elevationSurface 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 appearanceHover → cursor over elementActive → pressed/clicked (brief; gives physical feel)Focus → keyboard navigation — visible ring, never hiddenDisabled → 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 designedfor 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 → ImplementationCommitting to aesthetic direction?→ Define tone (pick ONE extreme), differentiation, and 3 defaults you rejectPlanning visual design?→ See references/visual-design.mdPlanning responsive behavior?→ See references/responsive-design.mdAdding interactions/animations?→ See references/interaction-design.mdChoosing between UI patterns?→ See Examples table below or references/design-thinking.mdEvaluating 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 coveredAccessibility 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