Distinctive Frontend Design Builder

Frontend Design Skill

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Follow the phased workflow below. Each phase has concrete reference material — use it, don't invent from scratch.

Phased Workflow

Phase 1: Design Direction

Before touching any code, commit to a clear aesthetic direction. Answer these:

Context questions:

• What problem does this interface solve? Who uses it?
• What's the one thing someone will remember about this design?
• What aesthetic direction fits? (Choose ONE — don't blend randomly)

Aesthetic directions to pick from: Brutally minimal · Maximalist chaos · Retro-futuristic · Organic/natural · Luxury/refined · Playful/toy-like · Editorial/magazine · Brutalist/raw · Art deco/geometric · Soft/pastel · Industrial/utilitarian · Sci-fi/cyberpunk

CRITICAL: Every generation must make a fresh choice. Never default to the same direction twice. Vary light/dark themes, fonts, and palettes across generations.

Deliverables from Phase 1:

• ✓ Named aesthetic direction (e.g., "editorial luxury, dark theme")
• ✓ Font pairing selected from references/typography.md
• ✓ Color palette selected from references/color-palettes.md
• ✓ Layout composition(s) selected from references/layout-compositions.md

Phase 2: Token System

Set up the design token foundation before writing any component code.

1. Copy examples/design-tokens.css into the project
2. Override the palette primitives with your chosen palette's HSL values
3. Override --font-display and --font-body with your chosen font pairing
4. Add the Google Fonts @import to your HTML <head> (with preconnect hints)

<!-- Always preconnect BEFORE the font stylesheet -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="[your @import from typography.md]">

Deliverables from Phase 2:

• ✓ design-tokens.css (or equivalent) in place with chosen palette/fonts
• ✓ All colors, spacing, typography, shadows, and motion defined as CSS variables
• ✓ No hardcoded color values or magic numbers anywhere in component code

Phase 3: Build

Load the framework module for your target and implement components using design tokens.

Framework modules — load the relevant one:

Build principles:

• Implement components from the layout compositions you chose
• Apply motion patterns from references/motion-patterns.md at high-impact moments: page load, scroll reveals, hover states
• Use only transform and opacity for animations — never width, height, top, left
• Every interactive element needs a hover state AND a focus-visible state
• Stagger entrance animations for groups of elements (cards, list items)

Mobile responsive (load references/mobile-responsive.md):

• Write CSS mobile-first: base styles for phone, min-width queries for larger screens
• Every tap target: ≥ 44×44px (min-height: 44px; min-width: 44px)
• Use 100svh not 100vh for full-screen sections (iOS Safari compatibility)
• Add env(safe-area-inset-*) padding on fixed bottom elements
• Test at 375px, 768px, and 1280px minimum — use the decision matrix in the module

PWA readiness (load references/pwa-checklist.md for production apps):

• Add manifest.json with correct name, icons (192 + 512 + maskable), theme_color
• Add PWA meta tags to <head> (theme-color, apple-mobile-web-app-capable, apple-touch-icon)
• Register a service worker with appropriate caching strategy
• Create an offline fallback page (offline.html)
• For Vite projects: prefer vite-plugin-pwa over manual SW

Phase 4: Polish & Verify

Visual polish checklist:

• Typography: Are display and body fonts visually distinct and harmonious?
• Color: Is the palette cohesive? Do accents draw the eye to the right places?
• Spacing: Is there enough breathing room between sections? (minimum --space-20 between major sections)
• Motion: Does the page feel alive on load? Are hover states immediate and satisfying?
• Backgrounds: Is there depth, texture, or gradient — or is it a flat color?
• Responsive: Does it look great at 375px? 768px? 1280px? No horizontal overflow?
• Touch: Are all interactive targets ≥ 44px? Does navigation work on mobile?
• PWA (if applicable): Does Lighthouse PWA score 100? Is offline fallback working?

Accessibility verification:

# Run the visual audit after starting your dev server
bash .agents/skills/frontend-design/scripts/visual-audit.sh http://localhost:[port]

The audit checks:

• Color contrast violations (WCAG AA minimum — 4.5:1 for text)
• Missing alt text, accessible names, and ARIA labels
• Skip link presence
• Semantic heading structure (one <h1> per page)
• Font loading performance (CLS)
• prefers-reduced-motion override presence

Fix all CRITICAL issues before marking the task complete. Warnings are acceptable if documented.