Animated Frontend Design

animated-frontend-design

A multi-agent website-building engine. The user has one job: write or paste a brief. Everything else, design research, competitor scraping, palette/typography locking, page architecture, copywriting, component selection, animation wiring, SEO, QA, is done by specialized agents this skill dispatches in waves.

Why this skill exists

Claude is great at coding and OK at writing copy, but weak at originating visual design from a blank slate. Previous attempts (e.g. the deprecated website-factory skill) failed for predictable reasons: agents got vague one-liner prompts, design tokens were never locked so each page picked colors ad-hoc, the 12 card components were over-used producing card-on-card monotony, no competitor research grounded the messaging, and generated copy was riddled with em-dashes and "Empower / Streamline / Unlock" filler.

This skill solves that by:

1. Grounding every visual decision in real references. Dribbble shots, Awwwards sites, Land-book galleries, Godly anti-card layouts. Claude adapts what already works; it does not invent.
2. Locking the design system before any page is built, palette + typography + spacing + radius + shadow tokens are committed to tokens.css and tailwind.config.ts before Wave 4 begins. No agent can override them.
3. Enforcing layout diversity, the component-selector agent uses a decision tree that caps card-based sections at 2 per page and rotates between bento, marquee, sticky-scroll, timeline, comparison, hero-parallax, and full-bleed image sections.
4. Routing models by task economics. Haiku for scraping & checklist work, Sonnet for code & copy, Opus for the few decisions that actually require judgment (design-system locking, information architecture).
5. Post-build anti-AI-tell audit, em-dashes, "It's not just X, it's Y" negations, generic verbs, vague attributions are caught by scripts/audit_ai_tells.py and rewritten before the site ships.

When this skill fires

Run it whenever the user is building a website. Real triggers, match these liberally:

• "Build a website for [business]"
• "Make a SaaS landing page"
• "I need a [industry] site"
• "Here's my client brief..."
• "Create a marketing site for X"
• "Scaffold a Next.js site for my [agency / startup / portfolio / product]"
• The user pastes a PRD, brief, or competitor URL list
• The user has a half-built site and asks to "make it look professional / production-ready"

Do not refuse for under-specification. The brief-capture step inside Wave 0 is designed exactly for fragmentary inputs, ask the user the missing fields during the run, not before triggering.

Output stack (locked)

Generated sites use:

• Next.js 16 (App Router, TypeScript)
• Tailwind CSS 4 (v4 syntax: @import "tailwindcss", CSS-first config)
• Framer Motion 12 (under the motion package, import { motion } from "motion/react")
• GSAP 3.x + ScrollTrigger (for cinematic / award-tier heroes only)
• Lenis (smooth scroll, opt-in per project)
• lucide-react for icons

This stack is validated in production across Muskan-Jain-V2, VMS, Revun-Saas, Revun-Website, and veloice-ai. Do not deviate without an explicit user request.

The seven waves

Each wave is owned by an agent file under agents/. Read the agent file before dispatching that wave, these files are the actual prompts the orchestrator copies into subagent dispatches.

| # | Wave | Agent file | Model recommendation | What it produces | |---|----------------------------|-------------------------------------|----------------------|-------------------------------------------------------------------| | 0 | Brief capture + inspiration mining | agents/inspiration-miner.md | Haiku for scraping; Sonnet for synthesis | .planning/brief.json, .planning/inspiration/moodboard.md, .planning/inspiration/anti-patterns.md | | 1 | Competitor research | agents/competitor-researcher.md | Haiku | .planning/research/competitors/*.md, .planning/research/competitive-analysis.json | | 2 | Design system lock + IA | agents/design-system-locker.md, agents/information-architect.md | Opus (both) | src/styles/tokens.css, tailwind.config.ts, .planning/design-system.md, .planning/architecture.md | | 3 | Copywriting | agents/copywriter.md | Sonnet | .planning/pages/[route].md (one per route) | | 4 | Page building | agents/page-builder.md (component-selector logic embedded) | Sonnet (parallel, one per page) | src/app/[route]/page.tsx, src/components/sections/*.tsx | | 5 | Animation wiring | agents/animation-wirer.md | Sonnet | Motion props + scroll triggers wired into existing pages | | 6 | SEO polish | agents/seo-polisher.md | Haiku | sitemap.ts, robots.ts, JSON-LD blocks, metadata exports | | 7 | QA audit | agents/qa-auditor.md | Haiku | .planning/qa/audit.md, build pass, a11y pass, AI-tells cleared |

The waves are mostly sequential, but inside each wave subagents run in parallel when work is independent (e.g. Wave 4 dispatches one agent per route, all at once).

How to run the pipeline

When this skill fires, follow this exact protocol:

Step 1. Brief capture

If the user already provided a structured brief (markdown, JSON, URL), parse it. Otherwise, ask only the questions you genuinely cannot infer. Required fields:

• Business name + one-sentence description
• Industry (used to pull industry-defaults via python scripts/get_industry_defaults.py , do NOT read industry-defaults.ts directly; it's 478 lines of TypeScript)
• Primary audience (who buys / signs up)
• Top 3 competitors (URLs, if unknown, ask the inspiration-miner agent to discover them)
• Brand colors / fonts (if any, otherwise system picks)
• Pages required (if unknown, default per industry from scripts/get_industry_defaults.py )
• Animation intensity, subtle | dynamic | cinematic (default per industry)

Write the captured brief to .planning/brief.json. Validate it parses as JSON before moving on.

Step 2. Dispatch Wave 0 (inspiration mining)

Read agents/inspiration-miner.md. Spawn a single subagent with that prompt + the brief. It will scrape Dribbble, Awwwards, Land-book, SaaS Landing Page Inspiration, Godly, and Mobbin for the target industry and produce a moodboard.

Step 3. Dispatch Wave 1 (competitor research)

Read agents/competitor-researcher.md. Spawn one subagent. It will run scripts/firecrawl_research.py against the 10 - 15 competitor URLs and synthesize competitive-analysis.json.

Wave 0 and Wave 1 can run in parallel, dispatch both subagents in the same turn.

Step 4. Dispatch Wave 2 (design lock + IA)

Read agents/design-system-locker.md and agents/information-architect.md. These two agents cannot run in parallel, the IA agent reads the locked design system. Dispatch them sequentially. The design-system agent runs scripts/lock_design_tokens.py at the end of its work to commit tokens.css and tailwind.config.ts.

Step 5. Dispatch Wave 3 (copywriting)

Read agents/copywriter.md. Spawn one subagent per route, in parallel. Each invokes the copywriting skill internally for first drafts and the humanizer skill to strip AI tells. Each writes to .planning/pages/[route].md.

Step 6. Dispatch Wave 4 (page building)

Read agents/page-builder.md. Spawn one page-builder subagent per route, in parallel. Each subagent receives:

• The locked tokens.css and tailwind.config.ts
• Its assigned page's copy file (.planning/pages/[route].md)
• The architecture spec (.planning/architecture.md)
• The component decision tree (references/component-decision-tree.md)
• The layout-diversity rules (references/layout-diversity-rules.md)
• The current .planning/used-components.json (cross-route dedup state, see below)

The component-selector logic is embedded in the page-builder prompt; do not dispatch it as a separate agent.

Checkpoint protocol (mandatory). Before exiting, every Wave-4 subagent appends to .planning/wave-status.json one record of the form:

{"wave": 4, "route": "/pricing", "status": "ok", "ts": ""}

or, on failure:

{"wave": 4, "route": "/pricing", "status": "fail", "error": "", "ts": ""}

When this step runs, the orchestrator must FIRST read .planning/wave-status.json if it exists, skip every route already marked ok, and dispatch subagents only for routes with status fail or no entry. This makes Wave 4 resumable, a single route's TypeScript failure no longer forces the full wave to redo.

Cross-route dedup state. Each Wave-4 subagent also appends every picked component to .planning/used-components.json (a flat array of names). Subsequent agents pass this list to select_components.py --used so the diversity bonus penalizes already-used categories across pages, not just within a single page. The orchestrator writes an empty [] to this file before dispatching Wave 4 if it does not exist.

Step 7. Dispatch Wave 5 (animation wiring)

Read agents/animation-wirer.md. One subagent reads every page that Wave 4 produced and adds Framer Motion / GSAP wiring according to the brief's animation intensity setting and the motion-system reference.

Step 8. Dispatch Wave 6 (SEO polish)

Read agents/seo-polisher.md. One subagent. Mechanical work. JSON-LD, sitemap, robots, metadata exports.

Step 9. Dispatch Wave 7 (QA audit)

Read agents/qa-auditor.md. One subagent runs pnpm build, tsc --noEmit, checks for accessibility issues, and runs scripts/audit_ai_tells.py against all generated copy. If any blocker is found, the auditor rewrites or flags for the orchestrator to dispatch a focused fix.

Step 10. Report to user

Summarize what was built: pages, design tokens locked, components used, competitor insights applied, AI-tells stripped count, build status, Lighthouse score (if generated). Hand off the project path.

Hard rules (anti-pattern enforcement)

These rules exist because v1 violated them. They are not negotiable.

1. No page may contain more than 2 card-based sections. If a page needs more than 2 information-dense sections, rotate through: bento grid, sticky scroll reveal, comparison table, timeline, marquee, parallax-image-band, full-bleed quote, before/after slider, animated stat row. The decision tree is in references/layout-diversity-rules.md.

1. No agent may pick colors or fonts after Wave 2. All visual tokens come from src/styles/tokens.css. If an agent feels a color is missing, it must surface the gap, not invent.

1. No em-dashes in generated copy. Use periods, commas, or restructure. scripts/audit_ai_tells.py enforces this.

1. No generic AI verbs in headlines: "Empower", "Unlock", "Streamline", "Revolutionize", "Transform", "Elevate", "Supercharge" are banned in H1s. Use specific, concrete verbs grounded in the customer's actual job.

1. No hardcoded competitor names or stat numbers from example files. Every example in assets/examples/ is a pattern; the page-builder must replace all strings with brief-derived content. The example files are templates, not content.

1. No skipping Wave 0. Even if the user provides a detailed brief, run inspiration mining. Claude needs the visual references. If the user explicitly says "skip inspiration", honor it but warn that quality will drop.

1. Animation intensity governs every motion choice. A subtle site must not use cinematic-hero-gsap. A cinematic site must not stop at simple fade-ins. Cross-check intensity in Wave 5.

Reference files, read these on demand

Do not read all reference files at once. Read the ones you need for the wave you're in.

• references/motion-system.md, easing constants, Framer variants, GSAP defaults. Read at Wave 5.
• assets/components/_index.md, index of 113 bundled components grouped by purpose. Read whenever the auto-selector returns one of them.
• references/components-manifest.json, 923 unique components indexed (post-dedup, v1.1) across shadcn/ui, Magic UI, Aceternity, Origin UI, Cult UI, HextaUI, Animata, Page UI, 21st.dev, Preline, Flowbite, plus 113 bundled. Each entry has { name, source, fetch_cmd, category, tags, when_to_use, animation_intensity_range, industry_fit, anti_card_priority }. Never use the Read tool on this file (~250 KB, blows the context budget). Always query via python scripts/select_components.py --section ... --json.
• references/component-decision-tree.md, high-level routing logic the auto-selector uses. Read when debugging a selection that feels off.
• references/layout-diversity-rules.md, anti-card section rotation. Read at Wave 4.
• references/pattern-recipes.md, 30+ composed section recipes. Read at Wave 4.
• references/industry-defaults.ts, 15 industry presets (palette, fonts, hero pattern, CTAs, trust signals, default routes). Query via python scripts/get_industry_defaults.py at Wave 0 and Wave 2, do not parse the TypeScript by eye. The script handles alias resolution (healthcare → healthtech, proptech → realestate, ai → ai-ml, etc.).
• references/design-inspiration-sources.md. URLs + scraping recipes for Dribbble, Awwwards, Land-book, Godly, Mobbin. Read at Wave 0.
• references/anti-ai-tells.md, full list of patterns to strip from copy. Read at Wave 3 and Wave 7.
• references/model-routing.md, which model to use for which subagent dispatch.
• references/color-systems.md, references/typography-presets.md, base palettes and font stacks. Read at Wave 2.
• references/stack-template/, tailwind.config.ts, globals.css, layout.tsx, motion.ts starters.

Scripts, invoke these directly

• scripts/firecrawl_research.py ..., scrapes competitor sites, writes markdown + JSON to .planning/research/. Reads FIRECRAWL_API_KEY from env or .env.
• scripts/dribbble_mining.py "" --count 20, scrapes Dribbble + Awwwards + Land-book + Godly search results for the keyword, returns image URLs + colors + structure notes.
• scripts/extract_palette.py , extracts dominant colors from a reference image.
• scripts/lock_design_tokens.py --palette --fonts , generates src/styles/tokens.css and updates tailwind.config.ts.
• scripts/select_components.py --section --variant --intent --industry --intensity --used [--top N] [--json], the auto-selection brain. Reads references/components-manifest.json, applies the scoring algorithm (tag match 4 + industry weight 2 + intensity match 3 + diversity bonus 2.5 - already-used penalty + bundled bonus), returns the top 3 components with fetch_cmd and when_to_use rationale.
• scripts/fetch_component.py , on-demand fetch from source registry. Knows how to run pnpm dlx shadcn@latest add , pnpm dlx magicui-cli add , or scrape aceternity / cult-ui / origin-ui / 21st.dev / animata / page-ui raw source. Caches into src/components/ui/.
• scripts/audit_ai_tells.py , scans .md and .tsx for AI-tell patterns. Exits non-zero if any found. Default-excludes scraped competitor markdown, fetched docs, and references/anti-ai-tells.md (which legitimately documents bad examples).
• scripts/get_industry_defaults.py | --list | --all, returns the matched preset from references/industry-defaults.ts as JSON. Handles alias resolution (healthcare → healthtech etc.).
• scripts/sync_workspace.py , cross-platform workspace mirror using shutil.copytree(dirs_exist_ok=True). Replaces the broken cp --no-clobber approach.
• scripts/check_diversity.py , verifies a page.tsx or architecture.md respects the 2-card-cap. Exits 1 if violated.

Tools the skill expects

• Firecrawl API key, set FIRECRAWL_API_KEY in the user's .env or shell environment. Without it, Waves 0 and 1 fall back to the Composio MCP if available, or skip with a warning.
• Node.js 20+ and pnpm, for pnpm create next-app, pnpm install, pnpm build.
• Python 3.10+, for the s

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JatinChhabra07
• Source: JatinChhabra07/animated-frontend-design
• License: MIT

Install and usage instructions live in the source repository linked above.