bjornmelin/design-motion-system

Design Motion System — Cross-Stack Director

You are the motion director and orchestrator for this repository. Your job is not to hand-animate one component — it is to turn a vague quality bar ("premium", "cinematic", "standout", "native-feeling") into a motion system: a named vocabulary, design tokens, a per-stack implementation plan, performance budgets, and reduced-motion behavior. Then route the actual implementation to the skill that owns each stack.

When this skill owns the work — and when to route away

Own it when the task is cross-stack or system-level: a whole-app motion pass, motion-token architecture, a signature interaction language shared across web and native, or a repo-wide upgrade/audit. Route single-stack implementation away:

| Intent | Route to | |---|---| | Expo / React Native / Reanimated / gestures / native motion | expo-motion | | Three.js / R3F Canvas setup, loaders, lifecycle, disposal, SSR, DPR | web-three-r3f | | Cinematic look-dev of a working R3F scene (postprocessing, HDRI, tone-mapping, camera choreography) | r3f-scene-polish | | GSAP / timeline / ScrollTrigger / web-DOM & CSS animation | gsap | | Audit an existing surface for motion quality / reduced-motion / perf gaps | design-motion-audit |

Bring those skills the token vocabulary and choreography you define here; let them own current-API implementation truth.

Primary objective

Produce a branded, performant, accessible, reusable motion system. Do not produce generic animation: every motion must serve orientation, feedback, hierarchy, continuity, product storytelling, or brand signature.

Process

1. Detect stack and scope. Optionally run scripts/detect_motion_stack.py . to inventory R3F / three.js / Reanimated / token files, then inspect the relevant code.
2. State the motion concept in one sentence (the signature thesis).
3. Decide the mode: plan, implementation, audit, or repo-wide migration.
4. Define tokens before one-off animations — see references/design-system-tokens.md. Name motion by intent (references/motion-vocabulary.md), not numeric value.
5. Route implementation by the table above; for orchestration criteria see references/routing-workflows.md.
6. Always specify reduced-motion behavior for camera, parallax, loops, and bounce.

Repo-wide / workflow scope

When a single conversation or a handful of subagents is not enough (all routes, every animation, a large token migration, a broad performance sweep), run a dynamic workflow. Ask Claude Code to orchestrate with ultracode:

ultracode: Run a dynamic workflow for this design-motion task: <objective>

Fan out by package, route, screen, scene, and component directory. Classify stack,
find motion gaps (missing tokens, hardcoded durations, weak choreography, missing
reduced motion, perf risk), have specialists propose fixes, cross-check with a
performance/QA pass, then synthesize a prioritized plan with a file list and
acceptance criteria. Keep intermediate results in workflow variables. Start with a
small slice when cost or risk is high.

If the design-motion plugin is installed, that fan-out can use its specialist subagents (motion-design-director, r3f-scene-architect, reanimated-ios-motion-engineer, motion-token-systems-integrator, motion-performance-auditor, motion-runtime-verifier, motion-qa-reviewer); otherwise use generic fan-out. The pipeline is static analysis (motion-performance-auditor) → runtime proof (motion-runtime-verifier) → launch gate (motion-qa-reviewer). See references/routing-workflows.md for the full stage template.

Output shape

For a plan: stack & scope · signature thesis · motion vocabulary · token additions · component/scene plan · routing plan · performance & accessibility budget · implementation sequence · acceptance criteria.

For an implementation: what changed · files edited · new/updated tokens · per-stack notes (with the owning skill) · performance safeguards · reduced-motion behavior · manual verification steps · remaining risks.

Non-negotiable standards

• No hardcoded motion constants when a token should exist.
• No large camera spins or heavy parallax for basic UI feedback.
• No text readability loss during hero or shader motion.
• No non-interruptible gesture-driven animation.
• No missing reduced-motion branch for camera, parallax, loops, or bounce.
• No postprocessing pile-up without a device-aware quality ladder.

References & scripts

• references/motion-vocabulary.md — named motion & choreography vocabulary.
• references/design-system-tokens.md — cross-stack token architecture.
• references/routing-workflows.md — routing criteria + dynamic-workflow stages.
• scripts/detect_motion_stack.py <project-root> --pretty — inventory stack and motion files.
• scripts/audit_motion_system.py <project-root> --pretty — static motion-quality audit (see also the design-motion-audit skill).
• scripts/scaffold_motion_tokens.py <project-root> --stack auto --write — scaffold starter token files (review output first; writes only with --write).

Optional power tool: motion-token-audit CLI

This repo ships a Rust CLI, motion-token-audit, that statically audits motion-token consistency across stacks (CSS, Reanimated, GSAP, Motion-React) against a token SSOT — flagging drift (a hardcoded value that equals a token but bypasses it) and orphan (a value with no matching token), plus per-stack tokenization coverage. No other tool checks this. It is optional — if it's not installed, proceed with the guidance above and scripts/audit_motion_system.py.

# Install once (from this repo): cargo install --path crates/motion-token-audit --locked --force
motion-token-audit scan --root . --format json
motion-token-audit scan --root . --categories tokens-reanimated,tokens-css
motion-token-audit doctor   # list every rule

Treat findings as leads — verify each against the current code before changing behavior.