--- name: design-craft description: "Emotional design and polish for delightful user experiences. Load this skill when polishing empty states, loading states, error states, adding celebrations and personality, implementing dark mode as a system, adding illustrations, or doing a final polish pass before shipping. Covers empty state quality ladders, loading state psychology, micro-interactions, illustration strategy, visual hierarchy, emotional design patterns, dark mode architecture, and mobile delight. Use alongside interaction-motion (animation) and visual-design (foundations)." version: 2.0.0 --- # Design Craft Creating apps users _love_, not just _use_. This skill covers the emotional and aesthetic elements that transform functional software into delightful experiences. ## The Delight Gap shadcn/ui + Tailwind gives you a professional foundation. But "professional" ≠ "loved." | Level | What It Looks Like | User Reaction | | -------------- | -------------------- | ------------- | | **Functional** | Works correctly | "It works" | | **Usable** | Easy to navigate | "It's fine" | | **Beautiful** | Visually polished | "It's nice" | | **Delightful** | Emotionally resonant | "I love this" | This skill focuses on the jump from Beautiful → Delightful. Research shows the aesthetic-usability effect is real — users perceive beautiful interfaces as more functional. But delight goes beyond aesthetics into emotional connection. --- ## 1. Empty States Empty states are your biggest opportunity to build connection. Users see them first. An empty screen creates decision paralysis and increases time-to-value. ### The Quality Ladder Not all empty states are equal. Aim for level 3-4: 1. **Basic** — assures nothing is broken. "No items yet." Acceptable for internal tools, insufficient for products. 2. **Informative** — explains the state. "This is where your contacts will appear after you import them." Users understand the purpose. 3. **Actionable** — guides the user with a specific CTA. "Create your first project" with a button. Users know what to do next. 4. **Delightful** — creates satisfaction with illustration, personality, and clear action. Users feel invited rather than confronted with emptiness. Best practice: combine levels 2-4. Pre-load demo data instead of showing empty states wherever possible. ### Anti-Patterns ```tsx // ❌ Lazy empty state (Level 0) {items.length === 0 &&

No items found.

} // ❌ Depressing empty state

Nothing here yet.

``` ### Delight Patterns ```tsx // ✅ Inviting empty state (Level 4)

Your inbox is clear!

When you receive messages, they'll show up here. Ready to get started?

``` ### Empty State Formula 1. **Illustration** — visual that matches the emotional context 2. **Headline** — positive framing (not "nothing here") 3. **Explanation** — what will appear here 4. **Action** — clear next step (specific CTA, not generic "Get started") ### Contextual Empty States | Context | Tone | Example Headline | | -------------------- | ---------------------- | ------------------------------------------- | | First time user | Welcoming, exciting | "Let's build something great" | | No results | Helpful, guiding | "No matches — try adjusting your filters" | | Completed state | Celebratory | "All done! You're a productivity machine" | | Error/failure | Empathetic, actionable | "Something went wrong — here's what to try" | | New feature area | Educational | "Track your team's progress here" | | Post-completion | Encouraging rest | GitHub's Octocat strolling through a forest | ### New Feature Education When users encounter an unused feature, the empty state should explain what it does and why they'd want it. Linear does this well — the empty state for a new feature doubles as its best marketing. --- ## 2. Loading States Loading states are moments to reduce perceived wait time and maintain engagement. Research shows skeleton screens feel approximately 20% faster than spinners for identical wait times. ### Anti-Patterns ```tsx // ❌ Generic spinner {loading && } // ❌ Blank screen {loading && null} ``` ### Delight Patterns ```tsx // ✅ Skeleton that matches content shape

{/* Title */} {/* Line 1 */} {/* Line 2 */}

// ✅ Progressive loading with context

Analyzing your data...

This usually takes about 5 seconds

// ✅ Optimistic UI const [items, setItems] = useState(data) async function addItem(item) { // Show immediately setItems([...items, { ...item, isPending: true }]) try { const saved = await api.create(item) setItems(prev => prev.map(i => i.id === item.id ? saved : i)) } catch { setItems(prev => prev.filter(i => i.id !== item.id)) toast.error("Failed to add item") } } ``` ### Loading Principles 1. **Show content shape** — skeletons > spinners, always 2. **Set expectations** — tell users what's happening and how long 3. **Be optimistic** — show success before confirmation when safe 4. **Meaningful delays** — for AI/analysis operations, a slight delay with animation suggests thoroughness. A 0ms "deep analysis" feels fake. 800ms with a meaningful animation feels like the system is working. 5. **Progress bars that accelerate** — bars with slight acceleration at the end feel faster than consistent ones --- ## 3. Micro-Interactions Small animations that provide feedback and create polish. See interaction-motion skill for detailed motion principles. ### Essential Micro-Interactions ```tsx // Button press feedback (squash & stretch) // Whitespace isolation (isolation effect: 40% more memorable)

// Visual weight (borders or surface shifts, not always shadows) ``` --- ## 6. Emotional Design Patterns ### Celebration Moments When users achieve something, celebrate with them. But calibrate to the achievement. ```tsx // Confetti on milestone achievement import confetti from "canvas-confetti"; function onGoalComplete() { confetti({ particleCount: 100, spread: 70, origin: { y: 0.6 } }); } // Subtle success for routine operations ✓ Saved ``` **Calibration rule:** confetti for milestones (completed onboarding, reached a goal, first sale). A checkmark for routine saves. Over-celebrating routine operations ("Congratulations! Your settings have been saved!") is patronizing. ### Personality Injection Add brand voice to UI copy. This is where the product stops feeling like a template. ```tsx // ❌ Generic Password

Must be 8+ characters

// ✅ With personality Password

Make it strong — at least 8 characters, mix it up

// ❌ Generic error

Invalid input

// ✅ Helpful and human

Hmm, that doesn't look quite right. Need a valid email like you@example.com

``` ### Sound Design (Use Sparingly) ```tsx const playSuccess = () => { const audio = new Audio("/sounds/success.mp3"); audio.volume = 0.3; audio.play(); }; // Only play if user hasn't disabled if (!prefersReducedMotion && userSettings.soundEnabled) { playSuccess(); } ``` --- ## 7. Dark Mode as a Design System Dark mode is not inverted light mode. It requires its own design system with different rules for elevation, contrast, saturation, and typography weight. ### The Elevation Principle In light mode, elevated surfaces cast shadows. In dark mode, **elevated surfaces get lighter.** Define 3-5 elevation levels: ```tsx const darkElevation = { base: '#0f0f0f', // Deepest background surface1: '#1a1a1a', // Cards, sidebars surface2: '#222222', // Elevated cards, popovers surface3: '#2a2a2a', // Modals, dropdowns surface4: '#333333', // Tooltips, highest elevation } ``` Never use pure black (#000) for surfaces — it creates excessive contrast and makes shadows invisible. Use dark gray or custom tinted near-blacks. ### Text Contrast Never use pure white for body text. Bright text on dark backgrounds appears heavier than the same weight on light backgrounds. ```tsx const darkText = { primary: 'rgba(255, 255, 255, 0.87)', // High emphasis secondary: 'rgba(255, 255, 255, 0.60)', // Medium emphasis disabled: 'rgba(255, 255, 255, 0.38)', // Disabled // Consider reducing body font weight by one step in dark mode // and slightly increasing letter spacing } ``` ### Saturation Tolerance Key insight: darker surfaces are highly tolerant of saturated colors while still reading as neutral. This is why Linear and Raycast can use vibrant gradients against dark surfaces effectively. Dark mode naturally supports richer, more opinionated color choices without looking garish. However: saturated colors that work on light backgrounds can look neon on dark ones. Desaturate standard semantic colors (success, error, warning) by 10-20% for dark mode. ### Dark Mode Checklist - [ ] Surfaces use tinted dark grays, not pure black - [ ] Text uses opacity-controlled white, not pure white - [ ] Elevation expressed through surface lightness, not shadows - [ ] Body text weight reduced by one step (or letter spacing increased) - [ ] Semantic colors desaturated 10-20% - [ ] Primary/accent colors tested for contrast on dark surfaces - [ ] Images have appropriate contrast - [ ] Charts/graphs adapt colors - [ ] Take advantage of saturation tolerance for brand expression --- ## 8. Mobile Delight ### Touch Targets ```tsx // Minimum 44x44px touch targets

Your inbox is clear!

Primary

Secondary

design-craft

Install this skill

Comments