---

What You Can Do

Job	Start with	Outcome
Build new UI	A brand brief, page idea, or existing reference prompt	Working React/Vite/Tailwind code or a portable one-shot prompt
Review a change	A diff or motion-bearing component	Profile-aware findings, exact Before/After values, and a Block/Approve verdict
Improve an existing app	A codebase that feels sluggish, generic, or inconsistent	Prioritized audit → self-contained plans → optional execute → reviewed implementation
Validate and tune	Existing CSS/JSX/TSX/HTML or an in-progress design decision	Score/grade plus exact tokens, easing, duration, pattern, and reusable primitives

The suite is deliberately split by responsibility: motion-site-builder builds, review-motion judges a change, and improve-motion surveys a codebase and plans the highest-leverage fixes. They share the same profile configs, 20-rule linter, and motion standards.

✨ What's Inside

🎬 Prompt Library	54 original prompts (cinematic heroes, dashboards, docs, storefronts, campaigns) ready to paste into Bolt, Lovable, v0, or Cursor — including our own landing page, two 100/A+ exemplars per non-cinematic profile, and a 20-concept Vietnam landscape collection with Pexels source pages and local-download targets. No brand replicas or hotlinked third-party assets.
🤖 Agent Skills (×3)	motion-site-builder: 15-step Plan → Build → Validate workflow. review-motion: mechanical lint + senior judgment → Before/After + Block/Approve. improve-motion: recon → 8-category audit → prioritized, executable plans → execute / reconcile.
✅ Motion Linter	Run it on generated or existing code. 20 profile-aware rules catch missing reduced-motion, layout-property animation, easing drift, video hygiene, accent misuse, ease-in UI, scale(0), wrong popover origin, missing press feedback, ungated hover motion, animated focus rings, overflow-x: hidden root masking, and z-index escape hatches. Returns findings, score, and grade.
🔌 MCP Server	8 zero-dependency tools expose five profiles, full tokens, 24 verbatim primitives, profile-specific pattern suggestions, easing/duration rationale, corpus retrieval, and inline/file validation.

🚀 Quick Start

Path 1 — Copy a production prompt (30 seconds)

1. Browse the prompt catalog and open a prompt close to your idea.
2. Copy the whole file into Bolt / Lovable / v0 / Cursor.
3. Personalize the explicitly marked values: brand/copy, palette within that profile's accent budget, and licensed local media or placeholders. Keep the motion and accessibility constraints intact.

Path 2 — Install the full agent suite

With the skills CLI (works for Claude Code, Cursor, Codex, and friends — re-run any time to update):

npx skills add olbboy/motion-site-builder --all
# review-motion/improve-motion share the builder engine; install it alongside either method skill:
npx skills add olbboy/motion-site-builder --skill motion-site-builder review-motion

In Claude Code you can also install via the plugin marketplace:

/plugin marketplace add olbboy/motion-site-builder

Or, to hack on the skills themselves, clone and symlink (Claude Code shown):

git clone https://github.com/olbboy/motion-site-builder
cd motion-site-builder
for s in motion-site-builder review-motion improve-motion; do
  ln -s "$(pwd)/skills/$s" ~/.claude/skills/$s
done

For another agent runtime, copy or link the same three directories using that runtime's SKILL.md discovery convention.

Use the skill that matches the job:

"Build a product-ui billing dashboard and return working code."
"Review the motion in this diff and give me a Block/Approve verdict."
"Audit this app with improve-motion deep; prioritize fixes by impact / effort."
"Execute plans/001-fix-dropdown-origin.md, then review the diff."

improve-motion is read-only during recon/audit: it writes implementation plans, not source changes. execute <plan> is the explicit implementation path; it dispatches an executor and reviews the resulting diff with the review-motion bar.

Path 3 — Enable the MCP tools (optional, zero deps)

{
  "mcpServers": {
    "motion-site-tools": {
      "command": "python3",
      "args": ["<repo>/skills/motion-site-builder/scripts/server.py"]
    }
  }
}

You get motion_list_profiles, motion_validate, motion_get_tokens, motion_get_template, motion_suggest_pattern, motion_easing_rationale, motion_find_reference, motion_validate_file. Every taste-bearing tool takes an optional profile arg.

🧠 How It Works

Most AI-generated sites look generic—and existing products often feel inconsistent—because motion decisions are left to chance. This repo turns taste into two deterministic workflows:

New brief    → Profile → Plan → Adapt nearest of 54 → Build → Lint → Runtime smoke
Existing UI → Recon   → Audit → Prioritized plans   → Execute → Review → Validate
Changed diff          → Profile-aware lint + judgment          → Block / Approve

• Retrieval over generation — the skill finds the closest existing prompt and adapts values instead of hallucinating structure.
• Verbatim primitives — signature CSS (liquid-glass, text-glow, seamless video crossfade, rAF+lerp parallax) is pasted exactly, never paraphrased.
• Deterministic quality gate — the linter scores every file 0–100; errors block, warnings advise.
• Judgment after lint — review and audit add frequency, interruptibility, cohesion, and missed-opportunity analysis that regex cannot see.
• Plans before mutation — whole-codebase improvement is scoped and reviewable before an executor touches source.
• Build accountability — the builder scans an existing project before touching it, previews its picks before writing code, self-critiques on six axes before emitting, then stamps the output (/* motion-site · … */) and appends .motion-site/log.json so the next build must differ — repeat briefs diverge instead of converging on one template.

🎨 The Design DNA — five profiles

The engine ships five design languages — pick one, and the linter + tools enforce that taste (motion_list_profiles, then a profile arg). Full guide: design-profiles.md.

Profile	For	Signature
cinematic (default)	hero, landing, launch	video-first, glass, serif, 1 accent, entrances 0.5–1.2s
product-ui	dashboard, SaaS, admin	crisp, fast (<250ms), light+dark, semantic multi-accent
editorial	blog, docs, articles	typography-first, prose, restrained motion
playful	consumer, creative, events	vibrant multi-accent, bouncy springs, decorative color
ecommerce	storefront, product page	imagery-first, snappy, quick-view, brand+neutral

Good motion feel (reduced-motion, GPU-only, press feedback, no ease-in on UI) is universal across all five; the tempo, palette, and typography vary per profile.

Cinematic (the default) — the signature elements the linter and tokens enforce:

Signature	What it means
Fullscreen video background	media is the canvas; UI stays quiet on top
Explicit z-index layering	depth via layering (video 0 → overlay 1 → content 10 → nav 20), never WebGL
rounded-full pill UI	glass pills for nav and buttons
Negative tracking on display type	tight, editorial headlines
Glassmorphism (backdrop-blur)	the liquid-glass surface primitive
Instrument Serif + Inter pairing	serif display over a clean sans body
Signature easing cubic-bezier(0.16, 1, 0.3, 1)	expo-out on entrances

Full guidelines: motion-design-dna.md. Everything is customizable — cinematic defaults live in config/motion-tokens.json; the other four languages live in config/profiles/*.json, all with the same schema. See the customization guide.

📁 Repository Structure

prompts/                      # the library — one .md per prompt (all original)
skills/llms.txt               # skill index (fast discovery for agents)
skills/motion-site-builder/   # the engine (build)
  SKILL.md                    #   agent workflow (entry point)
  references/                 #   profiles & schema, DNA, interaction standards, choreography,
                              #   modern-css motion, gsap interop, troubleshooting, catalog
  config/motion-tokens.json   #   cinematic taste (default profile)
  config/profiles/*.json      #   product-ui · editorial · playful · ecommerce
  data/prompt-index.json      #   generated corpus index
  scripts/                    #   linter · consistency audit · index builder · MCP server (zero-dep Python)
skills/review-motion/         # strict diff review (Before/After table + Block/Approve)
skills/improve-motion/        # codebase audit → self-contained plans (SKILL + AUDIT + PLAN-TEMPLATE)
site/                         # cinematic landing page — dogfooded from its own prompt
examples/                     # profile dogfoods (e.g. product-ui-dashboard — 100/A+ under product-ui)
docs/                         # getting started, prompt guidelines, architecture
.claude-plugin/               # plugin-marketplace manifests; AGENTS.md + copilot-instructions cover other runtimes

review-motion and improve-motion are method skills — they reuse the builder's linter, tokens, and standards rather than duplicating them.

📚 Documentation

• Getting Started — build, review, improve, and standalone validation paths
• Prompt Guidelines — how to write and submit a prompt
• Architecture — how the skill, linter, index, and MCP server fit together
• Project Roadmap — what's next (eval fixtures, variant mode, motion-DNA study)
• Interaction Standards — exact micro-motion values, springs & overshoot budgets, frequency rules
• Choreography — composing multi-element motion: attention budget, staging, direction semantics
• Profile Schema — the profile JSON schema + deriving a custom profile from references
• Modern CSS Motion · GSAP Interop · Troubleshooting Feel
• Review Skill · Improve Skill — working with existing code
• Skill README — customize & extend the engine

🤝 Contributing

Prompts, lint rules, and primitives are all welcome — see CONTRIBUTING.md. The short version:

1. Add your prompt to prompts/ following the guidelines.
2. Run python3 skills/motion-site-builder/scripts/build_index.py to re-index.
3. Run python3 skills/motion-site-builder/scripts/lint_motion.py --self-test if you touched the engine.
4. Open a PR — CI runs the same checks.

⚖️ License & Provenance

• Everything in this repo — code, skill, linter, docs, landing page, and all 54 prompts: MIT.
• Original prompts: every prompt is authored from this project's own design profiles and motion DNA. No brand replicas, copied copy, or hotlinked third-party assets.
• Bring your own media: most prompts use explicit placeholders. The Vietnam collection instead records Pexels source pages, photographer credits, crop guidance, and local-download targets; image binaries are not bundled. Re-check the source license before publication. All fonts are open-licensed (Google Fonts / OFL).

---