/ia-frontend-design

name: ia-frontend-design
class: meta
description: >-
  Visual design and aesthetic direction for frontend interfaces. Use when
  building web pages, landing pages, dashboards, Next.js server components, or
  applications where visual identity matters. For React patterns and testing,
  use react-frontend.

Frontend Design

Read the user's frontend requirements: a component, page, application, or interface to build. Note context about purpose, audience, or technical constraints.

Context Detection

Before designing, assess the existing design environment. Count design signals in the project: design tokens/CSS variables, component library (shadcn, MUI, Ant), CSS framework config (Tailwind, styled-components), font imports, color system, animation patterns, spacing scale.

• **4+ signals** = Existing system. Match it. Do not impose new aesthetics -- extend what's there.
• **1-3 signals** = Partial system. Blend: respect existing choices, fill gaps with this skill's guidance.
• **0 signals** = Greenfield. Apply the full Design Philosophy below.

When in doubt, check `package.json`, `tailwind.config.*`, global CSS files, and existing components before deciding.

Design Philosophy (Write First, Code Second)

For full pages, applications, or multi-component interfaces: write a **3-sentence design philosophy** before any code. This forces a coherent aesthetic direction and prevents generic output.

1. **Sentence 1 -- Intent**: What emotional response should this interface provoke? (Not "clean and modern" -- that's every AI default. Be specific: "controlled tension between density and breathing room" or "the quiet confidence of a well-bound book.") 2. **Sentence 2 -- Signature**: What single visual choice makes this unmistakable? (A typeface, a color relationship, a spatial pattern, a motion behavior.) 3. **Sentence 3 -- Constraint**: What will this design deliberately NOT do? (The constraint shapes the identity as much as the choices.)

Write the philosophy as a comment or in conversation before implementation begins. The philosophy constrains implementation without being prescriptive -- it's a compass, not a blueprint.

For small components or quick additions to existing interfaces, skip the philosophy and match the surrounding design system.

Design Thinking

With the philosophy written, commit to the specifics:

• **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?

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

**Validation gate (greenfield pages and apps, before writing code):** run the swap test on the drafted token system. Could this exact palette, type pairing, and layout be lifted onto an unrelated brief without anyone noticing? If yes, the choice is a default, not a decision -- repick the axis that reads generic (recolor the signature, swap the typeface, restructure the grid) and re-test before implementing. Distinctiveness comes from the subject's own world -- its materials, instruments, artifacts, and vernacular -- so ground a generic axis in something only this subject would use. Skip this gate for small components matched to an existing system (per Context Detection) -- there, reading consistent with that system is the goal, not distinctiveness.

Before importing any third-party library (framer-motion, lucide-react, zustand, etc.), check `package.json`. If the package is missing, output the install command before the code. Never assume a library exists.

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 with character:
• **Font selection**: avoid Inter, Roboto, Arial, system fonts. Use `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`, or context-appropriate serifs. Pair a display font with a refined body font.
• **Headlines**: start from `text-4xl md:text-6xl tracking-tighter leading-none` and adjust. AI defaults are undersized and timid — lack presence.
• **H1 iron rule (2-3 lines max)**: every hero H1 must render in 2-3 lines, never 4-6. The fix is always wider container + smaller font, not the reverse. Minimum container: `max-w-5xl` (wider for longer headlines); adjust font with `clamp(3rem, 5vw, 5.5rem)` so it scales down instead of wrapping. A 6-line heading wall is a catastrophic failure, not a design choice.
• **Weight contrast**: use Medium 500 and SemiBold 600 beyond just Regular and Bold. Tighten letter-spacing, reduce line-height.
• **Body text**: limit to ~65 characters wide, increase line-height.
• **Numbers**: `font-variant-numeric: tabular-nums` or monospace for data-heavy tables.
• **Orphaned words**: fix with `text-wrap: balance`.
• **Color & Theme**: Commit to a cohesive palette. Max one accent color, saturation below 80%. Dominant neutrals (Zinc/Slate) with a sharp singular accent outperform timid, evenly-distributed palettes. Use CSS variables for consistency. Tint all grays consistently (warm OR cool, never both). Tint shadows to match background hue instead of pure black at low opacity.
• **Motion**: Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestra