Imported from TylerSimons1127/vibe (skills/creative/ai-frontend-mastery/SKILL.md). Install upstream with npx skills add TylerSimons1127/vibe --skill ai-frontend-mastery. Copyright stays with the author (MIT (synthesis of public sources; see Re).

AI Frontend Mastery — getting the best design out of an AI agent

Synthesized from: Anthropic frontend-design skill, Together AI hallmark skill, Hermes anti-slop-web-design + claude-design + design-md skills, Composio's "Top Design Skills" (2026), Meez/Draper "why AI sites look generic", Superdesign's section-by-section method, Mindstudio design-tokens guide, and three YouTube deep-dives (Web2MCP + Superdesign canvas, "3 ways to make stunning sites with Claude Code", CodeGrid page-transition rebuild).

Core truth repeated by every source: AI has no taste. Vague prompts regress to the statistical mean — which IS the slop. The output quality tracks input specificity almost linearly. Fix it with process, not a better tool.

0. The one rule that beats every aesthetic trick

Surface-first. Commit to a composition archetype BEFORE any color or font.

Most AI slop is compositional, not cosmetic. A centered hero + 3 equal feature cards + CTA + footer is the default for every surface — recoloring it never fixes it.

The 7 surfaces (state the one you're building out loud before designing):

1. Monitor — watching state (dashboards). Density, glanceable hierarchy. NO hero.
2. Operate — taking action (consoles, admin). Action affordances dominate.
3. Compare — weighing options (pricing, spec tables). Aligned columns, parity.
4. Configure — setting up (settings, forms). Progressive disclosure, validation states.
5. Decide/Learn — being convinced (landing pages, docs). ONE idea per section. Hero is correct HERE ONLY.
6. Explore — browsing (galleries, catalogs). Filters, grids, zoom.
7. Command/Inspect — keyboard-driven / drilling into one object. Speed and focus.

The hero-plus-three-cards is correct for Decide/Learn only. Reaching for it anywhere else is the #1 tell.

1. The 4-part prompt framework (carry all four, every build)

Pass all four. NOT a 10k-line design.md — keep it loose but specific.

1. Aesthetic — the design family: "print-tech paper", "vast quiet cinematic", "editorial brutalist", "tactile rebellion", "classical remix", "riso print". Name a real family, not "modern/clean/premium".
2. Reference image(s) / URLs — from a taste library (Dribbble, Pinterest, X/Twitter UI creators, real sites). Goal = match the feel, not copy content. Real site URLs are fair game.
3. Intent — what it is, who's the audience, what ONE action you want (book demo, sign up, read). This dictates layout.
4. Guardrails — always-do / never-do list. Examples that reliably de-slop:
   • "Never purple-to-blue gradients." "Never Inter / Roboto / Arial / Space Grotesk by default."
   • "Never 3D SaaS blobs / generic glassmorphism as decoration."
   • "One accent color only, used in exactly one place." "Ban gradients outright."
   • "Numbered 01/02/03 markers only if content is a real sequence."
   • "Every component ships all 8 states: default/hover/focus/active/disabled/loading/error/success."

Example bad → good

❌ "Build me a modern landing page for my AI startup. Make it look professional with nice animations." ✅ "Hero: full-viewport. Background: looping motion clip (URL), scrim rgba(10,10,12,.55). Headline in Space Grotesk 600, clamp(44px,7vw,88px), -0.03em, two lines, second line italic serif (Instrument Serif). Left-aligned, max-width 12ch. One CTA: solid white, 14px/600, arrow translates 4px on hover, 200ms ease-out. Below fold: ..." (then 3,000 more chars of the same specificity, per section).

2. Token-plan workflow (do this in thinking before writing code)

Brainstorm a compact design system, then critique it against the brief, then build exactly to it.

• Color — 4–6 named hex values (ink, paper, ONE accent, one supporting). Full 50–900 shade scales for system-grade work. Define as CSS custom properties, never inline hex per component.
• Type — a characterful display face (restraint) + complementary body face + optional utility/mono face for data. Never default to Inter/system-ui unless intentional. Set a real scale (xs–5xl) with line-heights and tracking.
• Layout — one-sentence concept + ASCII wireframe. Asymmetry reads as designed; a 12-col grid with off-canvas crops beats "modern layout".
• Signature — the ONE memorable element this build is known by. Spend your boldness here; keep everything else quiet.
• Spacing — consistent 4px or 8px base. Radii — defined scale, NOT same radius everywhere. Motion — named durations + easing curves.

Self-critique pass: would this look the same for any other brief? If yes, revise. Cut one accessory (Chanel rule). Restraint is the default.

3. The verification loop (HIGHEST-leverage thing you can give an agent)

A blind model can't grade its own design. These MCPs are LIVE in this Hermes runtime — use them:

• mcp__playwright__browser_navigate / browser_take_screenshot / browser_snapshot — render the built page in a real browser, screenshot it, visually judge. A picture is worth 1000 tokens. Capture desktop + mobile viewports.
• mcp__mdvp_design_linter__perceive_url (domain=, live=true) — scores a site 0–100 across DOM/entropy/contrast/motion/classify and returns a ranked diagnosis + recommendations. Run it on your output and on reference sites. (Verified: graded linear.app B 69/100 PREMIUM, flagged 44% spacing off-grid, tight line-heights.)
• mcp__design_tokens__extract_design_system (url=) — extracts colors/typography/spacing/radius/shadows from any public site into tokens.json + tokens.css. Use to learn a reference site's system, then adapt (don't clone). (Verified: extracted Stripe's Söhne stack + spacing scale.)

Slop diagnostic — score out of 10 tells (lower is better): tech gradient, generic tech hue (indigo default), neon color/glow, feature-tile grid, accent rail, unearned blur, monument stat, icon topper, center stack, default type (Inter), wrong surface. Any neon color or glow = automatic fail. Re-score after repairs. Don't declare done while compositional tells fire.

Quality floor (unannounced): responsive to mobile, visible keyboard focus, prefers-reduced-motion respected, no single-viewport-only layouts, 44px hit targets on mobile.

4. Animation & effect stack (what actually works in 2026)

• Framer Motion / motion — best React fit; spring micro-interactions <200ms, staggered grid mount (not simultaneous), page transitions <400ms, skeleton loaders (not spinners). Default for app-grade React.
• GSAP — best for scroll-driven timelines, text-split reveals (SplitText, now free), complex orchestration, non-React or pinned sections. Pick GSAP when you need scroll-jacking / sequenced cinematic moments; Framer Motion for component-level spring feel.
• Lenis — smooth scroll (lerp), pairs with either. Adds the "weighted, expensive" feel. Respect reduced-motion.
• View Transitions API — native cross-document/page transitions in modern browsers; great for SPA route changes without a library.
• Micro-interaction vocabulary that reads premium: magnetic cursor-follow buttons, arrow translate on CTA hover, staggered fade-up on load (80ms), scroll-triggered reveals, subtle ambient atmosphere. Motion confirms an action — it does NOT decorate. If in doubt, cut it.
• Free text-reveal: GSAP SplitText (free), split-type npm, or CSS clip-path/overflow:hidden line masks.
• Page-transition pattern (CodeGrid award-site rebuild): overlay of N×M blocks, each scaleY 1→0 with per-row + random delay cascade, on enter AND exit, via Framer Motion AnimatePresence. Looks bespoke, ~40 lines.

Restraint rule (Anthropic + Hallmark agree): extra animation = "this is AI-generated" smell. One orchestrated entrance + one scroll behavior + hover micro-interactions beats a page of scattered effects.

5. DESIGN.md — the portable design-system file

A plain markdown file at repo root that any AI agent reads before building. Markdown is the format LLMs read best — no Figma/JSON. Define:

• color tokens (named, with roles), typography (font roles + scale), spacing scale, radii, shadows/elevation, motion posture, component treatment, interaction rules, written rationale.
• After generating, ask the agent to run a compliance pass against the DESIGN.md. Revisions point back to the shared source → no style drift between prompts.
• Real curated examples: VoltAgent/awesome-design-md repo (73+ site DESIGN.md files), styles.refero.design. Use as references, not templates — copy the system, not the site.

For agent-readable brand visuals at scale, also keep a JSON token file (colors/type/spacing/voice) — Mindstudio pattern: agents parse JSON trivially, single source of truth across web/mobile/PDF/image-prompts.

6. Iteration discipline (never one-shot)

1. Cast a wide net — generate 5 distinct aesthetic variations of the same brief, side by side. Compare all at once.
2. Narrow — pick the direction → 3 variants of that style (vary body format/layout).
3. Tinker — pick one → adjust fonts/colors/components. Build a visual "tweaks bar" (heading font, size, accent, motion, reveal distance) so you SEE differences fast instead of 10 full re-renders.
4. Branch, don't overwrite — keep every variant; feed the best back with a small nudge ("tighter hero", "warmer accent, less corporate", "add mobile version").
5. Section-by-section (Superdesign method) — one focused prompt per section (hero, social proof, features, pricing, CTA), each naming audience/offer/action/constraints. A single mega-prompt averages across goals → muddy page.
6. Apply references to the body too, not just the hero. Drop real URLs: "apply this site's body formatting to mine."

7. Tools to pull in (GitHub / MCP) — optional, raises ceiling

• nutlope/hallmark (npx skills add nutlope/hallmark) — 21 themes, 57 slop-test gates, structural-variety enforcement, audit/redesign/study verbs. The most complete anti-slop skill. Source of the 8-state component rule + diversification rule.
• anthropics/skills frontend-design — the canonical token-plan + surface-first skill (already mirrored in this skill's Sections 0–2).
• MCP Pointer (npx -y @mcp-pointer/server config <tool>) + Chrome extension — Option/Alt+Click any DOM element on any live site, feed its text/CSS/selector context to your agent. Clone inspiration precisely. Open-source, local.
• stagewise (github.com/stagewise-io/stagewise) — agentic IDE: click elements in your running app, send them to your coding agent for targeted fixes. Visual feedback loop inside the dev server.
• 21st.dev — copy real component prompts (buttons, cards, pricing, borders) from a 12k+ library.
• Impeccable (npx skills add pbakaus/impeccable) — 23 commands (bolder/quieter/typeset/colorize/animate) across brand vs product modes; 27 deterministic anti-pattern rules.

WARNING (anti-slop skill): don't fall into "one more skill fixes my design." Narrow prescriptive skills produce one kind of output. Prefer flexible tools whose results depend on YOUR prompting. Taste comes from humans; skills streamline what you already know (≈2x productivity).

9. Deep-research findings (verified sources, 2026)

9.1 The "specificity vs. decision-budget" nuance (resolves the contradiction)

Two strong sources disagree on how specific to be — and BOTH are right, applied differently:

• Meez / Superdesign / mindstudio say: name exact fonts, hex, grid, motion durations. Specificity tracks quality linearly.
• HAeG6k3HoFI + B2bNrB39L1c (Anthropic frontend-design plugin walkthroughs) warn: flooding a prompt with rigid pixel-perfect numbers spends the model's decision-making budget on your numbers, leaving no room for interesting choices → worse result. "Doing less produces a better result" when a design skill is already loaded.

Resolution: Give direction + constraints + references, not pixel dictatorship. Specify the things that encode taste (aesthetic family, type pairing, accent role, layout concept, motion posture, guardrails) and let the model decide spacing/padding details within those bounds. Use a design.json / DESIGN.md for the locked values instead of cramming them into prose. Over-specify only when cloning a specific reference.

9.2 The "clone" method (djDZHAi75dk)

To replicate a site you admire: ask any LLM (Claude/ChatGPT) to produce a JSON design system extracting colors, type scale, spacing, radii, shadows, component patterns from the reference (screenshot or URL). Hand that JSON to your coding agent with "follow this file, decide the rest." Result: pixel-consistent styling without mentioning design in the build prompt. (Pairs with mcp__design_tokens__extract_design_system which does this automatically from a live URL.)

9.3 Image-first composition workflow (uPIIJDmq5OU)

Instead of prompting for a template, prompt for a visual composition system: generate a 16:9 hero art plate (GPT-image / Higgs Field / your image gen) with an explicit brief — "don't use conventional hero layout; here is business context, composition, palette" — then code the UX around that reference image + a clean background plate. Reads bespoke because the composition was authored, not defaulted.

9.4 Full pre-build pipeline (89Fh_Ppw1A8)

Order of operations that beats one-shotting: (1) target-audience research → JSON, (2) SEO/copy generation from that JSON, (3) moodboard/design exploration in a canvas tool (Variant/Superdesign), (4) build in the coding agent. "Do the hard yards before building." The build step is easy because research + copy + design direction already exist as files.

9.5 AGENTS.md / CLAUDE.md — the persistent instruction layer

• AGENTS.md (or CLAUDE.md) is a README-for-agents at repo root: setup commands, code style, conventions, boundaries. Supported by 60k+ projects; symlink AGENTS.md↔CLAUDE.md so all tools read one file.
• Instruction budget (~150–200 rules max) — every token loads on every request. Keep it SMALL and focused; grow by progressive disclosure. Auto-generated bloated AGENTS.md files hurt performance (builders.io + aihero.dev agree).
• Use it for: package manager, framework, styling lib + format, token file location, dark-mode rules, "don't use X". NOT for cramming design taste — that belongs in DESIGN.md.
• DESIGN.md vs AGENTS.md: AGENTS.md = how to build (engineering); DESIGN.md = how it should look (visual system). Keep them separate. Both load automatically for any agent.

9.6 Agent prompting patterns (sureprompts / tweag — general, applies to design agents)

Tool use, reflection, ReAct, planning, multi-agent collaboration. For design: a planner agent writes the design brief/token plan; a builder agent implements; a critic agent (or the MDVP linter) scores against DESIGN.md. Decompose: "build hero" then "build features" beats one compound prompt holding 5 goals.

10. Techniques library (verified article deep-dives, 2026)

10.1 GSAP ScrollTrigger — the 3 patterns behind award-site scroll

From hontran.dev (verified). Master pin, scrub, parallax and you can recreate most award-site scroll effects. Always animate inside useGSAP (React) for auto-scoping/cleanup. start/end syntax is "[trigger] [scroller]" e.g. "top bottom" (trigger top hits viewport bottom), "top center", "bottom top", with offsets "top 80%", "+=600". markers:true while developing removes 90% of guesswork. Pair with Lenis. This is the differentiator vs Framer Motion for cinematic scroll storytelling.

10.2 React <ViewTransition> — native route/page animation

From react.dev official reference (verified, 31K). Wrap a tree: <ViewTransition><Page/></ViewTransition>. React auto-applies view-transition-name and calls startViewTransition behind the scenes (never call it yourself). Batches multiple updates into one animation (A→B, then B→D). Mandatory for SPA route transitions without a library; prefer over manual document.startViewTransition. (See CodeGrid rebuild in Section 4 for the manual block-cascade variant.)

10.3 CSS custom properties = the token backbone

From webtoolkit.tech (verified). CSS vars are runtime, inherited, not compile-time like Sass — change one on :root/media query/class and every consumer updates instantly. Rule: components reference semantic token names (--color-surface), never raw values. This is what makes dark mode, theming, and agent-consistent styling scale. (Mirrors design-token MCP output.)

10.4 Dark mode done right — OKLCH + light-dark() + View Transitions

From w3tweaks.com (verified, 27K). Three ingredients: CSS-var tokens, @media (prefers-color-scheme: dark), optional manual toggle. Modern default: OKLCH tokens + color-mix(). New light-dark() needs color-scheme: light dark on :root (the gotcha that breaks it). Animate the toggle with the View Transitions API circular-bloom. Fix dark-mode flash on SSG/SSR with an inline script setting data-theme before paint. Support forced-colors (Windows High Contrast). Set meta theme-color for mobile chrome. Tailwind v4: @custom-variant dark.

10.5 Skeleton screens > spinners

From LogRocket + NN/g (verified). Skeletons mimic final UI structure with animated placeholders → better perceived performance than spinners/blank. Best practice: match skeleton shape to real layout; use shimmer (not blink); swap to real content as it loads. Use for known-shape loading regions; use spinners only for unknown-duration actions.

10.6 Microinteractions that read premium

From Webflow (verified, 15 examples). Microinteractions = subtle feedback on hover/click/state (Dan Saffer). Premium patterns: password-rule green check, CTA hover shadow/color shift, cursor-driven image reveals (Lando Norris site: drag reveals helmet), scroll-triggered text/photo reveals. They guide, give feedback, add personality. Keep them tied to real state changes, not decoration.

10.7 SVG + CSS animation — lightweight, fast

From LogRocket (verified, 30K). Prefer SVG+CSS over GIFs/video (speed). Use for iconography, loading spinners, menu toggles, data-viz (D3). Animate via CSS transform/opacity (GPU-friendly), SMIL, or GSAP. Scales without quality loss.

10.8 Subagent design-review loop

From Claude Code docs (verified, 50K). Spawn isolated subagents to keep main context clean: a research/Explore subagent reads the repo for existing tokens/components; an implementation subagent builds; a critic subagent (or MDVP linter) scores against DESIGN.md. Subagents run parallel, can be scoped read-only, can route to cheaper models. For design: planner→builder→critic pipeline; the critic step is what closes the "looks generic" gap. (Pairs with Section 3 verification loop.)

11. Build checklist (paste into any frontend task)

• Stated the surface archetype in one line (Section 0).
• Wrote the 4-part prompt: aesthetic + reference + intent + guardrails (Section 1).
• Token plan drafted: color (named hex), type (display+body), layout concept, signature, spacing/radii/motion (Section 2).
• Self-critique: would this look the same for any brief? Cut one accessory.
• Built, then rendered via Playwright + screenshot at desktop + mobile.
• Ran MDVP linter; fixed ranked recommendations; re-scored.
• Slop diagnostic < 3 tells; no neon/glow; no wrong-surface hero.
• Quality floor: focus visible, reduced-motion respected, 44px targets.
• Iterated: 3+ variants compared, best branched forward.

References (verified during research)

• Anthropic frontend-design SKILL.md (raw.githubusercontent.com/anthropics/skills/main/skills/frontend-design)
• Together AI hallmark (github.com/Nutlope/hallmark) — 66KB rule-set, 57 slop gates, 8-state components
• Hermes skills: anti-slop-web-design, claude-design, design-md, popular-web-designs, premium-web-refs (already installed)
• Composio "Top 10 Design Skills for Claude Code and Codex" (composio.dev/content/top-design-skills)
• Meez "Why your AI-built website looks generic" (meez.design); Superdesign section-by-section method (superdesign.dev/blog)
• Mindstudio design-tokens guide; Refero + VoltAgent awesome-design-md DESIGN.md libraries
• YouTube: Web2MCP+Superdesign canvas; "3 ways to make stunning sites with Claude Code" (McJluKfjVGk); CodeGrid React page-transition rebuild (9W3yzVaxy8o)