frontend-design

What this skill does

# Frontend Design Skill — Systematic & Creative Web Development

**Skill Location**: `{project_path}/skills/frontend-design/`

This skill transforms vague UI style requirements into executable, production-grade frontend code through a systematic design token approach while maintaining creative excellence. It ensures visual consistency, accessibility compliance, and maintainability across all deliverables.

---

## When to Use This Skill (Trigger Patterns)

**MUST apply this skill when:**

- User requests any website, web application, or web component development
- User mentions design styles: "modern", "premium", "minimalist", "dark mode", "SaaS-style"
- Building dashboards, landing pages, admin panels, or any web UI
- User asks to "make it look better" or "improve the design"
- Creating component libraries or design systems
- User specifies frameworks: React, Vue, Svelte, Next.js, Nuxt, etc.
- Converting designs/mockups to code
- User mentions: Tailwind CSS, shadcn/ui, Material-UI, Chakra UI, etc.

**Trigger phrases:**
- "build a website/app/component"
- "create a dashboard/landing page"
- "design a UI for..."
- "make it modern/clean/premium"
- "style this with..."
- "convert this design to code"

**DO NOT use for:**
- Backend API development
- Pure logic/algorithm implementation
- Non-visual code tasks

---

## Skill Architecture

This skill provides:

1. **SKILL.md** (this file): Core methodology and guidelines
2. **examples/css/**: Production-ready CSS examples
   - `tokens.css` - Design token system
   - `components.css` - Reusable component styles
   - `utilities.css` - Utility classes
3. **examples/typescript/**: TypeScript implementation examples
   - `design-tokens.ts` - Type-safe token definitions
   - `theme-provider.tsx` - Theme management
   - `sample-components.tsx` - Component examples
4. **templates/**: Quick-start templates
   - `tailwind-config.js` - Tailwind configuration
   - `globals.css` - Global styles template

---

## Core Principles (Non-Negotiable)

### 1. **Dual-Mode Thinking: System + Creativity**

**Systematic Foundation:**
- Design tokens first, UI components second
- No arbitrary hardcoded values (colors, spacing, shadows, radius)
- Consistent scales for typography, spacing, radius, elevation
- Complete state coverage (default/hover/active/focus/disabled + loading/empty/error)
- Accessibility as a constraint, not an afterthought

**Creative Execution:**
- AVOID generic "AI slop" aesthetics (Inter/Roboto fonts, purple gradients, cookie-cutter layouts)
- Choose BOLD aesthetic direction: brutalist, retro-futuristic, luxury, playful, editorial, etc.
- Make unexpected choices in typography, color, layout, and motion
- Each design should feel unique and intentionally crafted for its context

### 2. **Tokens-First Methodology**

```
Design Tokens → Component Styles → Page Layouts → Interactive States
```

**Never skip token definition.** All visual properties must derive from the token system.

### 3. **Tech Stack Flexibility**

**Default stack (if unspecified):**
- Framework: React + TypeScript
- Styling: Tailwind CSS
- Components: shadcn/ui
- Theme: CSS custom properties (light/dark modes)

**Supported alternatives:**
- Frameworks: Vue, Svelte, Angular, vanilla HTML/CSS
- Styling: CSS Modules, SCSS, Styled Components, Emotion
- Libraries: MUI, Ant Design, Chakra UI, Headless UI

### 4. **Tailwind CSS Best Practices**

**⚠️ CRITICAL: Never use Tailwind via CDN**

**MUST use build-time integration:**
```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

**Why build-time is mandatory:**
- ✅ Enables tree-shaking (2-15KB vs 400KB+ bundle)
- ✅ Full design token customization
- ✅ IDE autocomplete and type safety
- ✅ Integrates with bundlers (Vite, webpack, Next.js)

**CDN only acceptable for:**
- Quick prototypes/demos
- Internal testing

---

## Implementation Workflow

### Phase 1: Design Analysis & Token Definition

**Step 1: Understand Context**
```
- Purpose: What problem does this solve? Who uses it?
- Aesthetic Direction: Choose ONE bold direction
- Technical Constraints: Framework, performance, accessibility needs
- Differentiation: What makes this memorable?
```

**Step 2: Generate Design Tokens**

Create comprehensive token system (see `examples/css/tokens.css` and `examples/typescript/design-tokens.ts`):

1. **Semantic Color Slots** (light + dark modes):
   ```
   --background, --surface, --surface-subtle
   --text, --text-secondary, --text-muted
   --border, --border-subtle
   --primary, --primary-hover, --primary-active, --primary-foreground
   --secondary, --secondary-hover, --secondary-foreground
   --accent, --success, --warning, --danger
   ```

2. **Typography Scale**:
   ```
   Display: 3.5rem/4rem (56px/64px), weight 700-800
   H1: 2.5rem/3rem (40px/48px), weight 700
   H2: 2rem/2.5rem (32px/40px), weight 600
   H3: 1.5rem/2rem (24px/32px), weight 600
   Body: 1rem/1.5rem (16px/24px), weight 400
   Small: 0.875rem/1.25rem (14px/20px), weight 400
   Caption: 0.75rem/1rem (12px/16px), weight 400
   ```

3. **Spacing Scale** (8px system):
   ```
   0.5 → 4px, 1 → 8px, 2 → 16px, 3 → 24px, 4 → 32px
   5 → 40px, 6 → 48px, 8 → 64px, 12 → 96px, 16 → 128px
   ```

4. **Radius Scale**:
   ```
   xs: 2px (badges, tags)
   sm: 4px (buttons, inputs)
   md: 6px (cards, modals)
   lg: 8px (large cards, panels)
   xl: 12px (hero sections)
   2xl: 16px (special elements)
   full: 9999px (pills, avatars)
   ```

5. **Shadow Scale**:
   ```
   sm: Subtle lift (buttons, inputs)
   md: Card elevation
   lg: Modals, dropdowns
   xl: Large modals, drawers
   ```

6. **Motion Tokens**:
   ```
   Duration: 150ms (micro), 220ms (default), 300ms (complex)
   Easing: ease-out (enter), ease-in (exit), ease-in-out (transition)
   ```

### Phase 2: Component Development

**Step 3: Build Reusable Components**

Follow this structure (see `examples/typescript/sample-components.tsx`):

```typescript
interface ComponentProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  state?: 'default' | 'hover' | 'active' | 'disabled' | 'loading';
}
```

**Required component states:**
- Default, Hover, Active, Focus, Disabled
- Loading (skeleton/spinner)
- Empty state (clear messaging)
- Error state (recovery instructions)

**Required component features:**
- Accessible (ARIA labels, keyboard navigation)
- Responsive (mobile-first)
- Theme-aware (light/dark mode)
- Token-based styling (no hardcoded values)

### Phase 3: Page Assembly

**Step 4: Compose Pages from Components**

```
- Use established tokens and components only
- Mobile-first responsive design
- Loading states for async content
- Empty states with clear CTAs
- Error states with recovery options
```

### Phase 4: Quality Assurance

**Step 5: Self-Review Checklist**

- [ ] All colors from semantic tokens (no random hex/rgb)
- [ ] All spacing from spacing scale
- [ ] All radius from radius scale
- [ ] Shadows justified by hierarchy
- [ ] Clear type hierarchy with comfortable line-height (1.5+)
- [ ] All interactive states implemented and tested
- [ ] Accessibility: WCAG AA contrast, keyboard navigation, ARIA, focus indicators
- [ ] Responsive: works on mobile (375px), tablet (768px), desktop (1024px+)
- [ ] Loading/empty/error states included
- [ ] Code is maintainable: DRY, clear naming, documented

---

## Design Direction Templates

### 1. Minimal Premium SaaS (Most Universal)

```
Visual Style: Minimal Premium SaaS
- Generous whitespace (1.5-2x standard padding)
- Near-white background with subtle surface contrast
- Light borders (1px, low-opacity)
- Very subtle elevation (avoid heavy shadows)
- Unified control height: 44-48px
- Medium-large radius: 6-8px
- Gentle hover states (background shift only)
- Clear but not harsh focus rings
- Low-contrast dividers
- Priority: Readability and consistency
```

**Best for:** Enterprise apps, B2B SaaS, productivity tools

### 2. Bold Editorial

```
Visual Style: Bold Editorial
-