| name | variant-design |
| description | AI-driven interactive design generation and style analysis with Impeccable design system. Two modes — (1) Generate: 3 distinct, fully-animated design variations from a prompt with scroll reveals, micro-interactions, animated charts, and functional JS patterns; (2) Analyze: audit existing sites for style consistency, extract design tokens, generate style-matched new pages, and produce migration plans. Built-in scenario materials (10 domains), design system references (typography, color, spatial, motion, micro-interactions, interaction, responsive, UX writing, style audit), interactive pattern library, and anti-AI-slop quality gates. Triggers on: "design options for X", "show me variations", "vary this design", "audit", "analyze my site", "check consistency", "match this style", "extract tokens", "new page matching my site", "migrate", "add motion", "dramatize", "make interactive". |
Variant Design
Solve the blank canvas problem. Prompt → 3 fully-formed distinct designs → vary → export.
About
Inspired by the Variant design community — a space where designers share divergent takes on the same brief. This skill brings that practice into Claude Code: every prompt yields three designs that feel like they came from different studios, then lets you iterate with one-word actions.
Built on the Impeccable design system — a comprehensive set of design references covering typography, color theory, spatial design, motion, interaction patterns, responsive design, and UX writing. Every design decision is grounded in these principles.
Supports: Interactive HTML (default) · React + Framer Motion · 10 domain reference libraries · 39 palettes · design system references · micro-interaction library · interactive pattern library · style audit & token extraction · variation actions
CLI Workflow (Claude Code)
This skill runs inside Claude Code — a terminal. Design decisions must account for the fact that the user cannot see the output without opening a browser. Every step of the workflow should minimize friction between "idea" and "eyes on pixels."
Output Convention
File naming: variant-[scenario]-[variation].html (e.g., variant-dashboard-A.html)
Output directory: Write to ./variant-output/ in the current working directory. Create the directory if it doesn't exist. This keeps design files separate from project source code.
variant-output/
├── variant-dashboard-A.html
├── variant-dashboard-B.html
├── variant-dashboard-C.html
└── tokens/
└── dashboard-A-tokens.css (when user extracts tokens)
Iteration files: On variation actions, overwrite the same file (e.g., variant-dashboard-A.html) rather than creating variant-dashboard-A-v2.html. The user is iterating on one design, not collecting versions. Git handles history.
Auto-Preview
After every file write, immediately open it in the user's default browser:
open variant-output/variant-dashboard-A.html
xdg-open variant-output/variant-dashboard-A.html
This is non-negotiable. The user should never have to manually find and open the file. When iterating (Vary subtle, Remix colors, etc.), the browser tab auto-refreshes because the file is overwritten — just re-run open to bring it to focus.
Live Preview Server (Optional)
If the user asks for live preview or says "watch mode", start a lightweight file server with auto-reload:
cd variant-output && python3 -c "
import http.server, socketserver, os, time, threading
class ReloadHandler(http.server.SimpleHTTPRequestHandler):
def end_headers(self):
self.send_header('Cache-Control', 'no-store')
super().end_headers()
def do_GET(self):
if self.path == '/_poll':
self.send_response(200)
self.send_header('Content-type', 'text/plain')
self.end_headers()
self.wfile.write(str(os.path.getmtime('.')).encode())
return
super().do_GET()
with socketserver.TCPServer(('', 3333), ReloadHandler) as httpd:
print('Preview: http://localhost:3333')
httpd.serve_forever()
" &
Then inject a tiny auto-reload script at the bottom of every generated HTML:
<script>
(async function poll() {
try {
const r = await fetch('/_poll');
const t = await r.text();
if (window._lastMod && t !== window._lastMod) location.reload();
window._lastMod = t;
} catch(e) {}
setTimeout(poll, 800);
})();
</script>
Only include this script when the preview server is running. Remove it on export.
Compact CLI Output
Terminal space is precious. Keep text responses short and structured:
On initial generation (3 variations):
✦ Detected: coffee brand landing page → loading food-beverage.md + micro-interactions.md
A — Terroir Warm Fraunces + Instrument Sans Minimal/Editorial
B — Espresso Dark DM Serif Display + DM Sans Dark/Premium
C — Fresh Market Crimson Pro + Plus Jakarta Warm/Human
Interactions: scroll reveal, counter animation, card lift, filter chips, lightbox
Files written:
variant-output/variant-coffee-A.html ← opened in browser
variant-output/variant-coffee-B.html
variant-output/variant-coffee-C.html
Pick a variation to iterate, or an action:
Reshape — Vary strong · Distill · Shuffle layout · Change style
Tune — Vary subtle · Remix colors · Mix (A+B)
Animate — Add motion · Dramatize · Make interactive
Refine — Polish · Critique · See other views
Export — Extract tokens
On iteration:
✦ Variation A — Vary subtle · iteration 2
Changed: tightened spacing to 4pt grid, added tabular-nums on stats,
hover now lifts 4px→6px with shadow, scroll stagger 60ms→80ms
variant-output/variant-coffee-A.html ← updated & opened
Next action?
Never dump the full HTML in the chat. Write to file, open in browser, show a 2-3 line summary of what changed. The user reads code in their editor, not in the terminal.
Quick Triggers
Support shorthand prompts for fast iteration in the terminal:
| User types | Expands to |
|---|
A vary strong | Apply "Vary strong" to Variation A |
B remix colors | Apply "Remix colors" to Variation B |
C → mobile | Show Variation C as mobile viewport |
pick A | Select Variation A as the winner, archive B and C |
A + B colors | Mix: A's layout with B's color palette |
tokens A | Extract design tokens from Variation A to CSS file |
open B | Re-open Variation B in browser |
dark mode A | Generate dark ↔ light toggle variant of A |
compare | Open all 3 variations side-by-side (writes a comparison HTML) |
Comparison View
When the user says "compare" or wants to see all variations together, generate a single variant-output/_compare.html that displays all 3 side-by-side in iframes:
<style>
body { margin:0; display:grid; grid-template-columns:1fr 1fr 1fr; height:100vh; gap:2px; background:#111; }
iframe { width:100%; height:100%; border:none; }
.label { position:absolute; top:8px; left:12px; background:#111; color:#fff; padding:4px 12px;
font:12px/1 monospace; border-radius:4px; z-index:10; }
.frame { position:relative; }
</style>
<div class="frame"><span class="label">A</span><iframe src="variant-coffee-A.html"></iframe></div>
<div class="frame"><span class="label">B</span><iframe src="variant-coffee-B.html"></iframe></div>
<div class="frame"><span class="label">C</span><iframe src="variant-coffee-C.html"></iframe></div>
Framework Export
When the user says "export to [framework]", transform the winning variation into the target structure:
| Target | Action |
|---|
export to next | Create app/page.tsx + app/globals.css with tokens + public/ for images |
export to vite | Create src/App.jsx + src/index.css + index.html |
export to astro | Create src/pages/index.astro + src/styles/tokens.css |
export to static | Clean HTML (remove dev scripts), optimize images, inline critical CSS |
Always ask which variation to export if the user hasn't picked one yet.
Clipboard Mode
If the user says "copy" or "clipboard", copy the HTML to system clipboard instead of (or in addition to) writing the file:
cat variant-output/variant-coffee-A.html | pbcopy
Useful for pasting into CodePen, Claude.ai artifacts, or other tools.
Project Context Initialization
On first use in a project, gather design context to ground all future generations. Ask the user:
- Users & Purpose — Who uses this? What problem does it solve? What's the core task?
- Brand & Personality — Existing brand colors? Tone (playful / serious / technical / warm)? Any sites you admire?
- Aesthetic Preferences — Light or dark? Minimal or dense? Any direction from the aesthetic table you're drawn to?
- Constraints — Framework requirements? Accessibility standards beyond baseline? Target devices?
If the user can't answer, infer from their codebase: scan for existing color variables, font imports, component patterns, and README/brand docs. Confirm inferences before proceeding.
Persist context as a comment block at the top of generated files or in the conversation — reference it in every subsequent generation to ensure consistency across variations.
Site Analysis Mode
When the user points to existing code (file paths, a directory, or says "analyze/audit/check my site"), switch from generation mode to analysis mode. Load references/design-system/style-audit.md for the full methodology.
Triggers
| User says | Action |
|---|
| "analyze my site" / "audit this" / "check consistency" | Full style audit → report |
| "match this style" / "follow existing design" / "extend my site" | Extract tokens → generate matching pages |
| "extract tokens" (on existing files, not a generated variation) | Token extraction → CSS custom properties file |
| "what's wrong with this design" / "review my CSS" | Style consistency check → findings list |
| "migrate" / "consolidate" / "clean up" | Audit → token generation → migration plan |
| "add a [page] to my site" / "new page matching my existing design" | Extract → match → generate |
Analysis Workflow
Step 1: Scan — Read the files the user points to. If no specific files given, scan for:
find . -name "*.html" -o -name "*.css" -o -name "*.tsx" -o -name "*.jsx" \
-o -name "*.vue" -o -name "*.svelte" | head -20
Step 2: Extract — Pull all design primitives following the Token Extraction schema in style-audit.md: colors, typography, spacing, components, transitions. Group by semantic role.
Step 3: Detect — Run all consistency checks from style-audit.md Section 2. For each finding, record severity (error/warning/info), the specific values, file locations, and a concrete fix.
Step 4: Report — Present findings using the compact terminal format from style-audit.md Section 3. Score out of 100. List priority fixes.
Step 5: Act — Based on what the user wants:
- Audit only: Stop after the report. Offer to generate a token file or migration plan.
- Extract tokens: Generate a
tokens.css file consolidating all values (see style-audit.md Section 4).
- Generate matching page: Lock extracted tokens as constraints, generate new pages that match (see below).
- Migration plan: Generate phased checklist for consolidating the codebase (see
style-audit.md Section 6).
Style-Matched Generation
When generating new pages for an existing project, the workflow changes:
- Extract first — Always analyze existing code before generating. Never guess the style.
- Lock tokens — All generated code must use
var(--*) referencing the existing token system. If no token system exists, generate one first and get user approval.
- Match patterns — Study existing component shapes (card radius, shadow, padding), interaction patterns (transition durations, hover effects), layout patterns (container width, grid), and naming conventions (BEM, Tailwind, CSS modules).
- Show diff from existing — In the Summary Card, note which tokens/patterns are being reused vs. which are new additions.
- Flag deviations — If the design system principles (from Impeccable) conflict with the existing style, flag it: "Your existing buttons have no hover state — I've added one following your color palette. OK?"
Summary Card for style-matched generation:
✦ New page: /pricing — matching existing site style
Reusing: --bg, --surface, --card, --border, --text, --muted, --accent
Reusing: Plus Jakarta Sans 400/600, 4 font sizes, 8px grid
Reusing: .card (24px padding, 8px radius, 1px border)
Reusing: .btn (100px radius, 200ms transition)
New additions:
+ Pricing toggle (monthly/annual) — uses existing .btn style
+ FAQ accordion — uses existing .card + new grid height animation
+ Comparison table — new component, follows existing spacing/color
File: variant-output/pricing-matched.html ← opened in browser
Quick Triggers for Analysis
| User types | Action |
|---|
audit | Full style audit on current project |
audit src/styles/ | Audit specific directory |
tokens | Extract tokens from existing code → CSS file |
match | Enter style-matched generation mode |
new page pricing | Generate /pricing page matching existing style |
migrate | Generate migration plan for token consolidation |
compare old new | Side-by-side: existing page vs. redesigned version |
Smart Prompt Handling
Before generating, apply these three rules in order:
- Confirm scenario detection. State the detected scenario and aesthetic direction. Ask the user to confirm before proceeding: "I'm reading this as a [scenario] with [direction] vibes — correct?"
- Resolve vague prompts — max 2 questions. If the prompt lacks enough signal to differentiate 3 variations (e.g. "design something cool"), ask at most 2 clarifying questions. Focus on: (a) what it's for / who uses it, (b) any aesthetic leaning. If the user says "surprise me," pick 3 maximally divergent directions and proceed.
- Never generate blind. Do not produce code until you have either (a) user confirmation of the scenario, or (b) answers to your clarifying questions, or (c) an explicit "surprise me."
Scenario Detection → Load Reference
Identify the scenario and load the corresponding reference file before designing:
| User asks about... | Also matches | Load |
|---|
| Dashboard, analytics, metrics, monitoring, data viz | 后台, admin panel, management system, backoffice, CRM, internal tool | references/dashboard.md |
| Editorial, magazine, journalism, news, article | blog post, report, white paper, newsletter | references/editorial.md |
| Landing page, SaaS, product page, startup, B2B | website, 官网, corporate site, personal site, portfolio, agency | references/saas.md |
| E-commerce, shopping, product, fintech card, consumer | store, shop, marketplace, cart, checkout | references/ecommerce.md |
| Education, learning app, quiz, language, science | lesson, flashcard, tutorial, training, course | references/education.md |
| Generative art, music tool, 3D, creative tool, synthesizer | tool, studio, editor, canvas, sequencer, DAW | references/creative.md |
| Mobile app, iOS, Android, onboarding, home screen | app, 应用, 界面, UI screen | references/mobile.md |
| Portfolio, personal site, showcase, case study | designer portfolio, developer site, freelancer, agency, 作品集 | references/portfolio.md |
| Restaurant, recipe, food, coffee, bakery, menu | café, bar, cocktail, wine, tea, meal planning, 餐厅, 菜单 | references/food-beverage.md |
| Fashion, clothing, beauty, lookbook, interior design | streetwear, luxury brand, skincare, cosmetics, furniture, 时尚, 服装 | references/fashion.md |
| Unsure / general | | Use aesthetic directions table below + references/palettes.md |
Always also load the relevant design system references from references/design-system/ based on what matters most for the design:
| Design challenge | Load |
|---|
| Font selection, type scale, hierarchy | references/design-system/typography.md |
| Color palette, dark mode, contrast | references/design-system/color-and-contrast.md |
| Layout, spacing, grids, visual hierarchy | references/design-system/spatial-design.md |
| Animations, transitions, loading states | references/design-system/motion-design.md |
| Micro-interactions, scroll reveals, hover effects | references/design-system/micro-interactions.md |
| Functional interactions (filter, drag, charts, forms) | references/interactive-patterns.md |
| Forms, states, focus, keyboard nav | references/design-system/interaction-design.md |
| Style audit, token extraction, consistency checks | references/design-system/style-audit.md |
| Mobile-first, breakpoints, fluid design | references/design-system/responsive-design.md |
| Labels, errors, empty states, microcopy | references/design-system/ux-writing.md |
For initial generation, load at minimum: typography, color-and-contrast, spatial-design, and micro-interactions. Load interactive-patterns when the design involves filtering, forms, charts, galleries, or drag-and-drop. Load others as the design demands.
Core Workflow
1. Parse → Detect → Load
Identify scenario, load domain reference file + relevant design system references, pick 3 starter prompts and palettes. Study the Real Community Examples for composition patterns and what makes each design work — extract the principle, not the surface style.
2. Generate 3 Distinct Variations
Each variation = a different studio's interpretation. Never two in the same direction.
Universal aesthetic directions:
| Direction | Feel | Signature |
|---|
| Minimal / Editorial | Type-driven, generous space | One strong font, minimal color |
| Bold / Expressive | High contrast, graphic | Dominant color block |
| Dark / Premium | Moody, atmospheric | Deep bg, elevated surfaces (not shadows) |
| Warm / Human | Rounded, approachable | Soft palette, organic forms |
| Data / Technical | Dense, systematic | Grid, monospace, tight |
| Neo-brutalist | Raw, unconventional | Bold outlines, broken grid |
| Luxury / Silence | Maximum negative space | One image, sparse text |
For each variation, define before coding:
- Starter prompt (from reference or custom)
- Color palette (from reference or
palettes.md) — use OKLCH for perceptually uniform colors where possible
- Typography: display font + body font (see banned fonts list below)
- Layout pattern (from reference) — consult
spatial-design.md for grid and hierarchy principles
- Motion strategy — consult
motion-design.md for timing and easing
- Interaction plan — which micro-interactions and interactive patterns from
micro-interactions.md and interactive-patterns.md to include (minimum 3 micro-interactions + domain-specific patterns)
- One signature detail that makes this variation unforgettable
3. Implement & Present
Working code — HTML (default) or React. Real content, no lorem ipsum. Visually complete.
Write each variation to a separate file following the CLI Output Convention (see "CLI Workflow" section). Never dump full HTML into the chat — write to variant-output/ and open in browser.
Present a compact Summary Card in the terminal for each variation:
A — [Name] · [Direction] · [Palette] · [Fonts]
Layout: [pattern] · Signature: [detail] · Interactions: [list]
Then show the file paths and open the first variation in the browser. The user reads the design in the browser, not in the terminal.
4. AI Slop Test (Quality Gate)
Before presenting, run this check on each variation:
If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, redesign.
A distinctive interface should make someone ask "how was this made?" not "which AI made this?" Review the Anti-Patterns table below — they are the fingerprints of AI-generated work.
Interactivity gate: Before presenting, also verify: Does this page move? Scroll down — do elements animate in? Hover a card — does it respond? Click a button — does it give feedback? If anything is dead on interaction, fix it before presenting.
After passing, show a one-line confidence signal: e.g. "Passed: distinctive fonts, OKLCH palette, tinted neutrals, WCAG AA, scroll reveals, counter animation, card hover lift, no AI slop patterns detected."
5. Offer Variation Actions
After presenting, always offer grouped by intent:
Which direction resonates? Pick an action:
Reshape — Vary strong · Distill · Shuffle layout · Change style
Tune — Vary subtle · Remix colors · Mix (e.g. "Mix A + B")
Animate — Add motion · Dramatize · Make interactive
Refine — Polish · Critique · See other views
Export — Extract tokens
Can't decide? Say "Mix A + B" or "A's layout + C's colors".
Variation Action Definitions
Vary strong
Amplify current direction to maximum. More contrast, stronger type, bolder color, more dramatic composition. Consult references/design-system/typography.md for scale ratios and references/design-system/color-and-contrast.md for high-contrast palette construction.
Before → After example:
- Body text 16px, heading 32px → Body 15px, heading 72px (ratio 1.25 → 1.5+)
- Accent used on buttons only → Accent dominates hero section, bleeds into nav
- Subtle 200ms fade-in → Dramatic 600ms staggered reveal with scale transform
Vary subtle
Tighten spacing, refine hierarchy, soften where needed. Same direction, higher craft. Focus on vertical rhythm, optical alignment, and micro-interactions per references/design-system/spatial-design.md and references/design-system/motion-design.md.
Before → After example:
- Inconsistent padding (16/20/24px) → Locked to 4pt grid (16/24/32px)
- Generic hover (opacity change) → Contextual hover (card lifts 2px, button darkens accent)
- Missing OpenType →
tabular-nums on data, font-kerning: normal on headlines
Distill
Strip the design to its absolute essence. Inspired by the Impeccable distill philosophy — ruthless simplification reveals what truly matters.
Process:
- Identify the single core purpose of the interface
- For each element, ask: "Does removing this break the core purpose?" If no, remove it.
- Simplify across all dimensions:
- Information: Reduce visible options, use progressive disclosure (
<details>, hover reveals)
- Visual: Fewer colors (aim for 2–3 total), fewer type sizes, remove decorative elements
- Layout: Collapse sections, merge related content, eliminate redundant containers
- Interaction: Fewer clicks to complete the primary task, remove confirmation steps where undo works
- Content: Shorter headlines, tighter copy, remove introductory paragraphs that restate the heading
- Verify: Can a new user complete the core task faster? If not, you removed the wrong things.
Before → After example:
- 5-section landing page → 2 sections: hero with value prop + single CTA
- Dashboard with 12 metric cards → 3 key metrics large + "Show all" expandable
- Nav with 8 items → 4 primary + overflow menu
Change style
Extract structure/layout DNA, replace entire visual language with a different direction from the table above.
Remix colors
Keep all shapes, type, layout. Generate 3 palettes using OKLCH color space (per references/design-system/color-and-contrast.md):
- Analogous to current — shift hue ±30°, adjust chroma
- Complementary contrast — opposite hue, rebalanced lightness
- Unexpected/left-field — completely different mood
Always tint neutrals toward the brand hue. Never use pure gray, pure black (#000), or pure white (#fff).
Before → After example (palette 3, unexpected):
- Dark indigo tech dashboard → Warm cream editorial palette with rust accent
- All neutrals shift from cool blue-gray → warm stone-tinted
Add motion
Layer additional micro-interactions and animations onto the current design. Consult references/design-system/micro-interactions.md for the full pattern library.
Process:
- Audit current interactions — list what already moves and what's dead
- Add missing baseline: scroll reveals on all sections, card hover lifts, button press feedback
- Add 2-3 domain-appropriate enhancements from the "Picking Micro-Interactions by Domain" table
- Wire up any static data displays: counter animations for numbers, bar/donut animations for charts
- Verify reduced motion fallbacks exist for every new animation
Before → After example:
- Static hero → Staggered entrance (title 100ms → subtitle 250ms → CTA 400ms → image 300ms)
- Cards appear instantly → Scroll-triggered fade-up with 80ms stagger
- Numbers display as-is → Count up from 0 with easeOutExpo on scroll into view
- Image gallery static → Lightbox on click with keyboard navigation
Dramatize
Push existing interactions to their cinematic maximum. Not just "add hover" — make the page feel like a directed experience.
Process:
- Replace subtle scroll reveals with more expressive entrances (word-by-word text reveal, curtain reveal, scale-from-zero)
- Add parallax layers to hero sections (foreground moves faster than background)
- Upgrade hover effects: card lift → tilt-3D, link underline → magnetic cursor pull
- Add page-level choreography: scroll progress bar, sticky header morph, section transitions
- Include a "hero moment" — one interaction that makes the user pause (e.g., counter hitting a big number, image comparison slider, infinite marquee of client logos)
Before → After example:
- Simple fade-in on scroll → Staggered word reveal + parallax background + scroll progress bar
- Card hover lifts 4px → Card tilts toward cursor in 3D perspective with glow
- Static hero → Curtain reveal on page load + magnetic CTA button + background parallax
Make interactive
Add functional interaction patterns that turn the design from a visual into a working prototype. Consult references/interactive-patterns.md for full implementations.
Process:
- Identify what should be functional: Is there a form? Add validation + multi-step. Gallery? Add lightbox. Products? Add filtering. Data? Add live charts.
- Add the most impactful interaction from
interactive-patterns.md for this domain (see "Picking Patterns by Domain" table)
- Wire up navigation: tabs work, accordions expand, drawers slide, modals open with proper focus trap
- Add data interactions: sorting, filtering, search — with animated transitions between states
- Add feedback loops: toast on action, copy-to-clipboard confirmation, form submission success state
Before → After example:
- Static product grid → Filter by category with animated show/hide + sort by price with FLIP animation
- Image gallery → Lightbox with keyboard nav (←→ Esc) + zoom on hover + dot indicators
- Contact form → Multi-step with progress bar, floating labels, real-time validation, submit→loading→success
- Dashboard metrics → Animated bar chart on scroll, donut chart that draws in, sparklines that trace, flash-on-update for live data
Shuffle layout
Same content + style. Rearrange structure: try full-bleed → asymmetric grid → editorial columns → card masonry. Consult references/design-system/spatial-design.md for grid systems and visual hierarchy principles.
Before → After example:
- Centered hero + 3-column grid → Full-bleed left-aligned hero + asymmetric 2-column with oversized feature
Polish
Apply Impeccable design system refinements systematically:
- Typography (
references/design-system/typography.md): vertical rhythm, modular scale, OpenType features (tabular-nums for data, proper fractions), font-display: swap, size-adjust fallback metrics
- Spatial (
references/design-system/spatial-design.md): squint test, hierarchy through multiple dimensions, optical alignment (text negative margin -0.05em, icon center offsets)
- Interaction (
references/design-system/interaction-design.md): all 8 interactive states (default/hover/focus/active/disabled/loading/error/success), focus-visible rings, proper form design (visible labels, blur validation, aria-describedby errors)
- Motion (
references/design-system/motion-design.md): 100/300/500 rule, ease-out-expo for enters, exit at 75% of enter duration, staggered animations with CSS custom properties
- UX Writing (
references/design-system/ux-writing.md): specific button labels (verb + object), error formula (what → why → fix), empty states that teach the interface, link text with standalone meaning
- Clarify copy: Scan all visible text — replace vague labels with specific ones, remove redundant intros, ensure every word earns its place. "Submit" → "Create account". "Error" → "Email needs to be in name@example.com format."
Critique
Systematic audit against design system principles. Score each dimension and provide specific fixes:
- Typography: Is hierarchy clear? Scale ratio consistent? Fonts distinctive? Vertical rhythm locked?
- Color: WCAG contrast passing? Neutrals tinted? 60-30-10 balance? No pure black/white?
- Layout: Passes squint test? Varied spacing creates rhythm? Cards justified? No nested cards?
- Motion: Durations appropriate (100/300/500)? Ease-out for enters? Reduced motion respected? Only transform+opacity animated?
- Interaction: All 8 states designed? Focus rings present? Touch targets ≥44px? Skeleton > spinner?
- Responsive: Mobile-first? Content-driven breakpoints? Input method detected (
pointer/hover)? Safe areas?
- Writing: Specific button labels? Helpful errors (what/why/fix)? Empty states that teach? No redundant copy?
- Resilience: Text truncation handled? Long content graceful? Loading/error states present? i18n-ready spacing?
Extract tokens
Export the design's token system in the requested format:
CSS Custom Properties (default):
:root {
--blue-500: oklch(55% 0.2 260);
--stone-100: oklch(95% 0.01 60);
--color-primary: var(--blue-500);
--color-surface: var(--stone-100);
--font-display: 'Fraunces', serif;
--font-body: 'Instrument Sans', sans-serif;
--text-xs: clamp(0.7rem, 0.65rem + 0.25vw, 0.75rem);
--text-base: clamp(0.95rem, 0.9rem + 0.25vw, 1.0625rem);
--text-xl: clamp(1.5rem, 1rem + 2.5vw, 3rem);
--space-xs: 4px; --space-sm: 8px; --space-md: 16px;
--space-lg: 24px; --space-xl: 48px; --space-2xl: 96px;
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
--duration-instant: 100ms;
--duration-fast: 200ms;
--duration-normal: 350ms;
}
JSON (for design tools / Figma): Same structure as flat key-value JSON.
Tailwind config: Extend theme with colors, fontFamily, spacing, transitionTimingFunction.
See other views
Render additional views with full design system compliance:
-
Empty state — not just "No items." Design as an onboarding moment:
- Acknowledge briefly ("No projects yet")
- Explain the value of filling it ("Create your first project to start tracking progress")
- Provide a clear primary action (prominent CTA button)
- Add visual interest (illustration, icon, or subtle pattern — never a sad face)
- If applicable, show a preview of what it will look like when populated
-
Data-filled state — realistic volume: 3–7 items for lists, 6–12 months of data for charts, edge cases included (one very long name, one empty optional field)
-
Mobile viewport — not a shrunk desktop. Per references/design-system/responsive-design.md:
- Rethink for thumb zones (primary actions bottom-right for right-handed)
- Touch targets ≥44px with padding
- Navigation collapses to hamburger + drawer or bottom tab bar
- Tables transform to cards with
data-label attributes
- Use
@media (pointer: coarse) for larger tap areas
-
Dark ↔ Light toggle — per references/design-system/color-and-contrast.md:
- Dark mode uses lighter surfaces for depth (no shadows)
- Desaturate accent colors slightly for dark backgrounds
- Reduce font weight (light text on dark appears heavier)
- Never pure black (#000) background — use oklch(12-18% ...) tinted
-
Onboarding flow — per Impeccable onboard principles:
- Show Don't Tell: inline demos > text instructions
- Make It Optional: skip button always visible, no forced tours
- Time to Value: reach the "aha moment" in ≤3 steps
- Context Over Ceremony: teach at the moment of need, not upfront
- Respect User Intelligence: no condescending language, allow power-user shortcuts
-
Hover / active / focus states — all interactive elements with visible state changes
Mix
Combine two variations into one. Accepts forms like "Mix A + B" or "A's layout + C's colors."
Process:
- Use the first-named variation as the structural base (layout, hierarchy, component structure)
- Layer the second variation's visual language (palette, typography, motion, signature details)
- When elements conflict (e.g. both have a distinctive nav pattern), explicitly state the trade-off and pick the one that better serves the content
- Label result as "Mix [A+B]" and present with a Summary Card showing which parts came from where
Variation Loop
Track iteration count internally (reset per variation). After any variation action:
- Overwrite the same file (e.g.
variant-output/variant-coffee-A.html) — don't create new files for iterations
- Re-open in browser — run
open / xdg-open so the user sees the update immediately
- Show a 2-3 line diff summary in the terminal — what changed, not the full code
- Offer the grouped action menu again — the loop never ends until the user moves on
- If the user has iterated 3+ times on the same direction, proactively suggest: "Want to branch? I can apply this to one of the other variations."
- At iteration 2: Ask a direction-check — "Still feeling this direction, or want to pivot?"
- At iteration 4: Show a change summary — "Over 4 rounds: [list key changes]. Want to keep refining or export?"
- At iteration 5+: Suggest convergence — "You've refined this 5 times — it's looking solid. Ready to export, or one more pass?"
Design Principles
Grounded in the Impeccable design system. Consult individual references for deep implementation guidance.
Content & Intent
- Real content wins. Plausible headlines, real data values, actual copy. Makes designs feel alive.
- Commit fully. Half-executed aesthetics look worse than simple ones. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
- Never converge. If A is dark, B cannot also be dark. Each must feel like a different studio.
- Match type to domain. Don't default to generic app UI — load the right reference.
Typography (→ references/design-system/typography.md)
- Distinctive display + reliable body. Use Google Fonts
@import, always specify weights.
- Banned display fonts: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, system-ui, system defaults.
- Better alternatives: Instrument Sans, Plus Jakarta Sans, Outfit, Onest, Figtree, Urbanist, Fraunces, Newsreader, Lora.
- Modular scale: Use fewer sizes with more contrast (5-size system: xs/sm/base/lg/xl+). Popular ratios: 1.25, 1.333, 1.5.
- Fluid type: Use
clamp(min, preferred, max) for responsive sizing. Not for buttons/labels.
- Vertical rhythm: Line-height as base unit for all vertical spacing.
- OpenType features:
tabular-nums for data tables, diagonal-fractions for recipes, all-small-caps for abbreviations.
- Never mix more than 2 typefaces. One well-chosen family in multiple weights often suffices.
Color (→ references/design-system/color-and-contrast.md)
- Use OKLCH for perceptually uniform palettes. Reduce chroma as you approach white/black.
- Tint your neutrals toward the brand hue — even chroma 0.01 creates subconscious cohesion.
- 60-30-10 rule: 60% neutral, 30% secondary, 10% accent. Accent colors work because they're rare.
- Never pure black/white. Always tint. Pure black/white never appears in nature.
- Never gray on color. Gray text on colored backgrounds looks washed out — use a darker shade of the background color.
- Two-layer tokens: Primitive (
--blue-500) + semantic (--color-primary: var(--blue-500)). Dark mode redefines semantic only.
Layout & Space (→ references/design-system/spatial-design.md)
- 4pt base grid (not 8pt — too coarse). Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
- Use
gap instead of margins for sibling spacing.
- Squint test: Blur your eyes — can you identify the most important element, second most, and clear groupings?
- Hierarchy through multiple dimensions: Combine size, weight, color, position, and space (2-3 at once).
- Cards are not required. Spacing and alignment create grouping naturally. Never nest cards inside cards.
- Container queries for component-level responsiveness.
Motion (→ references/design-system/motion-design.md)
- 100/300/500 rule: 100-150ms instant feedback, 200-300ms state changes, 300-500ms layout changes, 500-800ms entrances.
- Ease-out-expo (
cubic-bezier(0.16, 1, 0.3, 1)) for elements entering. Exit at 75% of enter duration.
- Only animate
transform and opacity. For height: use grid-template-rows: 0fr → 1fr.
- Stagger with CSS custom properties:
animation-delay: calc(var(--i) * 50ms). Cap total stagger time.
- Reduced motion is not optional. Always include
@media (prefers-reduced-motion: reduce).
- Never bounce/elastic easing. Real objects decelerate smoothly.
Interaction (→ references/design-system/interaction-design.md)
- Design all 8 states: default, hover, focus, active, disabled, loading, error, success.
- Focus rings: Never
outline: none without replacement. Use :focus-visible.
- Forms: Visible labels (not just placeholders), validate on blur, errors below fields with
aria-describedby.
- Skeleton screens > spinners. Optimistic UI for low-stakes actions.
- Undo > confirm dialogs. Users click through confirmations mindlessly.
- Modals only as last resort. Prefer native
<dialog> when needed. Consider Popover API for non-modal overlays.
UX Writing (→ references/design-system/ux-writing.md)
- Specific button labels: "Save changes" not "OK", "Create account" not "Submit".
- Error formula: What happened → Why → How to fix. Never blame the user.
- Empty states are opportunities: Acknowledge, explain value, provide clear action.
- Link text must standalone: "View pricing plans" not "Click here".
Code Export
- Interactive HTML: Single-file, embedded CSS + JavaScript. Alive by default. Default.
- React: Functional components, Tailwind or CSS modules — state assumptions upfront.
Interactive HTML Output Spec (Default)
Every HTML output must feel alive — static mockups are not acceptable. Follow this checklist:
Baseline (every output):
- CSS custom properties for all colors — use OKLCH where supported with hex fallback:
--accent: oklch(65% 0.2 250); /* fallback: #6366F1 */
- Semantic token layer:
--color-primary, --color-surface, --color-text mapping to primitives
- Google Fonts via
@import in <style> — always specify weights used, include font-display: swap
- Responsive: mobile-first, breakpoints at
640px and 1024px. Use clamp() for fluid values
- No frameworks by default — vanilla CSS + HTML + JS. CDN Tailwind only if user asks
@media (prefers-reduced-motion: reduce) block for all animations- Minimum visual completeness: populated data, real copy, working nav state
Interactivity baseline (every output — non-negotiable):
- Page load animation: Staggered entrance for hero elements (title → subtitle → CTA → image) using
animation-delay. See design-system/micro-interactions.md → Page Load.
- Scroll reveal: All below-fold sections use
IntersectionObserver to fade/slide in on scroll. Apply data-reveal to sections, data-reveal-stagger to card grids.
- Hover states: Every button, card, link, and image has visible hover feedback — card lift, image zoom, link underline animation, button press scale. Not just
opacity changes.
- Focus rings:
:focus-visible on all interactive elements with 2-3px offset ring.
- Smooth scroll:
html { scroll-behavior: smooth; } for anchor links.
- At least 3 micro-interactions from
design-system/micro-interactions.md appropriate to the domain (see the "Picking Micro-Interactions by Domain" table).
Enhanced interactivity (add when relevant to the design):
- Sticky header that shrinks/blurs on scroll — for any page with navigation
- Dark mode toggle with animated icon transition — for any page with
[data-theme] tokens
- Counter animation — for any stat/metric displays (KPIs, hero numbers, pricing)
- Scroll progress bar — for long-form editorial, case studies, documentation
- Infinite marquee — for client logos, skills, testimonials
- Image zoom on hover — for any image gallery, product grid, portfolio
- Accordion with animated height — for FAQ, menu sections, sidebar filters
- Tab switching with indicator slide — for any tabbed interface
- Toast notifications — for any form submission, copy action, save confirmation
- Floating labels — for any form with text inputs
Domain-specific interactivity (consult references/interactive-patterns.md):
- Dashboard: Live clock, animated charts (bar/donut/sparkline), flash-on-update metrics, sortable tables
- SaaS Landing: Scroll-driven parallax hero, animated counters in social proof, comparison slider for pricing
- E-commerce: Filter chips with animated show/hide, image carousel with scroll-snap, product image lightbox
- Portfolio: Masonry grid with animated layout, lightbox gallery, tilt-on-hover cards, cursor effects
- Food & Beverage: Image lightbox for dishes, accordion menus, step-by-step recipe checkboxes
- Fashion: Full-screen image carousel, countdown timer (for drops), before/after comparison slider
- Editorial: Word-by-word text reveal, scroll progress bar, parallax images, reading time estimate
- Education: Multi-step form with progress, drag-to-sort for quizzes, animated progress bars
- Mobile: Slide drawer navigation, snap-scroll carousel, pull-to-refresh hint, swipeable cards
Always load these references before coding:
references/design-system/micro-interactions.md — animation patterns and JS snippetsreferences/interactive-patterns.md — functional interaction patterns (filter, drag, charts, forms)
React Output Spec
- Functional components only — no class components
- Declare color tokens as
const theme = { ... } with OKLCH values and hex fallbacks
- Google Fonts: add a
<link> in the returned JSX or instruct user to add to index.html
- Prefer inline styles for one-off values; extract repeated patterns to a
styles object
- State assumptions upfront in a comment block: which components are stateful, what props to pass
- If Tailwind: use
@apply for repeated patterns; if CSS modules: one .module.css per component
- Use
useEffect sparingly — CSS animations and transitions preferred for entrances and states; JS for scroll observers and data-driven interactions
- Prop defaults must be realistic content (no
undefined, no "Lorem ipsum")
- Include interaction hooks:
useScrollReveal, useCounter, useThemeToggle as custom hooks where reusable
- Framer Motion: Allowed and encouraged for React outputs. Use
motion.div, AnimatePresence, useInView for scroll reveals, layout prop for animated filtering/sorting
Multi-Screen / Flow Support
When a user asks for a flow (onboarding, checkout, wizard, multi-step form):
- Render all screens side-by-side horizontally, each in a
390px frame with label above
- Use a shared
currentStep state variable to show/hide screens if making it interactive
- Annotate transitions: "→ swipe left to advance" or "→ tab triggers step 2"
- Each screen must be visually complete — never leave a screen empty as placeholder
- Apply onboarding principles: show don't tell, make skip visible, reach "aha" in ≤3 steps
Performance Baseline
Every output must meet these minimums:
- Images:
loading="lazy" on below-fold images, width/height attributes to prevent CLS, srcset for responsive images, WebP/AVIF format preference
- Fonts:
font-display: swap, subset to used character ranges when possible, preconnect to Google Fonts origin: <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
- CSS: No
@import for CSS files (blocks render) — only for Google Fonts in <style>. Use content-visibility: auto for off-screen sections
- Animation: Only
transform and opacity (GPU-composited). No will-change unless animation is imminent. Use Intersection Observer for scroll-triggered animations — never scroll event listeners
- Layout: No layout thrashing (read then write, never interleave). Avoid forced synchronous reflows
Production Hardening Checklist
Apply when the design will be used in real products:
Text resilience:
- All text containers handle overflow:
overflow: hidden; text-overflow: ellipsis for single-line, -webkit-line-clamp for multi-line
- Test with 2× expected content length — does the layout survive?
- Test with 0 content — does the empty state make sense?
- Headings:
overflow-wrap: break-word to prevent horizontal scroll on mobile
i18n readiness:
- No fixed-width containers for text — allow 30% expansion for German/French
- Use logical properties:
margin-inline-start not margin-left (RTL support)
- Numbers: use
Intl.NumberFormat for locale-aware formatting
- Dates: use
Intl.DateTimeFormat — never hardcode date formats
Error & edge states:
- Network failure: show last-known data with "Unable to update" banner, not a blank screen
- Slow connection: skeleton screens appear within 200ms if data isn't ready
- Invalid data: graceful degradation (show "--" for missing numbers, not NaN/undefined)
Input robustness:
- Debounce search/filter inputs (300ms)
- Prevent double-submit on forms (disable button after first click, re-enable on error)
- Paste handling: strip formatting on paste into plain-text inputs
Integration Quick-Start
After exporting, append a brief guide so users know how to own the code:
Making it yours:
- Colors: Edit the
--color-* CSS custom properties in :root — all colors flow from these tokens
- Fonts: Swap the Google Fonts
@import URL and update --font-display / --font-body
- Spacing: Adjust
--space-* tokens to scale the entire layout proportionally
- New pages: Copy the HTML structure, keep the same
<style> block — the token system ensures visual consistency
- Dark mode: Redefine
--color-* semantic tokens inside @media (prefers-color-scheme: dark) — primitives stay unchanged
- Framework migration: The CSS custom properties work in any framework. For React/Vue, map tokens to your theme object
Anti-Patterns (AI Slop Fingerprints)
Avoid these in every output — they are the telltale signs of AI-generated design:
| Anti-pattern | Instead |
|---|
| Two variations in the same aesthetic direction | Ensure A/B/C feel like different studios — re-check the direction table |
Inter, Roboto, Arial, system-ui as display fonts | Distinctive fonts: Instrument Sans, Fraunces, Outfit, Newsreader |
| Hardcoded hex values in CSS rules | CSS custom properties with OKLCH: color: var(--text) |
| Lorem ipsum or placeholder text | Real, domain-plausible content |
| Generic "Feature 1 / Feature 2 / Feature 3" copy | Specific feature names that match the domain |
| Five or more colors used at similar weight | 60-30-10: one dominant color used with conviction |
| Cards with identical sizes and equal visual weight | Vary card sizes to create rhythm and hierarchy |
| Hover states missing on interactive elements | Every button, link, and card needs hover + focus-visible |
| Mobile layouts that are just desktop shrunk down | Rethink for thumb zones, touch targets, and vertical flow |
| Gradient abuse (5+ color gradient backgrounds) | One solid color or a two-stop gradient maximum |
| Purple-to-blue gradients, cyan-on-dark, neon accents | Intentional palette from OKLCH, tinted neutrals |
| Glassmorphism everywhere (blur, glow borders) | Purposeful decorative elements that reinforce brand |
| Big rounded icons above every heading | They rarely add value — use typography for hierarchy |
| Cards nested inside cards | Flatten hierarchy — use spacing and dividers |
| Everything centered | Left-aligned with asymmetric layouts feels more designed |
| Same spacing everywhere | Varied spacing creates rhythm — tight groups, generous separations |
| Gradient text on headings/metrics | Decorative, not meaningful — use solid color with weight |
| Dark mode as default with glowing accents | Earn dark mode: different surface depths, desaturated accents, no shadows |
| Bounce/elastic easing | Exponential ease-out — real objects decelerate smoothly |
outline: none without replacement | :focus-visible with 2-3px offset ring |
| Modals for everything | Consider alternatives: inline expansion, drawers, popovers |
| Pure black (#000) or pure white (#fff) | Always tint — pure extremes don't exist in nature |
| Gray text on colored backgrounds | Use darker shade of the background color |
| Empty state = "No data" text only | Design as onboarding moment: acknowledge, explain value, CTA |
| Text that overflows its container | overflow-wrap: break-word, text-overflow: ellipsis, line-clamp |
| Static page with no animations or interactions | Every page needs: entrance animation, scroll reveals, hover states, ≥3 micro-interactions |
| Scroll reveal on ALL elements simultaneously | Stagger children with 60-80ms delay; animate sections independently |
JavaScript in <script> but nothing actually moves | Wire up scroll observer, counters, lightbox — code must produce visible motion |
Hover effects limited to opacity: 0.8 | Use card lift, image zoom, underline slide, color shift — see micro-interactions.md |
| Charts/numbers that appear fully rendered | Animate bar growth, counter count-up, donut draw on scroll into view |
Accessibility Baseline
Apply to every output — non-negotiable:
- Text contrast minimum: 4.5:1 for body, 3:1 for large text (≥24px bold or ≥18.5px normal)
- All interactive elements: minimum 44×44px touch/click target (use pseudo-elements if visual size is smaller)
- Focus rings: never
outline: none without a custom visible :focus-visible replacement
- Don't convey meaning by color alone — pair with icon, label, or pattern
- Avoid pure white on pure black for long-form text — slightly off-white/off-black (
#F0EDE8 on #111) reduces eye strain
@media (prefers-reduced-motion: reduce) — preserve functional animations (progress, loading), remove spatial movement- Use
rem/em for font sizes, never px for body text — respect browser settings
- Minimum 16px body text on all viewports
- Keyboard navigation: logical tab order, skip links for nav-heavy pages, roving tabindex for component groups
- ARIA: landmarks (
main, nav, aside), live regions for dynamic content, aria-describedby for form errors
