var e=[{file:`SKILL.md`,content:`---
name: frontend-design
description: "Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection."
metadata:
  category: domain
  domain: frontend
  applicability: on-demand
  inputs: [ui-requirements, codebase]
  outputs: [design-guidance, patterns]
  relatedSkills: [react]
---

# Frontend Design

> Comprehensive frontend design system — visual design thinking, typography, color, layout, motion, accessibility, performance, and anti-pattern detection. Synthesized from Anthropic's frontend-design skill, Vercel Web Interface Guidelines, and Impeccable design patterns.

## Quick Reference

**Purpose:** Comprehensive design guidance — typography, color, layout, motion, accessibility, performance, anti-pattern detection.

**Mandatory** for the Frontend agent on every task. Also for any UI, styling, responsive, or design work.

**Context checklist** (infer from codebase if not specified):
Design system? | Brand guidelines? | Accessibility level (AA default)? | Breakpoints? | Motion budget? | Dark mode? | Target platforms?

**Design cycle:** Understand → Explore → Evaluate → Refine

**Key principles:**
- Typography: system font stack, modular scale, max 2 families
- Color: semantic tokens (\`--color-success\`, not \`--green\`), 4.5:1+ contrast
- Layout: CSS Grid for 2D, Flexbox for 1D, \`min()\`/\`clamp()\` for fluid sizing
- Motion: \`prefers-reduced-motion\`, \`will-change\` sparingly, 200-300ms for UI
- Accessibility: semantic HTML first, ARIA only when needed, focus visible, skip links

**Anti-patterns to catch:** z-index wars, magic numbers, \`!important\` chains, px-only sizing, color-only status indicators.

## When to Use

**MANDATORY** for the Frontend agent on every task. Also use when:
- Building any UI component, page, or layout
- Styling, theming, or visual design work
- Reviewing UI for quality, accessibility, or design consistency
- User says "make it look good", "design", "UI", "styling", "responsive", "dark mode", "animation"

## Context Gathering Protocol

Before any design work, gather answers to these questions (infer from codebase if user doesn't specify):

1. **Design System** — Does one exist? Tokens, variables, component library?
2. **Brand Guidelines** — Colors, fonts, logo usage, tone?
3. **Accessibility Requirements** — WCAG level (AA default), assistive tech?
4. **Responsive Breakpoints** — Mobile-first? Specific breakpoints?
5. **Motion Preferences** — Animation budget, reduced-motion support?
6. **Content Model** — CMS, static, dynamic, i18n?
7. **Dark Mode** — Required? System preference detection?
8. **Target Platforms** — Desktop, mobile web, tablet, native?

## Design Thinking Process

Follow this cycle: **Understand → Explore → Evaluate → Refine**

1. **Understand** — What is the user trying to accomplish? What are the constraints?
2. **Explore** — Generate at minimum 2-3 distinct design directions. Name each direction. Describe the aesthetic and rationale.
3. **Evaluate** — Compare against requirements, accessibility, performance, and the AI Slop Test.
4. **Refine** — Iterate on the chosen direction. Polish details.

## Typography

### Hierarchy
- Use a **clear scale**: display → h1 → h2 → h3 → body → caption → overline
- Maximum **3 font sizes** per viewport visible at once
- Use \`font-weight\` to create hierarchy within same size
- Line height: 1.5 for body text, 1.2-1.3 for headings
- **Fluid typography**: use \`clamp()\` for responsive sizing — e.g., \`clamp(1rem, 2.5vw, 1.5rem)\`

### Rules
- Never use more than 2 typeface families
- Ensure minimum **16px** body text on mobile
- Use \`rem\` for font sizes, \`em\` for component-relative spacing
- Monospace only for code: use a dedicated code font family
- Set \`max-width: 65ch\` on text blocks for readability
- Use \`text-wrap: balance\` on headings, \`text-wrap: pretty\` on body
- Provide room for **text expansion** (50%+) for i18n

## Color

### 60-30-10 Rule
- **60%** — Background/surface (neutral)
- **30%** — Secondary/container (brand subtle)
- **10%** — Accent/CTA (brand strong)

### Systematic Color
- Define colors as design tokens with semantic names: \`--color-surface\`, \`--color-text-primary\`, \`--color-accent\`
- Every color needs **4.5:1 contrast ratio** minimum (WCAG AA) for text
- Non-text elements need **3:1** minimum
- Never rely on color alone to convey information — pair with icons, text, or patterns
- Test with color blindness simulators

### Dark Mode
- Detect system preference with \`prefers-color-scheme\`
- Don't just invert — re-design surfaces: dark surfaces get lighter elevation, reduce saturation
- Smooth transition between modes (CSS transitions on \`background-color\`, \`color\`)
- Diagrams/images: consider \`filter: invert(1)\` or provide alternate assets
- Store user preference and sync with system default

## Layout & Spacing

### Grid System
- Use an **8px base grid** — all spacing is a multiple of 8 (4px for tight spaces)
- CSS Grid for 2D layouts, Flexbox for 1D alignment
- Consistent spacing tokens: \`--space-xs: 4px\`, \`--space-sm: 8px\`, \`--space-md: 16px\`, \`--space-lg: 24px\`, \`--space-xl: 32px\`, \`--space-2xl: 48px\`, \`--space-3xl: 64px\`

### Responsive Design
- **Mobile-first**: design for 320px, scale up
- Breakpoints: only add when the layout breaks, not at device widths
- Use \`container queries\` for component-level responsiveness
- Fluid layouts with \`minmax()\`, \`auto-fill\`, \`auto-fit\`
- Every interactive target: minimum **44×44px** touch area (WCAG 2.5.5)

### Rules
- Use consistent gutters — don't mix random padding values
- Stacking: define a z-index scale (e.g., base: 0, dropdown: 100, modal: 200, toast: 300)
- Avoid magic numbers — extract to named tokens

## Motion & Animation

### Principles
- **Purpose before polish** — every animation must serve a purpose: orientation, feedback, continuity, or delight
- **Spring physics** over linear easing — use \`cubic-bezier(0.175, 0.885, 0.32, 1.275)\` or spring-based libraries
- Duration budget: micro-interactions **100-200ms**, transitions **200-400ms**, page transitions **300-500ms**
- Never exceed **500ms** unless it's a storytelling/onboarding animation

### Performance
- Animate only \`transform\` and \`opacity\` — these run on the compositor thread
- Never animate \`width\`, \`height\`, \`top\`, \`left\`, \`margin\`, \`padding\` (trigger layout)
- Use \`will-change\` sparingly and only before the animation starts
- \`requestAnimationFrame\` for JS animations

### Accessibility
- **Always respect \`prefers-reduced-motion\`**: reduce or remove animations when set
- Layout animations: use \`layout\` prop (Framer Motion) or FLIP technique
- Skeleton screens during loading — never an empty blank page
- Skeleton loading → content: smooth fade transition, not a hard swap

### Patterns
- Enter/exit transitions with stagger for lists
- Shared element transitions between route changes
- Micro-interactions on hover/focus: subtle scale, bg-color shift, shadow change
- Pull-to-refresh, swipe gestures (mobile) with physics-based feel

## Accessibility (WCAG AA Mandatory)

### Structure
- Use **semantic HTML**: \`header\`, \`nav\`, \`main\`, \`section\`, \`article\`, \`aside\`, \`footer\`
- Every \`<img>\` has a meaningful \`alt\` (or \`alt=""\` for decorative)
- Every form field has a visible \`<label>\` (not just placeholder)
- Headings form a logical hierarchy (\`h1\` → \`h2\` → \`h3\`, no skipping)

### Keyboard Navigation
- All interactive elements reachable via **Tab** key
- Logical tab order (follows visual reading order)
- Focus indicators: visible, high-contrast, never \`outline: none\` without replacement
- Escape to close modals/dropdowns, Enter/Space to activate
- Skip-to-content link for screen readers

### Screen Readers
- ARIA labels on icons-only buttons: \`aria-label="Close"\`
- Live regions for dynamic content: \`aria-live="polite"\` for updates, \`"assertive"\` for errors
- Landmark roles if semantic HTML is insufficient
- Don't use ARIA when a native HTML element works (\`<button>\` not \`<div role="button">\`)

### Testing
- Tab through entire flow without mouse
- Test with screen reader (NVDA, VoiceOver)
- Run Lighthouse accessibility audit
- Test at 200% zoom — nothing should break or overflow

## Forms

- **Instant inline validation** — validate on blur, not on every keystroke
- Show error messages below the field, not in an alert
- Preserve user input on error — never clear a form on submit failure
- **Auto-save** drafts for long forms (debounced)
- Use \`inputmode\` for mobile: \`numeric\`, \`email\`, \`tel\`, \`url\`
- Multi-step forms: show progress indicator and allow back-navigation
- File uploads: drag-and-drop zone, progress indicator, file type restrictions, preview
- **Optimistic UI**: show success immediately, revert on error

## Navigation & State

- URL should always reflect application state (\`/settings/profile\` not \`/settings#profile\`)
- Support deep linking — any URL should be shareable and land on the right view
- Breadcrumbs for hierarchical navigation (3+ levels deep)
- Keyboard shortcuts for power users (document them)
- Browser back/forward must work correctly — don't break history

## Performance

- **Virtual scroll** for lists > 100 items — don't render 10,000 DOM nodes
- **Lazy load** images: use \`loading="lazy"\`, provide dimensions to prevent layout shift
- **Prefetch** next-likely routes on hover/viewport intersection
- **Code split** by route — each page only loads its own JavaScript
- **Edge rendering** — render at the CDN edge when possible (SSR, RSC)
- Optimize images: use \`<picture>\` with WebP/AVIF + fallback
- Font loading: \`font-display: swap\`, preload critical fonts
- Target LCP < 2.5s, INP < 200ms, CLS < 0.1

## Error Handling

- **Graceful degradation** — partial failures shouldn't crash the entire page
- Show retry buttons on transient errors
- Offline indicator when network is lost
- Clear error messages: what happened, what the user can do about it
- Error boundaries in React: catch rendering errors, show fallback UI
- Never show raw error messages, stack traces, or error codes to users

## SSR & Hydration

- Prevent hydration mismatches: no \`Date.now()\`, \`Math.random()\`, \`window\` in server render
- Use streaming SSR for faster TTFB
- Optimistic mutations: update UI before server confirms
- Handle loading states with Suspense boundaries

## Internationalization (i18n)

- **RTL support**: use logical properties (\`margin-inline-start\` not \`margin-left\`)
- Format dates/numbers/currencies locale-aware — never hardcode formats
- Text expansion room: German/French can be 50%+ longer than English
- Unicode support: test with CJK, Arabic, emoji
- Externalize all user-visible strings

## AI Slop Test — MANDATORY CHECK

Before shipping ANY design, verify it does NOT have these AI-generated tells:

| AI Slop Pattern | What to check |
|-----------------|---------------|
| Centered hero + gradient blob | Does it look like every AI demo landing page? ADD ASYMMETRY |
| Lowercase geometric sans headings | Add personality: case choices, weight variation, size contrast |
| Purple-to-blue gradient | If using gradients, use brand-specific or creative color stops |
| Uniform card grid with icon + heading + text | Vary card sizes, add imagery, break the grid |
| Stock illustration style | Use real photos, custom illustrations, or no imagery |
| "Modern SaaS template" look | Add something unexpected: editorial layout, bold typography, color blocking |
| Generic placeholder copy | Real content or clearly marked FPO (For Placement Only) |
| Identical padding everywhere | Vary rhythm — tight grouping inside sections, generous between |
| No texture or depth | Add subtle noise, shadows, borders, layering |
| Perfectly symmetrical everything | Break symmetry deliberately — offset grids, varied alignments |

If 3+ items match → **STOP and redesign**. The goal is distinctive, not generic.

## Implementation Principles

1. **Design tokens before code** — define variables/tokens first, then use them everywhere
2. **Component boundaries** — each component owns its internal layout, parent owns its placement
3. **Progressive enhancement** — works without JS, enhanced with JS
4. **Content-first** — design with real content, not lorem ipsum
5. **Test in context** — view components inside the actual page, not just in isolation
`}];export{e as default};