Product UI Craft

This skill guides creation of production-grade product interfaces that feel polished, responsive, and premium. The goal: interfaces that look like they came from an expert product designer, not AI-generated templates.

Inspiration: Linear, Stripe, Superhuman, Figma, Notion, Slack

Core Philosophy

Production quality comes from invisible craft — details users feel but can't pinpoint:

• Keyboard-first — Power users never touch the mouse
• Instant feedback — Optimistic updates, zero perceived latency
• Graceful states — Loading, empty, and error states that build trust
• Systematic consistency — Design tokens, not hardcoded values
• Purposeful motion — Physics-based animation that feels natural

If users notice the interface, something is wrong. Great product UI disappears.

Decision Framework

When Starting a New Interface

1. Define the interaction model first

• What are the primary keyboard shortcuts?
• How does selection work?
• What's the command palette scope?

1. Establish the token system

• Set up semantic colors, spacing scale, and typography
• Never hardcode values — always use tokens
• See tokens.md

1. Map all states

• Loading: skeleton or spinner?
• Empty: what action do we guide toward?
• Error: how do we help recovery?
• See states.md

1. Plan motion intentionally

• What transitions maintain spatial continuity?
• Where does micro-interaction add delight?
• What should be instant?
• See animation.md

Choosing Animation Approach

Rule: If you're debating whether to animate something, make it instant. Animation should be obvious wins.

Loading State Selection

Empty State Design

Ask: "What should the user do next?"

• First-time user → Guide to primary action
• Filtered to zero → Offer to clear filters
• Completed state → Celebrate (inbox zero)
• Search no results → Suggest alternatives

Implementation Checklist

Keyboard & Focus

• [ ] Command palette (⌘K) implemented
• [ ] Primary actions have shortcuts
• [ ] Tab order is logical
• [ ] Focus trapping in modals
• [ ] Focus visible styles (not default)
• [ ] Roving tabindex for lists

States

• [ ] Skeleton screens match content structure
• [ ] Empty states guide action
• [ ] Errors are specific and recoverable
• [ ] 0, 1, many cases handled
• [ ] Text overflow handled (truncation + tooltip)
• [ ] Optimistic updates where appropriate

Motion

• [ ] Spring animations for entrances
• [ ] Reduced motion respected
• [ ] No layout-triggering animations
• [ ] Transitions under 300ms
• [ ] Staggered animations for lists

Visual Polish

• [ ] Semantic color tokens used
• [ ] Consistent spacing rhythm
• [ ] Text selection styled
• [ ] Custom scrollbar (if needed)
• [ ] Focus rings match brand
• [ ] Shadows create hierarchy

Reference Files

Detailed implementation patterns organized by domain:

• [interactions.md](references/interactions.md) — Command palette, keyboard shortcuts, focus management, selection patterns, drag interactions, cursor states
• [animation.md](references/animation.md) — Easing functions, spring physics, micro-interactions, page transitions, loading animations
• [states.md](references/states.md) — Loading states, empty states, error handling, edge cases, optimistic updates
• [tokens.md](references/tokens.md) — Color tokens, typography scale, spacing system, shadows, theming
• [patterns.md](references/patterns.md) — Concrete code recipes: navigation, lists, forms, toasts, modals, menus, scroll behavior

Quick Patterns

Command Palette Trigger

useEffect(() => {
  const handler = (e: KeyboardEvent) => {
    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
      e.preventDefault();
      setOpen(prev => !prev);
    }
  };
  window.addEventListener('keydown', handler);
  return () => window.removeEventListener('keydown', handler);
}, []);

Spring Animation Config

// Framer Motion presets
const springs = {
  snappy: { type: 'spring', stiffness: 400, damping: 30 },
  smooth: { type: 'spring', stiffness: 300, damping: 30 },
  bouncy: { type: 'spring', stiffness: 400, damping: 15 },
};

Semantic Color Token Structure

:root {
  /* Surfaces */
  --surface-primary: #ffffff;
  --surface-secondary: #f9fafb;
  --surface-hover: rgba(0, 0, 0, 0.04);
  
  /* Text */
  --text-primary: #111827;
  --text-secondary: #6b7280;
  --text-tertiary: #9ca3af;
  
  /* Accent */
  --accent: #3b82f6;
  --accent-subtle: rgba(59, 130, 246, 0.1);
}

Skeleton Shimmer

.skeleton {
  background: linear-gradient(90deg,
    var(--surface-secondary) 0%,
    var(--surface-tertiary) 50%,
    var(--surface-secondary) 100%);
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
}

@keyframes shimmer {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

Toast Entrance

<motion.div
  initial={{ opacity: 0, y: 20, scale: 0.95 }}
  animate={{ opacity: 1, y: 0, scale: 1 }}
  exit={{ opacity: 0, scale: 0.95 }}
  transition={{ type: 'spring', stiffness: 400, damping: 25 }}
>

Anti-Patterns to Avoid

Don't:

• Use ease or linear for UI transitions (use ease-out or springs)
• Animate width/height/top/left (use transform)
• Show spinners for fast operations (<200ms)
• Use alert() or browser-native dialogs
• Hardcode colors, spacing, or font sizes
• Forget keyboard navigation
• Skip empty/error states
• Over-animate (if in doubt, make it instant)

Do:

• Prefer CSS transitions for simple state changes
• Use springs for entrances and complex motion
• Show skeletons that match content structure
• Make all destructive actions reversible (undo)
• Test with keyboard-only navigation
• Handle all edge cases (0, 1, many, overflow)
• Respect prefers-reduced-motion