frontend-design

name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use when asked to build web components, pages, artifacts, posters, or applications (websites, landing pages, dashboards, React components, HTML/CSS layouts), when styling/beautifying any web UI, when applying a color/font theme to slides/docs/HTML, or when reviewing UI against Vercel Web Interface Guidelines (accessibility, UX audit, design review). Generates creative polished code, applies pre-built themes, and avoids generic AI aesthetics. license: Complete terms in LICENSE.txt allowed-tools: Read, Glob, Grep, Write, Edit, Bash, WebFetch

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

Project Design Source of Truth (check FIRST)

Before committing to any aesthetic direction, check for a DESIGN.md at the project root:

[ -f DESIGN.md ] && echo "DESIGN.md present — it is the source of truth" || echo "no DESIGN.md — free creative direction"

When DESIGN.md is present, it is the normative design system — not a suggestion. It uses the google-labs-code/design.md format (YAML token frontmatter + prose). You MUST:

• Parse the tokens (colors, typography, spacing, rounded, components) and use those exact values — do NOT invent palette or typography the file already defines.
• Honor the prose sections (Overview, Colors, Typography, Layout, Shapes, Components) for how to apply tokens, and treat Do's and Don'ts as hard guardrails.
• Generate consumable tokens from it rather than hand-writing CSS: npx @google/design.md export --format tailwind DESIGN.md (Tailwind v3 JSON) or --format dtcg. For Tailwind v4 @theme, mirror the YAML token values directly into the @theme block.
• Validate your output's contrast/refs against the system: npx @google/design.md lint DESIGN.md.

In this mode, the "BOLD aesthetic direction" guidance below is constrained by the design system — express creativity in layout, composition, motion, and detail, NOT by overriding the defined tokens.

When no DESIGN.md exists, proceed with the full creative-direction flow below. (If the work is establishing a project's first design system, consider emitting a DESIGN.md so future frontend work has a source of truth — /plan:design produces one automatically.)

Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• Constraints: Technical requirements (framework, performance, accessibility).
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Operating Modes

This skill is not just a generator — it is a diagnostic. Three modes:

1. Create (default) — building new UI. Read the Aesthetics Guidelines + Canon of Slop first, then produce work that avoids every listed pattern.
2. Audit — the user shares existing UI/copy. If the project has a DESIGN.md (see § Project Design Source of Truth), audit against it FIRST — deviations from the committed token system are STRUCTURAL findings and outrank generic slop. Then run the Canon of Slop (references/anti-slop-canon.md) + microcopy sins (references/microcopy.md). Call out every pattern by name, then suggest the specific replacement.
3. Spot-fix — the user points at one element. Diagnose it, explain why it's slop, rewrite it.

Always name the sin before fixing it. "This is a purple-gradient hero (#7c3aed→#2563eb), the default AI palette" builds more trust than "let's improve the colors."

Severity (audit/spot-fix)

Rank every finding, then fix structural first — never polish a broken foundation:

Rationalizations (do not accept these from yourself)

File Output

All generated HTML, CSS, and standalone frontend files MUST be written to docs/diagrams/ in the current working directory. NEVER write to /tmp, project root, or any other location.

mkdir -p docs/diagrams
# Write to: docs/diagrams/my-diagram.html

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Raster imagery (hero shots, textures, mockup photos, social cards). When a design needs a real raster asset that CSS/SVG can't produce, generate it with the ai-media-gen skill (scripts/bin/ai-media image …, Vercel AI Gateway) and match the prompt to your chosen palette and aesthetic direction (style + dominant token colors). Logos remain svgl's job; vector diagrams remain visual-explainer's. See the ai-media-gen skill for usage.

Frontend Aesthetics Guidelines

Focus on:

• Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
• Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
• Spatial Composition: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
• Backgrounds & Visual Details: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

The Canon of Slop (NEVER)

These are the highest-signal markers of the 2024–2026 AI-generated design monoculture. NEVER ship them. Name the pattern when you spot it.

The full 16-pattern canon, font alternatives by context, and non-state UX interaction anti-patterns live in references/anti-slop-canon.md — read it in audit mode or when you need a specific replacement.

Precedence: when a project DESIGN.md defines tokens (see § Project Design Source of Truth), it WINS over these defaults — even if it picks a font this canon would otherwise flag. The canon governs free creative direction; a committed design system governs constrained direction.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

Aesthetic Decisions → Code

Quick Recipes

Hero with depth:

.hero {
  @apply relative min-h-[90vh] flex items-center;
  background: radial-gradient(ellipse at 30% 50%, hsl(var(--primary) / 0.15), transparent 70%);
}
.hero::before {
  @apply content-[''] absolute inset-0 bg-[url('/noise.svg')] opacity-5 mix-blend-overlay pointer-events-none;
}

Staggered reveal on scroll:

<div className="space-y-6">
  {items.map((item, i) => (
    <div
      key={item.id}
      className="animate-in fade-in slide-in-from-bottom-4"
      style={{ animationDelay: `${i * 80}ms`, animationFillMode: "both" }}
    />
  ))}
</div>

Implementation Checklist by Direction

Minimalist:

• Max 2 font weights, 1 accent color
• Generous whitespace (gap-16+ between sections)
• No shadows, no gradients, no borders -- rely on spacing alone
• Typography does ALL the heavy lifting (size contrast, weight contrast)

Maximalist:

• 3+ layered backgrounds (gradient + noise + blur)
• Multiple animation entry points (stagger, parallax, hover)
• Bold color blocking -- no neutral zones
• Intentional visual overload -- every element earns its complexity

Dark luxury:

• bg-zinc-950 or darker, accent in gold/warm tones
• Subtle grain texture overlay at 3-5% opacity
• backdrop-blur-xl on glass cards
• Thin borders (border border-white/5) for depth without weight

Editorial:

• Dominant serif display font (Playfair Display, Fraunces, DM Serif)
• Asymmetric 2-column layout with oversized images
• Pull quotes and drop caps
• High contrast black/white with one editorial accent color

Pre-Built Themes

10 ready-to-apply professional themes are available in references/themes/. Each defines a complete color palette + font pairing. Show assets/theme-showcase.pdf to the user for visual selection, then read the chosen theme file and apply it.

Available themes: Ocean Depths, Sunset Boulevard, Forest Canopy, Modern Minimalist, Golden Hour, Arctic Frost, Desert Rose, Tech Innovation, Botanical Garden, Midnight Galaxy.

To generate a custom theme on-the-fly: extract colors/tone from user description and create a new theme spec in the same format as references/themes/*.md.

CSS Microinteractions (motion-and-transitions)

For UI state changes — modals, dropdowns, panels, badges, page slides, icon swaps, number pop-ins, card resizes — load the motion-and-transitions skill. It ships nine copy-ready CSS snippets (from transitions.dev) with a unified curve language (out-quint for ambient, spring-overshoot for attention) and mandatory prefers-reduced-motion guards. This is the first stop for any "make X open/close smoothly" request before reaching for GSAP or WebGL.

When to use: Any UI component that transitions between two states — open/closed, visible/hidden, active/idle. Does not require React; works in plain HTML + CSS.

How to load: Skill({ skill: "motion-and-transitions" })

Motion & Animation Components (Motion Core)

For designs needing interactive animations, 3D effects, text reveals, scroll-driven motion, or physics-based interactions, read references/motion-core.md. This provides React porting patterns for 36 production-ready animation components spanning:

• Text animations: Split reveals, scramble effects, weight waves, text loops
• 3D/WebGL effects: Glass refraction, god rays, globes, fluid simulation, dithering
• Interaction: Magnetic cursor, macOS dock, image trails, interactive grids
• Layout animation: FLIP grids, card stacks, slideshows, marquees
• Atmosphere: Halo, lava lamp, neural noise, plasma, glitter cloth

When to suggest: Hero sections needing interactive depth, scroll-driven reveals, hover effects with physics, image galleries with 3D transitions, navigation with micro-interactions, or any design where motion would elevate the aesthetic beyond static CSS. Pair with Radiant shaders for layered depth.

Stack: React Three Fiber (@react-three/fiber) for WebGL, GSAP (@gsap/react) for DOM animations. Shaders are framework-agnostic GLSL — copy verbatim from reference.

Generative Shader Effects (Radiant)

For designs needing animated backgrounds, hero effects, or visual depth beyond static CSS, read references/radiant-shaders.md. This provides access to 91 production-ready, zero-dependency shader effects (Canvas 2D + WebGL) embeddable via iframe.

When to suggest: Hero sections, full-viewport backgrounds, dark-themed interfaces, or any design where generative motion would elevate the aesthetic. Especially effective with the Mono, Blue, or Arctic color schemes for tech/corporate contexts.

A React/Next.js wrapper component is available at ~/.claude/recon/radiant-react-wrapper/ — copy into the target project and use <RadiantShader html={...} colorScheme="blue" loading="lazy" />.

Brand Logos (svgl)

When your design references brands, services, or tools by name (Stripe, GitHub, Vercel, AWS, etc.), use real SVG logos from svgl.app instead of emojis, text placeholders, or guessed SVG paths. Read the svgl skill (~/.claude/skills/svgl/SKILL.md) for the full API reference, theme variant selection (light/dark), and embedding patterns. Key points:

• Search the API for the correct logo URL: https://api.svgl.app?search={brand}
• Pick the right variant: dark background = dark route, light background = light route
• Embed via <img>: <img src="https://svgl.app/library/stripe.svg" alt="Stripe" width="32" height="32" />
• Fall back gracefully: if a brand isn't in svgl, use Phosphor Icons or a styled text placeholder
• Never use emojis as brand placeholders

UI Icons (Phosphor)

For UI iconography (navigation, buttons, status indicators, forms), use Phosphor Icons as the default library. Read the phosphor-icons skill (~/.claude/skills/phosphor-icons/SKILL.md) for the full API. Key points:

• React: import { HouseIcon } from "@phosphor-icons/react" — props: size, weight, color
• HTML: <i class="ph ph-house"></i> via CDN stylesheet
• 6 weights: thin, light, regular, bold, fill, duotone — pick one per UI region
• Brand logos go through svgl.app (above), not Phosphor

Related Skills

When building frontend interfaces, also consider these complementary skills:

• svgl — SVG brand logos from svgl.app. Use for brand iconography (Stripe, GitHub, Vercel, AWS logos).
• phosphor-icons — Phosphor icon library for UI iconography. Use for navigation, actions, and status indicators.
• geist-design — Vercel Geist design system. Use for design tokens, typography, and component patterns.
• algorithmic-art — Generative and algorithmic art patterns. Use for creative backgrounds, data visualizations, and decorative elements.

Skill boundaries (do not duplicate)

• state-handling owns loading / empty / error STATE patterns. The non-state UX interaction anti-patterns (modals, wizards, hamburger-on-desktop, toast spam, hover-only) live in this skill's references/anti-slop-canon.md; for state behavior, defer to state-handling.
• leo-writing-voice owns general prose voice (Teams / Slack / email / chat replies). This skill's references/microcopy.md covers UI microcopy ONLY — error messages, CTA labels, empty-state text, form labels. For human-facing prose, load leo-writing-voice instead.

Validation

To check UI code against Vercel's Web Interface Guidelines, fetch:

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

Apply all rules from the fetched content and report findings as file:line violations.