premium-frontend-design

What this skill does

# Premium Frontend Design Skill

This skill guides creation of **production-grade frontend interfaces that feel ALIVE** — not generic, not copy-paste, but genuinely crafted experiences that users remember.

> "The difference between a good interface and an unforgettable one is intentionality in every pixel."

---

## Dependencies (Flexible — Choose What Fits)

This skill is **framework-flexible**. Pick packages based on user preference and project needs.

### Core 3D (for WebGL templates)
```bash
pnpm add three @react-three/fiber @react-three/drei
```

### Animation (choose based on user preference)

| Library | Best For | Complexity | Bundle Size |
|---------|----------|------------|-------------|
| **CSS/Tailwind** | Simple transitions, micro-interactions | Low | 0KB |
| **Framer Motion** | React-native feel, layout animations, gestures | Medium | ~30KB |
| **GSAP** | Complex timelines, scroll-triggered, text effects | High | ~60KB |
| **GSAP + Club** | SplitText, ScrollTrigger, MorphSVG | High | ~80KB |

```bash
# Framer Motion (simpler, React-idiomatic)
pnpm add framer-motion

# GSAP (powerful, timeline-based)
pnpm add gsap @gsap/react
# Note: SplitText, ScrollTrigger require GSAP Club license
```

**Decision Guide:**
- User says "simple" or "lightweight" → CSS + Framer Motion
- User says "complex animations" or "scroll effects" → GSAP
- User says "text animations" or "split text" → GSAP + SplitText
- User doesn't specify → Default to Framer Motion (simpler API)

### Optional Enhancements
```bash
# Mesh gradients (for mesh-gradient-hero)
pnpm add @paper-design/shaders-react

# Icons
pnpm add lucide-react

# Charts/Sparklines (for dashboards)
pnpm add recharts
# or lightweight: pnpm add @visx/shape @visx/scale
```

### Browser Compatibility Notes
- `backdrop-filter`: Not supported in Firefox < 103 (add fallback bg)
- WebGL: Provide CSS fallback for older devices
- `@starting-style`: Chrome 117+, Safari 17.4+ (progressive enhancement)

---

## Core Philosophy

### The "Alive" Principle

An interface feels alive when:
- **It breathes**: Subtle ambient animations, particles, or shader effects create constant but non-distracting motion
- **It responds**: Micro-interactions acknowledge every user action with satisfying feedback
- **It has depth**: Layers, parallax, glassmorphism, and shadows create dimensional space
- **It surprises**: At least one element breaks expectations in a delightful way

### Design Thinking (Before ANY Code)

Before writing a single line, answer these:

1. **Purpose**: What problem does this solve? Who uses it?
2. **Tone**: Pick ONE extreme direction (not a blend):
   - Brutally minimal
   - Maximalist chaos
   - Retro-futuristic / Cyberpunk
   - Organic / Natural
   - Luxury / Refined
   - Playful / Toy-like
   - Editorial / Magazine
   - Brutalist / Raw
   - Art Deco / Geometric
   - Industrial / Utilitarian
   - Bio-luminescent / Sci-fi
   - Mission Control / Technical

3. **The One Thing**: What single element will someone remember? Every great interface has a signature moment.

4. **Constraints**: Framework, performance budgets, accessibility requirements.

**CRITICAL**: Bold maximalism and refined minimalism both work. The key is **intentionality, not intensity**. A single, perfectly-executed animation beats 50 mediocre ones.

---

## Wow + Clarity Framework

Use this whenever the brief is vague or when you need to justify design decisions. The goal is **wow factor with purpose**.

### 1. Hierarchy Guardrails

- **1 hero flourish** (shader, particle system, or globe). Everything else supports readability.
- **1 supporting flourish** (micro-interactions, animated stat card, or glowing CTA). No more.
- Layout rule: `Hero (wild) → Content blocks (calm) → Proof (calm) → CTA (highlighted)`.
- If the page has more than one scroll-length of copy, every second section should be mostly static.

### 2. Typography Discipline

- **Max 2 headliner fonts** (display + body). Monospace only for data.
- Headline letter-spacing ≥ -0.04em. Anything tighter kills readability.
- Body width target: 55–75 characters per line on desktop, 35–45 on mobile.
- Always pair big display text with a plain supporting sentence under 80 characters.

### 3. Color & Contrast Rules

- Limit neon usage to **primary CTA + 1 accent**. Everything else stays in zinc/neutral palette.
- If background is busy (shader, gradients, particles), add a `bg-black/70` or `bg-slate-950/70` scrim behind text.
- Keep contrast ratios ≥ 4.5:1 for body copy even if the aesthetic is cyberpunk.
- Add a grayscale preview check before shipping: if it looks muddy, dial the palette back.

### 4. Motion Throttle

- **Default**: CSS or Framer Motion with durations ≤ 400ms, easing `cubic-bezier(0.34, 1.56, 0.64, 1)`.
- **Escalate to GSAP/WebGL** only if the brief explicitly asks for cinematic or interactive experiences.
- Max 1 continuous animation per viewport (e.g., shader OR wave bars, not both).
- Provide a “calm mode”: disable non-essential motion when `prefers-reduced-motion` is on OR when user scrolls past hero.

### 5. When Requirements Are Vague

| Situation | Default | Optional Upgrade |
|-----------|---------|------------------|
| User only says “clean SaaS” | `mesh-gradient-hero` + `bento-grid` | Swap hero background for CPPN if they later ask for “more energy” |
| User says “dashboard” with no flair | `bento-grid` + `dashboard-widgets` + CSS glow pills | Add `digital-liquid` shader only after data viz is signed off |
| User says “hero section” but nothing else | Text-first layout + CSS gradient | Offer shader/globe as a suggestion, never as default |

If the prompt does not explicitly mention WebGL, assume **CSS-first** and opt-in to shaders only when the user embraces the cost.

---

## Anti-Patterns (NEVER Do This)

### Visual Anti-Patterns
❌ White/light backgrounds as default (dark mode is premium)
❌ Generic gradients (purple-to-blue on white is AI slop)
❌ Evenly-distributed, timid color palettes
❌ Static, lifeless backgrounds
❌ Cookie-cutter component layouts
❌ Missing loading/transition states
❌ Jarring, un-eased animations

### Typography Anti-Patterns
❌ Inter, Roboto, Arial, system fonts for headlines
❌ Same font for everything
❌ Default line-heights and letter-spacing
❌ Boring, predictable type scales

### Code Anti-Patterns
❌ Inline styles scattered randomly
❌ No CSS variables for theming
❌ Animations without `will-change` or GPU acceleration
❌ Canvas/WebGL without `requestAnimationFrame`
❌ Missing cleanup in `useEffect`

---

## Design System

### 1. Color Architecture

**Rule: ONE dominant accent, everything else supports it.**

```typescript
// Premium Dark Theme (Default)
const colors = {
  // Backgrounds (layer from darkest to lightest)
  bg: {
    void: '#000000',      // True black for maximum contrast
    primary: '#050505',   // Main background
    elevated: '#0a0a0a',  // Cards, modals
    subtle: '#111111',    // Hover states
  },
  
  // Glass surfaces
  glass: {
    bg: 'rgba(255, 255, 255, 0.03)',
    border: 'rgba(255, 255, 255, 0.08)',
    hover: 'rgba(255, 255, 255, 0.06)',
  },
  
  // Text hierarchy
  text: {
    primary: '#ffffff',
    secondary: '#a1a1aa',   // zinc-400
    muted: '#71717a',       // zinc-500
    ghost: '#3f3f46',       // zinc-700
  },
  
  // Accent (choose ONE per project)
  accent: '#ff4d00',  // Neon Orange
  // accent: '#00f3ff',  // Neon Cyan
  // accent: '#ccff00',  // Neon Lime
  // accent: '#F5E445',  // Premium Yellow
  // accent: '#a855f7',  // Electric Purple
}
```

**Accent Usage Rules**:
- Primary actions: Full accent color
- Secondary elements: Accent at 20% opacity
- Borders/lines: Accent at 30% opacity
- Glows: Accent with blur, 40-60% opacity
- Never use accent for large background areas

### 2. Typography System

**Rule: Display font for impact, Body font for reading, Mono for data.**

```css
/* Tier 1: Display/Headlines - BOLD, characterful */
--font-display: 'Chakra Petch', 'Orbitron', 'Bebas Neue', 'Play