Elegant Design

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 to implement? → Read implementation/ files

Need tools or want to avoid mistakes? → Read reference/ files

Design Systems Priority

1. shadcn/ui (https://ui.shadcn.com) - PRIMARY CHOICE

   • Excellent accessibility defaults
   • Radix UI primitives
   • Tailwind-based, customizable
   • Copy-paste into project

2. daisyUI (https://daisyui.com)

   • Semantic component names
   • Tailwind plugin
   • Rapid prototyping

3. HeroUI (https://heroui.com)

   • Modern, polished
   • Strong design language
   • Product interfaces

See reference/design-systems.md for detailed comparison and usage patterns.