/elegant-design

name: elegant-design
description: Create world-class, accessible, responsive interfaces with sophisticated interactive elements including chat, terminals, code display, and streaming content. Use when building user interfaces that need professional polish and developer-focused features.

Designing Elegant Interfaces

Philosophy

World-class design is intentional, accessible, and delightful. Every element serves a purpose, every interaction feels natural, and the experience adapts gracefully across contexts.

**Core Principles:**

• **Clarity over cleverness** - Users should never wonder what to do next
• **Consistency over novelty** - Patterns should repeat predictably
• **Performance over features** - Fast, smooth interactions trump visual complexity
• **Accessibility always** - Design for all users from the start
• **Progressive disclosure** - Reveal complexity only when needed
• **Intentional friction** - Make destructive actions harder, constructive actions effortless

When to Use This Skill

Use this skill when:

• Building web applications with React/Next.js/similar frameworks
• Creating developer tools or technical interfaces
• Designing interfaces with chat, terminals, or code display
• Implementing real-time or streaming features
• Ensuring accessibility and responsive design
• Working with shadcn/ui, daisyUI, or HeroUI design systems

Design Process Workflow

Follow this workflow for optimal results:

1. Discovery & Planning (15-30 min)

**Map User Experience:**

# Create flow diagrams with Graphviz
cat > user-flow.dot << 'EOF'
digraph UserFlow {
  Start -> "Observe State"
  "Observe State" -> "Orient Understanding"
  "Orient Understanding" -> "Decide Action"
  "Decide Action" -> "Act Execute"
  "Act Execute" -> "Observe State" [label="OODA loop"]
}
EOF

dot -Tpng user-flow.dot -o user-flow.png

**OODA Loop Mapping:** For each major user goal, optimize the cycle: 1. **Observe** - What information does the user need? 2. **Orient** - How do they make sense of it? 3. **Decide** - What choices are available? 4. **Act** - How do they execute?

**Document States:**

• Entry points (how users arrive)
• Core loops (repeated actions)
• Success states (goals achieved)
• Failure states (errors, recovery paths)
• Edge cases (empty, loading, error, extreme data)

**List Affordances:** Identify every UI element needed:

• Navigation (movement between sections)
• Actions (buttons, links, controls)
• Inputs (forms, editors, pickers)
• Feedback (success, error, loading)
• Content (text, images, data)
• Wayfinding (breadcrumbs, progress)

**Before Building Custom Components:** 1. Search shadcn/ui first (https://ui.shadcn.com) 2. Check daisyUI (https://daisyui.com) 3. Explore HeroUI (https://heroui.com) 4. Build custom only when necessary

2. Design Foundation (20-40 min)

**Establish Visual System:**

Read the detailed foundation guides:

• `foundation/typography.md` - Font selection (Geist, JetBrains Mono), scales, loading
• `foundation/colors-and-spacing.md` - Color palettes, spacing systems, dark mode
• `foundation/layout-patterns.md` - Grids, containers, white space, responsive breakpoints

**Quick Reference:**

• **Typography**: Geist for UI, JetBrains Mono for code (14px minimum)
• **Spacing**: 8px base system (0.5rem, 1rem, 1.5rem, 2rem, 3rem, 4rem, 6rem, 8rem)
• **Colors**: Semantic tokens (--color-background, --color-primary, --color-error, etc.)
• **Layout**: Mobile-first, 12-column grid, generous white space

3. Interactive Elements (30-60 min)

For sophisticated interactive features, reference the specialized guides:

**Chat & Messaging:**

• Read `interactive/chat-and-messaging.md` when building conversational interfaces
• Covers message states, streaming, auto-scrolling, markdown rendering

**Terminals & Code Display:**

• Read `interactive/terminals-and-code.md` for terminal emulators, syntax highlighting, semantic highlighting
• Covers ANSI colors, Shiki integration, copy buttons, line highlighting

**Streaming & Loading:**

• Read `interactive/streaming-and-loading.md` for progressive loading, streaming text, optimistic updates
• Covers skeleton screens, progress indicators, loading hierarchies

**Diffs & Logs:**

• Read `interactive/diffs-and-logs.md` for version control UIs, log viewers
• Covers split/unified diffs, character-level changes, virtual scrolling

4. Implementation (1-3 hours)

**Build Components:**

• Read `implementation/components-and-accessibility.md` for component architecture and WCAG compliance
• Use atomic design: atoms → molecules → organisms → templates → pages
• Ensure keyboard navigation and screen reader support

**Optimize Performance:**

• Read `implementation/performance.md` for Core Web Vitals optimization
• Lazy load, code split, optimize images, measure with Lighthouse

**Test & Refine:**

• Read `implementation/testing-and-qa.md` for comprehensive testing approach
• Test on multiple devices, screen sizes, and with accessibility tools

5. Validation & Refinement

**Pre-Launch Checklist:**

• [ ] User flows tested and OODA loops optimized
• [ ] All states handled (empty, loading, error, success)
• [ ] Mobile responsive (tested on real devices)
• [ ] Accessibility compliant (WCAG AA)
• [ ] Performance measured (Lighthouse score > 90)
• [ ] Geist used for UI, JetBrains Mono for code
• [ ] Design system components used where possible
• [ ] Consistent spacing and typography
• [ ] Both light and dark modes work
• [ ] Keyboard navigation complete
• [ ] Interactive elements polished (see interactive guides)

Quick Decision Tree

**Need to understand the basics?** → Read `foundation/` files first

**Building chat or messaging?** → Read `interactive/chat-and-messaging.md`

**Building terminal or code editor?** → Read `interactive/terminals-and-code.md`

**Need streaming or loading states?** → Read `interactive/streaming-and-loading.md`

**Building diffs or log viewers?** → Read `interactive/diffs-and-logs.md`

**Ready