frontend-design

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.

Great interfaces rarely come from a single thing. It's a collection of small, intentional details that compound into an experience that feels crafted.

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

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.

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

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. When building with shadcn/ui, leverage its token system as your foundation (see "Using shadcn Variables" below) — then extend it with custom tokens for your unique aesthetic.
• 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.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

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.

Using shadcn Variables

shadcn/ui provides a semantic CSS variable system that handles light/dark mode automatically. Use these as your baseline token layer — they give you theme-awareness for free.

Core surface & text tokens:

• --background / --foreground — page-level background and text
• --card / --card-foreground — card surfaces and their text
• --popover / --popover-foreground — floating surfaces (dropdowns, tooltips)
• --muted / --muted-foreground — subdued surfaces and secondary text

Interactive tokens:

• --primary / --primary-foreground — primary actions (buttons, links)
• --secondary / --secondary-foreground — secondary actions
• --accent / --accent-foreground — hover states, highlights
• --destructive / --destructive-foreground — destructive/danger actions

Border & structure tokens:

• --border — default border color (used on cards, inputs, dividers)
• --input — input-specific border color
• --ring — focus ring color
• --radius — base border radius (e.g. 0.5rem). Derive all other radii from this: calc(var(--radius) - 2px) for inner elements, calc(var(--radius) + 4px) for outer wrappers.

How to reference them: In Tailwind v4 / shadcn v2, variables store raw color values and are used directly: bg-background, text-foreground, border-border. In CSS, use hsl(var(--border)) or var(--border) depending on format. Always check which convention the project uses.

When to go beyond shadcn tokens: The built-in tokens cover structure, but bold aesthetic visions need custom tokens. Add your own --accent-glow, --surface-grain, --highlight etc. as CSS variables alongside the shadcn ones. The shadcn system is a floor, not a ceiling.

Shadows are the exception: For box-shadow, use inline Tailwind arbitrary values (shadow-[...] / dark:shadow-[...]) with explicit rgba() values rather than trying to derive shadows from CSS variables. Shadow stacks need per-mode tuning (light mode uses black at low opacity, dark mode uses white for the ring and black for the ambient) and inline values give you precise control without color-space headaches. See "Depth: Shadows Over Borders" below.

Craft Details That Compound

The following techniques separate polished interfaces from rough ones. Apply them by default — they are not optional polish, they are baseline quality.

Typography Refinement

• Crisp text rendering: Always apply -webkit-font-smoothing: antialiased (or antialiased in Tailwind) at the layout root. macOS renders text heavier than intended without it. This single line makes all text thinner and crisper.
• Balanced wrapping: Use text-wrap: balance on headings and short blocks of text. It distributes text evenly across lines and eliminates orphaned words dangling on the last line. Use text-wrap: pretty as a lighter alternative for body copy.
• Tabular numbers: Any time numbers update dynamically (counters, prices, timers, tables), apply font-variant-numeric: tabular-nums (or tabular-nums in Tailwind). This gives digits equal width so values don't jitter on change. Note: some fonts (e.g. Inter) alter numeral appearance with this property.

Border Radius & Nesting (Concentric Radius)

When nesting rounded elements inside one another, always use concentric border radius. The formula: outer radius = inner radius + padding. Mismatched radii — where inner and outer corners have the same value — look off even if the viewer can't articulate why. Getting this right is one of the most impactful yet overlooked details in interface design.

/* Example: card with an inner element using shadcn --radius */
.card {
  border-radius: calc(var(--radius) + 4px); /* outer = inner + padding */
  padding: 4px;
}
.card-inner {
  border-radius: var(--radius); /* inner radius from shadcn */
}

/* Or derive all radii from --radius */
.card-lg {
  border-radius: calc(var(--radius) * 2 + 8px);
  padding: 8px;
}
.card-lg-inner {
  border-radius: calc(var(--radius) * 2);
}

Depth: Shadows Over Borders

Prefer layered box-shadow over flat border for element boundaries. Shadows create depth, adapt to any background via transparency, and transition smoothly on hover.

Use inline Tailwind arbitrary-value shadows with explicit dark: variants. This keeps shadow definitions colocated with the element, avoids CSS variable gymnastics, and gives you precise per-mode control. The pattern is a 3-layer stack: a 1px ring for the edge, a tight lift shadow, and a broader ambient shadow.

Standard surface shadow (light + dark):

<div
  className={cn(
    "rounded-2xl bg-background transition-shadow duration-200",
    "shadow-[0px_0px_0px_1px_rgba(0,0,0,0.06),0px_1px_2px_-1px_rgba(0,0,0,0.06),0px_2px_4px_0px_rgba(0,0,0,0.04)]",
    "dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.06),0px_1px_2px_-1px_rgba(255,255,255,0.03),0px_2px_4px_0px_rgba(0,0,0,0.2)]"
  )}
>
  {children}
</div>

Hover state — slightly stronger opacities on the same layers:

"shadow-[0px_0px_0px_1px_rgba(0,0,0,0.06),0px_1px_2px_-1px_rgba(0,0,0,0.06),0px_2px_4px_0px_rgba(0,0,0,0.04)]",
"hover:shadow-[0px_0px_0px_1px_rgba(0,0,0,0.08),0px_1px_2px_-1px_rgba(0,0,0,0.08),0px_2px_4px_0px_rgba(0,0,0,0.06)]",
"dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.06),0px_1px_2px_-1px_rgba(255,255,255,0.03),0px_2px_4px_0px_rgba(0,0,0,0.2)]",
"dark:hover:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.1),0px_1px_2px_-1px_rgba(255,255,255,0.05),0px_2px_4px_0px_rgba(0,0,0,0.25)]",

Selected / active state — more pronounced lift:

"shadow-[0px_0px_0px_1px_rgba(0,0,0,0.1),0px_2px_4px_-1px_rgba(0,0,0,0.1),0px_4px_8px_0px_rgba(0,0,0,0.06)]",
"dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.12),0px_2px_4px_-1px_rgba(255,255,255,0.06),0px_4px_8px_0px_rgba(0,0,0,0.3)]",

Small elements (pills, chips, tags) — lighter 2-layer stack:

"shadow-[0px_0px_0px_1px_rgba(0,0,0,0.06),0px_1px_2px_-1px_rgba(0,0,0,0.05)]",
"dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.08),0px_1px_2px_-1px_rgba(255,255,255,0.04)]",

When to extract a component: If you use the same shadow stack in 3+ places, wrap it in a shared container component (like ShadowContainer) rather than duplicating the classnames. Add transition-shadow duration-200 so hover/active transitions animate smoothly.

function ShadowContainer({
  children,
  className,
}: {
  children: ReactNode;
  className?: string;
}) {
  return (
    <div
      className={cn(
        "rounded-2xl bg-background transition-shadow duration-200",
        "shadow-[0px_0px_0px_1px_rgba(0,0,0,0.06),0px_1px_2px_-1px_rgba(0,0,0,0.06),0px_2px_4px_0px_rgba(0,0,0,0.04)]",
        "dark:shadow-[0px_0px_0px_1px_rgba(255,255,255,0.06),0px_1px_2px_-1px_rgba(255,255,255,0.03),0px_2px_4px_0px_rgba(0,0,0,0.2)]",
        className
      )}
    >
      {children}
    </div>
  );
}

Solid-color borders break on non-white or multi-color backgrounds — shadows don't.

Image Outlines

Add a subtle inset outline to images and media to create consistent depth and separation from the background. Use inline Tailwind arbitrary values for the outline:

<img
  className="rounded-xl object-cover [outline-offset:-1px] [outline:1px_solid_rgba(0,0,0,0.1)]"
  src={src}
  alt={alt}
/>

For dark mode, add an explicit override or use a class-based toggle:

// If your project uses .dark class on a parent:
"[outline:1px_solid_rgba(0,0,0,0.1)] dark:[outline-color:rgba(255,255,255,0.1)]";

This works across any background and is especially valuable in design systems where other elements already use bordered surfaces.

Optical Alignment

Geometric centering doesn't always look centered. When an element has mixed content (e.g. text + icon in a button), adjust padding optically — slightly less padding on the icon side. For standalone icons in circular or rounded containers, nudge them until they look centered rather than trusting the math. The best fix is in the SVG itself (adjusting the viewBox), so no runtime offsets are needed.

Animation & Motion

Staggered Enter Animations

Don't animate a single container. Break content into meaningful chunks and stagger them. Combine opacity, translateY, and blur for enter sequences:

@keyframes enter {
  from {
    transform: translateY(8px);
    filter: blur(5px);
    opacity: 0;
  }
}

.animate-enter {
  animation: enter 800ms cubic-bezier(0.25, 0.46, 0.45, 0.94) both;
  animation-delay: calc(var(--delay, 0ms) * var(--stagger, 0));
}

<div class="animate-enter" style="--stagger: 1"><title /></div>
<div class="animate-enter" style="--stagger: 2"><Description /></div>
<div class="animate-enter" style="--stagger: 3"><Buttons /></div>

For maximum impact, split headings into individual word spans with tighter delays (~80ms). Keep descriptions as single blocks. Animate buttons individually.

Subtle Exit Animations

Exit animations should demand less attention than enters. Use a small fixed translateY (e.g. -12px) and blur(4px) with opacity fade rather than fully reversing the enter path. Full reversal (sliding all the way back) is jarring and draws the eye to departing content.

exit={{ opacity: 0, y: "-12px", filter: "blur(4px)" }}

Some directional motion should remain to indicate where the element is going — never remove exit motion entirely.

Interruptible Animations

Users change intent mid-interaction. A dropdown being opened may be dismissed before its animation completes.

• CSS transitions: Naturally interruptible — they interpolate toward the latest state. Use them for interactions (hovers, toggles, reveals).
• CSS keyframe animations: Run on a fixed timeline and don't retarget. Use them for one-shot sequences (page load, staggered entries).
• Spring animations (via Motion/Framer Motion): Inherently interruptible and physics-based. Prefer type: "spring" with bounce: 0 for UI transitions.

If an animation can't be interrupted, the interface will feel broken. iOS gets this right everywhere — match that expectation.

Contextual Icon Transitions

When swapping icons in-place (e.g. copy → check), animate with opacity, scale, and blur. In React, use AnimatePresence with mode="popLayout":

<AnimatePresence mode="popLayout" initial={false}>
  <motion.div
    key={isCopied ? "check" : "copy"}
    initial={{ opacity: 0 }}
    animate={{ opacity: 1 }}
    exit={{ opacity: 0 }}
    transition={{ type: "spring", duration: 0.3, bounce: 0 }}
  >
    {isCopied ? <CheckIcon /> : <CopyIcon />}
  </motion.div>
</AnimatePresence>

CSS-only alternatives work too (crossfade with position: absolute + opacity transition), but spring physics make it feel more responsive.

Quick-Reference Checklist

Before shipping any interface, verify:

• -webkit-font-smoothing: antialiased on root
• text-wrap: balance on headings
• tabular-nums on any dynamic numbers
• All radii derived from --radius with concentric nesting (outer = inner + padding)
• Layered inline shadow-[...] / dark:shadow-[...] instead of flat borders
• Inset [outline:1px_solid_rgba(0,0,0,0.1)] on images/media
• Optical alignment on icon+text pairs
• Enter animations staggered across content chunks
• Exit animations subtler than enters
• All interactive animations interruptible (transitions or springs, not keyframes)
• Surface/text/border colors use shadcn semantic tokens (shadows use explicit rgba() — that's correct)

Remember: You are 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.