ui-motion-atlas

Why UI Motion Atlas?

Most AI frontend prompts describe a pile of effects. The result may move, but the page still looks like the same template.

UI Motion Atlas reverses the order:

brief → foundation scene → narrative choreography → 2–3 support behaviors → implementation

One foundation scene recipe controls the composition, media hierarchy, section transitions, responsive behavior, and ending. Atomic UI patterns can support that scene, but cannot replace it.

The result is a design system for motion, not an animation shopping list.

What it helps create

• animation-rich portfolio websites;
• premium landing pages and campaign sites;
• original hero sections and narrative case studies;
• motion systems for SaaS and product interfaces;
• single-file HTML prototypes;
• implementation prompts for Codex, ChatGPT, Claude, Gemini, and other coding agents;
• reference-inspired designs without copying source code, assets, prompts, or complete layouts.

Inside the atlas

Every motion behavior is described through observable intent: trigger, response, resting state, timing, purpose, and reduced-motion fallback.

Design principles

• Composition before effects. Select one visual world before choosing animation patterns.
• Motion must advance the story. Fade-ups, particles, and hover scaling do not count as structural choreography.
• Different sections need different jobs. A palette change is not a new section design.
• Media carries evidence. Decorative UI cannot replace real project or product media.
• Originality is enforced. Category defaults and recognizable reference signatures are rejected.
• Accessibility survives the spectacle. Keyboard operation, visible focus, responsive recomposition, and prefers-reduced-motion are part of the contract.

Installation

Codex

Clone the repository, then copy the skill directory:

git clone https://github.com/Talhaer/ui-motion-atlas.git
Copy-Item -Recurse .\ui-motion-atlas\skill\ui-motion-atlas "$env:USERPROFILE\.codex\skills\ui-motion-atlas"

Invoke it naturally or explicitly:

Use $ui-motion-atlas to build a long, animation-rich portfolio with three projects.

Other AI coding agents

Point the agent's skill or rules system at:

skill/ui-motion-atlas/SKILL.md

The core guidance is plain Markdown. The optional query and prompt tools require Node.js 18 or newer and use no third-party runtime packages.

Agent products load skills differently. Confirm that your agent reads SKILL.md, can access the adjacent references/ directory, and is allowed to run the scripts. If it only reads the first file, use the generated prompt workflow below.

Quick start

Generate a complete implementation prompt:

npm run prompt -- \
  --brief "A dark blue, highly animated portfolio with three projects and no WebGL" \
  --target gemini \
  --output single-html

Find suitable foundation scenes:

npm run query:scene -- "image-led creative portfolio with continuous hero media"

Search supporting motion and UI behaviors:

npm run query -- "masked media reveal with a sticky narrative handoff"

Translate vague animation language:

npm run terms -- "subtle movement on hover"

Example request

Build a long portfolio for a digital product designer. Use dark navy, warm off-white, and only
one ice-blue accent. Show three projects, but do not put them in the same card template. Continue
the hero's main visual into the first project. Include at least three visible structural changes
during scroll; simple fade-ups do not count. Avoid filler copy, badges, coordinates, and fake
controls. Do not use WebGL. Recompose the mobile layout and support reduced motion. Return one
self-contained index.html and inspect it in a browser before finishing.

How the prompt engine works

1. Preserves explicit facts and constraints from the current brief.
2. Scores the scene library and selects one binding foundation recipe.
3. Selects only two or three compatible atomic behaviors.
4. Emits a composition, media, typography, motion, responsive, accessibility, and originality contract.
5. Adapts delivery language for Gemini, ChatGPT, Claude, or a generic coding agent.
6. Rejects prompts that lack a foundation scene or observable structural motion.

No proprietary prompt, component code, screenshot, or premium asset is included.

Validation

npm test

This validates:

• the Agent Skill structure and metadata;
• all 10 scene recipes;
• all 99 original behavior records;
• prompt selection across unrelated portfolio, product, and editorial briefs;
• technology exclusions such as “no WebGL”.

Repository structure

skill/ui-motion-atlas/
├── SKILL.md
├── agents/openai.yaml
├── assets/html-first-template.html
├── references/
│   ├── scene-recipes.json
│   ├── patterns/
│   ├── rules.md
│   ├── art-direction.md
│   ├── prompting-system.md
│   └── terminology.json
└── scripts/
    ├── prompt-engine.mjs
    ├── query-scene-recipes.mjs
    ├── query-atlas.mjs
    └── validators

Clean-room and licensing policy

UI Motion Atlas contains original, source-neutral descriptions of interface behavior. It does not redistribute third-party source code, DOM structures, class names, screenshots, videos, assets, or proprietary prompts. Product names and external references, when present, are identification or research pointers and do not grant permission to copy.

Code is available under the MIT License. Catalog text is available under CC BY 4.0.

Contributing

Contributions should add reusable behavior knowledge, not copied implementations. Read CONTRIBUTING.md before opening a pull request.