# motion-architect

Adopt this skill: https://proskills.md/skills/other/hainrixz-motion-architect-skills-motion-architect

Page: https://proskills.md/skills/other/hainrixz-motion-architect-skills-motion-architect
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/motion-architect/SKILL.md
size: 6338
sha: 4626df3e1387967b0b5ac78d0a543bcd14b03b45
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/SKILL.md

````text
---
name: motion-architect
description: Crea motion graphics y videos animados con Remotion, de forma local. Analiza videos de referencia (URL o archivo), imágenes y la marca de la persona; arma un storyboard, escribe la composición en React y la renderiza a mp4 en 16:9, 9:16, 1:1 o 4:5. Úsala cuando pidan "hazme una animación", "un motion graphic", "un video animado", "un intro/outro", "un reel animado", "anima este logo", "un video de lanzamiento", "como este video pero con mi marca", o /motion. EN — Create motion graphics locally with Remotion from video/image references and brand; triggers on "make an animation", "motion graphic", "animated video", "launch video", "animate my logo".
---
<!-- Copyright (c) 2026 Enrique Rocha (@soyenriquerocha) · tododeia.com · id er-22575577 -->

# Motion Architect

Eres **Motion Architect**, un director de motion graphics que trabaja en el estudio de Remotion de este repo (`studio/`). Todo corre en la computadora de la persona: nada se sube a ningún servicio.

Para la persona eres una sola herramienta. No hace falta explicarle los módulos internos ni pedirle que instale nada aparte: todo lo que necesitas viene en esta carpeta. Si pregunta de qué está hecho, la respuesta honesta es que es Remotion más componentes open source, listados en `third_party/NOTICES.md`.

`<skill-dir>` es la carpeta de este SKILL.md. Tus recursos internos:

| Recurso | Ruta | Para qué |
|---|---|---|
| Motor de visión | `<skill-dir>/engine/vision/analyze.py` | Ver videos: descarga, frames, cortes y transcripción. Ver `references/vision.md` |
| Motor de diseño | `<skill-dir>/engine/design/scripts/search.py` | Estilos, paletas y fuentes. Ver `references/design-engine.md` |
| Criterio de animación | `<skill-dir>/references/craft/` | Filosofía, estándares, recetas y vocabulario de movimiento |
| Librería de SFX | `studio/public/sfx/` (índice en `references/sfx-library.md`) | Clicks, impactos, whooshes y teclas (CC0) |

## Dónde está el estudio

Busca la carpeta `studio/` con `package.json` que dependa de `remotion`:
1. Primero en el directorio actual o sus padres.
2. Si no, en `$MOTION_ARCHITECT_HOME/studio`.
3. Si no, en `~/motion-architect/studio`.

Si no existe, dile a la persona que corra `./install.sh` del repo y para ahí.

## Flujo (siempre en este orden)

### 1. Intake: una sola pregunta, todo junto
Lee `references/intake.md`. Haz todas las preguntas en un solo mensaje. Si hay AskUserQuestion, úsalo para formato y tono. Lo que no respondan, asúmelo con los defaults de ese archivo y dilo en una línea.

### 2. Referencias
- **Videos** (URL o ruta local): usa el motor de visión (`references/vision.md`). Si hay varios o son largos, despacha el subagente `reference-analyst`, uno por video, en paralelo. Te devuelve un *motion spec*. Lee `references/references-from-video.md`.
- **Imágenes**: léelas con Read, cópialas a `studio/public/references/` y extrae paleta, composición y tipografía.
- **Logos o assets de la persona**: van a `studio/public/` y se usan con `staticFile()`.

### 3. Marca
Lee `references/brand.md`. Actualiza `studio/brand.json` y, si cambian las fuentes, los imports de `studio/src/brand/brand.ts`. Si no dan marca, propón una con el motor de diseño a partir del tono y las referencias. Nunca inventes un logo de una marca real.

### 4. Storyboard (la persona lo aprueba)
Lee `references/storyboard.md` y `references/tones.md`. Escribe `studio/storyboards/<id>.md` con escenas, duración en frames (30 fps), texto en pantalla, movimiento, transición y audio. Muéstralo resumido y **espera el sí** antes de escribir código. Es barato cambiar un storyboard y caro cambiar un render.

### 5. Build
Lee `references/remotion-patterns.md` y `references/motion-principles.md`. Para decisiones finas de movimiento consulta `references/craft/philosophy.md` y `references/craft/animate.md`.
- Crea `studio/src/compositions/<Id>.tsx`. El id va en PascalCase, sin espacios.
- Reutiliza `studio/src/components/` (Background, SafeArea, KineticTitle, LogoReveal, Counter, CardStack, Caption, ImagePan) y `studio/src/lib/motion.ts` (curvas `ease`, `springs`, `progress`, `enterStyle`). Crea componentes nuevos en `components/` solo cuando hagan falta.
- Registra la composición en `studio/src/compositions/index.ts` con los formatos pedidos.
- Diseña con `useScale()`: unidades relativas al lado corto, para que funcione en todos los formatos.
- Corre `npx tsc --noEmit` en `studio/` hasta que pase.

### 6. Revisión visual (antes de mostrar nada)
Saca 3 a 5 stills de momentos clave:
`npx remotion still src/index.ts <Id>-<formato> out/check-<n>.png --frame=<f>`
Míralos con Read. Revisa con la checklist de `references/motion-principles.md` y, para lo dudoso, con `references/craft/standards.md`. Arregla antes de seguir.

### 7. Preview
Dile a la persona que abra Remotion Studio con `cd studio && npm run studio` (abre http://localhost:3000). Ahí puede scrubbear el timeline. Si prefieres, lánzalo tú en segundo plano.

### 8. Render
Lee `references/formats.md`. Para cada formato pedido:
```
cd studio && npx remotion render src/index.ts <Id>-<formato> out/<id>-<formato>.mp4
```
Después:
- Saca el poster: `ffmpeg -y -ss <seg> -i out/<id>-<formato>.mp4 -frames:v 1 -q:v 2 out/<id>-<formato>.jpg`.
- Verifica las dimensiones con `ffprobe -v error -select_streams v:0 -show_entries stream=width,height,duration -of csv=p=0 out/<id>-<formato>.mp4`.
- Entrega las rutas y una línea por archivo con formato, duración y peso.

## Audio
Lee `references/audio-sync.md`. Los SFX incluidos son CC0. La música la pone la persona o debe tener una licencia clara.

## Reglas
- Todo es local. El motor de visión siempre va con `--engine local`. No subas assets a servicios externos ni uses APIs de generación sin que la persona lo pida.
- Cada movimiento debe tener una razón. Si no sabes por qué algo se mueve, que no se mueva.
- Las entradas usan ease-out y nunca escalan desde 0. Las salidas son más rápidas que las entradas.
- El texto tiene que leerse: mínimo 1 s en pantalla y unos 3 frames por letra en frases cortas.
- En 9:16, nada importante en el 14 % superior ni en el 20 % inferior (la UI de Reels/TikTok).
- Si algo falla (render, fuentes, tsc), explica en una frase qué pasó y cuál es el siguiente paso.
````

## File: skills/motion-architect/references/audio-sync.md
size: 1827
sha: 59dae14add2a4f5031886f48fe483dc38bc66264
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/audio-sync.md

````text
# Audio y sincronía

El audio es opcional. Una pista de fondo bien elegida y pocos SFX en los momentos clave suelen ser mejor que el silencio, pero menos es más.

## De dónde sale
- **SFX incluidos (CC0)** en `studio/public/sfx/`: `interface/` (clicks, switches, drops), `impact/` (golpes, campanas), `ui/`, `casino/` y `keyboard/` (teclas sueltas para animaciones de tipeo). El índice con usos recomendados y riesgo de agudos está en `sfx-library.md`. Úsalos con `staticFile("sfx/impact/impactSoft_medium_000.ogg")`.
- **Música**: la pone la persona en `studio/public/music/`. Si no tiene, sugiérele bibliotecas con licencia clara. Nunca descargues música con derechos de una plataforma para meterla en el video.

## En Remotion
```tsx
import { Audio, Sequence, staticFile, interpolate } from "remotion";
<Audio src={staticFile("music/track.mp3")} volume={(f) => interpolate(f, [0, 15, DUR - 20, DUR], [0, 0.6, 0.6, 0], { extrapolateRight: "clamp" })} />
<Sequence from={72}><Audio src={staticFile("sfx/whoosh.ogg")} volume={0.5} /></Sequence>
```

## Sincronizar con el beat
- Si conoces los BPM: `frames_por_beat = 30 * 60 / bpm` (120 bpm = 15 frames). Alinea los cortes y las entradas a múltiplos de eso.
- Para ver la energía de la pista y ubicar los golpes, localmente con ffmpeg:
  `ffmpeg -i track.mp3 -af "astats=metadata=1:reset=15,ametadata=print:key=lavfi.astats.Overall.RMS_level" -f null - 2>&1 | grep RMS | head`
- Los cortes grandes van en los golpes fuertes. Los staggers chicos pueden ir a la corchea (la mitad del beat).

## SFX con criterio
- Uno por evento importante (reveal, logo, CTA), no uno por cada cosa que se mueve.
- Whoosh suave en transiciones, click en taps simulados, impacto grave en el logo.
- Volumen de SFX entre 0.3 y 0.6, con la música por debajo (0.4–0.6) cuando hay voz.
````

## File: skills/motion-architect/references/brand.md
size: 1944
sha: d23480bb0360ddec84d27e88437324cb2e411d95
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/brand.md

````text
# Marca

La marca vive en `studio/brand.json`. Los componentes la leen desde `studio/src/brand/brand.ts`.

```json
{
  "name": "Nombre",
  "tagline": "Claim corto",
  "colors": { "background": "#…", "surface": "#…", "text": "#…", "muted": "#…", "accent": "#…", "accent2": "#…" },
  "fonts": { "display": "Bricolage Grotesque", "body": "Geist" },
  "radius": 28,
  "style": "Una línea con el carácter visual"
}
```

## De dónde sale
1. **La persona la da**: hex, fuentes, logo. Úsala tal cual.
2. **De una imagen o captura**: léela, extrae 3 a 5 colores dominantes (fondo, texto, acento) e identifica el estilo tipográfico.
3. **De un sitio**: pide la URL y mira su CSS y capturas. Busca variables `--color-*` y `font-family`.
4. **No hay marca**: usa el motor de diseño (`design-engine.md`) para proponer estilo, paleta y par tipográfico según el tono:
   `python3 <skill-dir>/engine/design/scripts/search.py "<producto> <industria> <mood>" --design-system -p "<Nombre>"`

## Cambiar fuentes
1. Mira si existe `studio/node_modules/@remotion/google-fonts/dist/esm/<NombreSinEspacios>.mjs`.
2. Cambia los imports en `src/brand/brand.ts`:
   ```ts
   import { loadFont as loadDisplay } from "@remotion/google-fonts/Syne";
   ```
3. Actualiza `fonts` en `brand.json`. Es solo informativo; la fuente real es la del import.
4. Fuente propia (.woff2/.ttf): ponla en `studio/public/fonts/` y cárgala con `loadFont` de `@remotion/fonts`. Si no está instalado: `npm i @remotion/fonts@<misma versión que remotion>`.

## Contraste
Texto sobre fondo ≥ 4.5:1. Texto grande (más de 48 px) ≥ 3:1. Si el acento no llega sobre el fondo, úsalo en formas y no en texto.

## Logo
Archivo de la persona en `studio/public/brand/logo.svg` (o png), usado con `<Img src={staticFile("brand/logo.svg")} />`. `LogoReveal` trae un símbolo genérico: reemplázalo por el logo real cuando exista. Nunca recrees el logo de una marca de terceros.
````

## File: skills/motion-architect/references/craft/animate.md
size: 11285
sha: 43a24447a524dbaab72f38bfe6975056af658d30
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/animate.md

````text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Building Animations

A construction skill. It does ONE thing: turn a request for motion into an implementation that would survive a strict review. It does not audit a codebase (that's `improve-animations`), critique a diff (that's `review-animations`), hunt for places that could animate (that's `find-animation-opportunities`), or build for React Native (that's `animate-expo`).

## Operating Posture

You are a senior design engineer building the animation yourself. The bar is Emil Kowalski's animation philosophy — the same bar `review-animations` enforces. Write it so it passes that review the first time.

Two failure modes, and the first is worse:

1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
2. **Animating the right thing with the wrong ingredients** — `ease-in` on an entrance, `scale(0)`, keyframes on a toast, a duration that makes a dropdown feel sluggish.

Never present motion options as a menu. Make the call, state the reasoning in one line, write the code.

## Hard Rules

1. **Run the sequence in order.** Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
2. **No approximated values.** Every curve, duration, and spring config comes from the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
3. **Extend the codebase's tokens, don't fork them.** If `--ease-out` or a duration scale already exists, use it. Adding a parallel system is a defect.
4. **Reduced motion and hover gating ship with the animation**, not as a follow-up.
5. **Cheapest tool that works.** Don't install a motion library for a fade.

## The Build Sequence

### 1. Should this animate at all?

| Frequency | Decision |
| --- | --- |
| 100+ times/day (keyboard shortcuts, command palette toggle) | **No animation. Ever.** Stop here. |
| Tens of times/day (hover effects, list navigation) | Near-imperceptible only — fast and subtle, or nothing |
| Occasional (modals, drawers, toasts) | Standard animation |
| Rare / first-time (onboarding, success, celebration) | The delight budget lives here |

**Keyboard-initiated actions are a disqualifier, not a judgment call.** Raycast has no open/close animation — that is correct for something opened hundreds of times a day.

If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.

### 2. What is the purpose?

Name it in one of these words before continuing:

- **Feedback** — confirming the interface heard the user
- **Spatial consistency** — showing where something came from or went
- **State indication** — making a state change legible
- **Preventing a jarring change** — bridging content that would otherwise teleport
- **Explanation** — demonstrating how something works (marketing/onboarding only)
- **Delight** — allowed *only* at the rare/first-time tier

Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.

Also check **function**: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.

### 3. Pick the tool — cheapest that works

Walk down; stop at the first that fits.

| Need | Tool |
| --- | --- |
| Hover, press, color, a state toggle you control with a class or attribute | **CSS transition** |
| Entry animation on mount, no JS state | **CSS `@starting-style`** |
| Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (runs off the main thread) |
| Programmatic control with CSS performance, no library | **WAAPI** (`element.animate()`) |
| Springs, layout animations, exit animations, gesture-driven values | **Motion** (`motion.dev`) |

CSS animations beat JS under load — they run off the main thread, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.

If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and invoke `pick-ui-library`. Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.

### 4. Pick the properties

- **`transform` and `opacity` only.** They skip layout and paint and run on the GPU. `width`/`height`/`margin`/`padding`/`top`/`left` trigger all three. (`clip-path` is the sanctioned fourth — see RECIPES.md. `height` is tolerated only for accordions, where there's no transform equivalent.)
- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
- **`transform-origin` at the trigger** for popovers, dropdowns, menus, tooltips — `var(--transform-origin)` in Base UI. **Modals are exempt**; they're not anchored to a trigger, so they stay centered.
- **Percentages in `translate()`** are relative to the element's own size — `translateY(100%)` moves by its own height whatever the content. Prefer over hardcoded pixels.
- **In Motion, use the full transform string.** `x`/`y`/`scale` shorthands are not hardware-accelerated and drop frames under load:

```jsx
<motion.div animate={{ x: 100 }} />                          // drops frames under load
<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
```

- **Never drive a child's transform from a CSS variable on the parent** — it recalculates styles for every child. Set `transform` on the element directly.

### 5. Easing and duration — or a spring

**Easing**, in decision order:

| Situation | Easing |
| --- | --- |
| Entering or exiting | `ease-out` |
| Moving / morphing on screen | `ease-in-out` |
| Hover / color change | `ease` |
| Constant motion (marquee, progress) | `linear` |
| Default | `ease-out` |

**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.

Built-in CSS easings are too weak. Use these:

```css
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
```

Need a curve that isn't here? Take it from [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/). Don't hand-roll one.

**Duration:**

| Element | Duration |
| --- | --- |
| Button press feedback | 100–160ms |
| Tooltips, small popovers | 125–200ms |
| Dropdowns, selects | 150–250ms |
| Modals, drawers | 200–500ms |
| Marketing / explanatory | Can be longer |

**UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one.

**Reach for a spring instead** when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:

```js
{ type: "spring", duration: 0.5, bounce: 0.2 }        // Apple-style — easier to reason about
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // traditional physics — more control
```

Keep bounce at 0.1–0.3, and avoid bounce in most UI — reserve it for drag-to-dismiss and playful interactions.

### 6. Interruption and exit

- **Transitions, not keyframes, for anything triggered rapidly** — toasts, toggles, anything a user can fire twice in a second. Transitions retarget from the current value; keyframes restart from zero.
- **Springs for gestures**, because they carry velocity through an interruption.
- **Exit the way it entered.** A toast that slides in from the bottom leaves through the bottom. Symmetric paths are what make swipe-to-dismiss feel obvious.
- **Asymmetric timing where the user is deciding.** Slow on the deliberate phase (a hold-to-confirm press: 2s linear), snappy on the system response (release: 200ms ease-out).

### 7. Reduced motion and pointer gating

Ships with the animation, every time.

```css
@media (prefers-reduced-motion: reduce) {
  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
}

@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
}
```

```jsx
const reduce = useReducedMotion();
const closedX = reduce ? 0 : '-100%';
```

Reduced motion means **fewer and gentler** animations, not zero — keep transitions that aid comprehension, remove movement and position changes.

## Recipes

For ready-to-build implementations of the common cases — button press, dropdown, tooltip, modal, drawer, toast, accordion, stagger, hold-to-confirm, tab indicator, scroll reveal, drag-to-dismiss — see [RECIPES.md](RECIPES.md). Load it whenever the request matches one of those components; start from the recipe rather than from a blank file.

## Never Ship

Self-check before you finish. Each of these is an automatic block in `review-animations`:

| Never | Instead |
| --- | --- |
| `transition: all` | Name the exact properties |
| `transform: scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
| `ease-in` on a UI element | `ease-out` or a strong custom curve |
| Built-in `ease-out` on a deliberate animation | `cubic-bezier(0.23, 1, 0.32, 1)` |
| Animation on a keyboard shortcut or 100+/day action | No animation |
| UI duration over 300ms with no reason | 150–250ms |
| `transform-origin: center` on a trigger-anchored popover | `var(--transform-origin)` (modals exempt) |
| Keyframes on toasts, toggles, rapidly-triggered elements | CSS transitions |
| Animating `width`/`height`/`margin`/`padding`/`top`/`left` | `transform` / `opacity` |
| Motion `x`/`y`/`scale` props under load | Full `transform` string |
| Ungated `:hover` motion | `@media (hover: hover) and (pointer: fine)` |
| Missing `prefers-reduced-motion` | Gentler variant, not zero |
| Everything entering at once | 30–80ms stagger |

## Output

Write the code. Then, in at most a few lines:

- **The gate result** — frequency tier and the named purpose. If something in the request was rejected, say which and why.
- **The ingredients** — tool, properties, curve, duration or spring config, in one line each.
- **What to feel-check** — if the result depends on feel you can't judge from code (a crossfade, a spring's bounce, the opacity/height balance in an entering list), say so and point at the check: play it at 2–5× duration or in the DevTools animation inspector, step it frame by frame, test gestures on a real device, and look again the next day with fresh eyes.

Don't pad this into a report. The code is the deliverable.

## Tone

Opinionated and brief. When the honest answer is "this shouldn't animate," give it — that answer is the reason this skill exists. When feel genuinely can't be settled from code, say so instead of guessing at a value.
````

## File: skills/motion-architect/references/craft/philosophy.md
size: 26841
sha: f3fb6cbde8dc0574c6f995d5ffbbf4585563665f
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/philosophy.md

````text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Design Engineering

You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.

## Core Philosophy

### Taste is trained, not innate

Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. You develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.

When building UI, don't just make it work. Study why the best interfaces feel the way they do. Reverse engineer animations. Inspect interactions. Be curious.

### Unseen details compound

Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. That is the goal.

> "All those unseen details combine to produce something that's just stunning, like a thousand barely audible voices all singing in tune." - Paul Graham

Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.

### Beauty is leverage

People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Beauty is underutilized in software. Use it as leverage to stand out.

## Review Format (Required)

When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:

| Before | After | Why |
| --- | --- | --- |
| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
| `transform-origin: center` on popover | `transform-origin: var(--transform-origin)` | Popovers should scale from their trigger (not modals — modals stay centered) |

Wrong format (never do this):

```
Before: transition: all 300ms
After: transition: transform 200ms ease-out
────────────────────────────
Before: scale(0)
After: scale(0.95)
```

Correct format: A single markdown table with | Before | After | Why | columns, one row per issue found. The "Why" column briefly explains the reasoning.

## The Animation Decision Framework

Before writing any animation code, answer these questions in order:

### 1. Should this animate at all?

**Ask:** How often will users see this animation?

| Frequency                                                   | Decision                     |
| ----------------------------------------------------------- | ---------------------------- |
| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever.          |
| Tens of times/day (hover effects, list navigation)          | Remove or drastically reduce |
| Occasional (modals, drawers, toasts)                        | Standard animation           |
| Rare/first-time (onboarding, feedback forms, celebrations)  | Can add delight              |

**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow, delayed, and disconnected from the user's actions.

Raycast has no open/close animation. That is the optimal experience for something used hundreds of times a day.

### 2. What is the purpose?

Every animation must have a clear answer to "why does this animate?"

Valid purposes:

- **Spatial consistency**: toast enters and exits from the same direction, making swipe-to-dismiss feel intuitive
- **State indication**: a morphing feedback button shows the state change
- **Explanation**: a marketing animation that shows how a feature works
- **Feedback**: a button scales down on press, confirming the interface heard the user
- **Preventing jarring changes**: elements appearing or disappearing without transition feel broken

If the purpose is just "it looks cool" and the user will see it often, don't animate.

### 3. What easing should it use?

Is the element entering or exiting?
  Yes → ease-out (starts fast, feels responsive)
  No →
    Is it moving/morphing on screen?
      Yes → ease-in-out (natural acceleration/deceleration)
    Is it a hover/color change?
      Yes → ease
    Is it constant motion (marquee, progress bar)?
      Yes → linear
    Default → ease-out

**Critical: use custom easing curves.** The built-in CSS easings are too weak. They lack the punch that makes animations feel intentional.

```css
/* Strong ease-out for UI interactions */
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);

/* Strong ease-in-out for on-screen movement */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);

/* iOS-like drawer curve (from Ionic Framework) */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
```

**Never use ease-in for UI animations.** It starts slow, which makes the interface feel sluggish and unresponsive. A dropdown with `ease-in` at 300ms _feels_ slower than `ease-out` at the same 300ms, because ease-in delays the initial movement — the exact moment the user is watching most closely.

**Easing curve resources:** Don't create curves from scratch. Use [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) to find stronger custom variants of standard easings.

### 4. How fast should it be?

| Element                  | Duration      |
| ------------------------ | ------------- |
| Button press feedback    | 100-160ms     |
| Tooltips, small popovers | 125-200ms     |
| Dropdowns, selects       | 150-250ms     |
| Modals, drawers          | 200-500ms     |
| Marketing/explanatory    | Can be longer |

**Rule: UI animations should stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. A faster-spinning spinner makes the app feel like it loads faster, even when the load time is identical.

### Perceived performance

Speed in animation is not just about feeling snappy — it directly affects how users perceive your app's performance:

- A **fast-spinning spinner** makes loading feel faster (same load time, different perception)
- A **180ms select** animation feels more responsive than a **400ms** one
- **Instant tooltips** after the first one is open (skip delay + skip animation) make the whole toolbar feel faster

The perception of speed matters as much as actual speed. Easing amplifies this: `ease-out` at 200ms _feels_ faster than `ease-in` at 200ms because the user sees immediate movement.

## Spring Animations

Springs feel more natural than duration-based animations because they simulate real physics. They don't have fixed durations — they settle based on physical parameters.

### When to use springs

- Drag interactions with momentum
- Elements that should feel "alive" (like Apple's Dynamic Island)
- Gestures that can be interrupted mid-animation
- Decorative mouse-tracking interactions

### Spring-based mouse interactions

Tying visual changes directly to mouse position feels artificial because it lacks motion. Use `useSpring` from Motion (formerly Framer Motion) to interpolate value changes with spring-like behavior instead of updating immediately.

```jsx
import { useSpring } from 'framer-motion';

// Without spring: feels artificial, instant
const rotation = mouseX * 0.1;

// With spring: feels natural, has momentum
const springRotation = useSpring(mouseX * 0.1, {
  stiffness: 100,
  damping: 10,
});
```

This works because the animation is **decorative** — it doesn't serve a function. If this were a functional graph in a banking app, no animation would be better. Know when decoration helps and when it hinders.

### Spring configuration

**Apple's approach (recommended — easier to reason about):**

```js
{ type: "spring", duration: 0.5, bounce: 0.2 }
```

**Traditional physics (more control):**

```js
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
```

Keep bounce subtle (0.1-0.3) when used. Avoid bounce in most UI contexts. Use it for drag-to-dismiss and playful interactions.

### Interruptibility advantage

Springs maintain velocity when interrupted — CSS animations and keyframes restart from zero. This makes springs ideal for gestures users might change mid-motion. When you click an expanded item and quickly press Escape, a spring-based animation smoothly reverses from its current position.

## Component Building Principles

### Buttons must feel responsive

Add `transform: scale(0.97)` on `:active`. This gives instant feedback, making the UI feel like it is truly listening to the user.

```css
.button {
  transition: transform 160ms ease-out;
}

.button:active {
  transform: scale(0.97);
}
```

This applies to any pressable element. The scale should be subtle (0.95-0.98).

### Never animate from scale(0)

Nothing in the real world disappears and reappears completely. Elements animating from `scale(0)` look like they come out of nowhere.

Start from `scale(0.9)` or higher, combined with opacity. Even a barely-visible initial scale makes the entrance feel more natural, like a balloon that has a visible shape even when deflated.

```css
/* Bad */
.entering {
  transform: scale(0);
}

/* Good */
.entering {
  transform: scale(0.95);
  opacity: 0;
}
```

### Make popovers origin-aware

Popovers should scale in from their trigger, not from center. The default `transform-origin: center` is wrong for almost every popover. **Exception: modals.** Modals should keep `transform-origin: center` because they are not anchored to a specific trigger — they appear centered in the viewport.

```css
/* Base UI */
.popover {
  transform-origin: var(--transform-origin);
}
```

Whether the user notices the difference individually does not matter. In the aggregate, unseen details become visible. They compound.

### Tooltips: skip delay on subsequent hovers

Tooltips should delay before appearing to prevent accidental activation. But once one tooltip is open, hovering over adjacent tooltips should open them instantly with no animation. This feels faster without defeating the purpose of the initial delay.

```css
.tooltip {
  transition: transform 125ms ease-out, opacity 125ms ease-out;
  transform-origin: var(--transform-origin);
}

.tooltip[data-starting-style],
.tooltip[data-ending-style] {
  opacity: 0;
  transform: scale(0.97);
}

/* Skip animation on subsequent tooltips */
.tooltip[data-instant] {
  transition-duration: 0ms;
}
```

### Use CSS transitions over keyframes for interruptible UI

CSS transitions can be interrupted and retargeted mid-animation. Keyframes restart from zero. For any interaction that can be triggered rapidly (adding toasts, toggling states), transitions produce smoother results.

```css
/* Interruptible - good for UI */
.toast {
  transition: transform 400ms ease;
}

/* Not interruptible - avoid for dynamic UI */
@keyframes slideIn {
  from {
    transform: translateY(100%);
  }
  to {
    transform: translateY(0);
  }
}
```

### Use blur to mask imperfect transitions

When a crossfade between two states feels off despite trying different easings and durations, add subtle `filter: blur(2px)` during the transition.

**Why blur works:** Without blur, you see two distinct objects during a crossfade — the old state and the new state overlapping. This looks unnatural. Blur bridges the visual gap by blending the two states together, tricking the eye into perceiving a single smooth transformation instead of two objects swapping.

Combine blur with scale-on-press (`scale(0.97)`) for a polished button state transition:

```css
.button {
  transition: transform 160ms ease-out;
}

.button:active {
  transform: scale(0.97);
}

.button-content {
  transition: filter 200ms ease, opacity 200ms ease;
}

.button-content.transitioning {
  filter: blur(2px);
  opacity: 0.7;
}
```

Keep blur under 20px. Heavy blur is expensive, especially in Safari.

### Animate enter states with @starting-style

The modern CSS way to animate element entry without JavaScript:

```css
.toast {
  opacity: 1;
  transform: translateY(0);
  transition: opacity 400ms ease, transform 400ms ease;

  @starting-style {
    opacity: 0;
    transform: translateY(100%);
  }
}
```

This replaces the common React pattern of using `useEffect` to set `mounted: true` after initial render. Use `@starting-style` when browser support allows; fall back to the `data-mounted` attribute pattern otherwise.

```jsx
// Legacy pattern (still works everywhere)
useEffect(() => {
  setMounted(true);
}, []);
// <div data-mounted={mounted}>
```

## CSS Transform Mastery

### translateY with percentages

Percentage values in `translate()` are relative to the element's own size. Use `translateY(100%)` to move an element by its own height, regardless of actual dimensions. This is how Sonner positions toasts and how Vaul hides the drawer before animating in.

```css
/* Works regardless of drawer height */
.drawer-hidden {
  transform: translateY(100%);
}

/* Works regardless of toast height */
.toast-enter {
  transform: translateY(-100%);
}
```

Prefer percentages over hardcoded pixel values. They are less error-prone and adapt to content.

### scale() scales children too

Unlike `width`/`height`, `scale()` also scales an element's children. When scaling a button on press, the font size, icons, and content scale proportionally. This is a feature, not a bug.

### 3D transforms for depth

`rotateX()`, `rotateY()` with `transform-style: preserve-3d` create real 3D effects in CSS. Orbiting animations, coin flips, and depth effects are all possible without JavaScript.

```css
.wrapper {
  transform-style: preserve-3d;
}

@keyframes orbit {
  from {
    transform: translate(-50%, -50%) rotateY(0deg) translateZ(72px) rotateY(360deg);
  }
  to {
    transform: translate(-50%, -50%) rotateY(360deg) translateZ(72px) rotateY(0deg);
  }
}
```

### transform-origin

Every element has an anchor point from which transforms execute. The default is center. Set it to match where the trigger lives for origin-aware interactions.

## clip-path for Animation

`clip-path` is not just for shapes. It is one of the most powerful animation tools in CSS.

### The inset shape

`clip-path: inset(top right bottom left)` defines a rectangular clipping region. Each value "eats" into the element from that side.

```css
/* Fully hidden from right */
.hidden {
  clip-path: inset(0 100% 0 0);
}

/* Fully visible */
.visible {
  clip-path: inset(0 0 0 0);
}

/* Reveal from left to right */
.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms ease-out;
}
.button:active .overlay {
  clip-path: inset(0 0 0 0);
  transition: clip-path 2s linear;
}
```

### Tabs with perfect color transitions

Duplicate the tab list. Style the copy as "active" (different background, different text color). Clip the copy so only the active tab is visible. Animate the clip on tab change. This creates a seamless color transition that timing individual color transitions can never achieve.

### Hold-to-delete pattern

Use `clip-path: inset(0 100% 0 0)` on a colored overlay. On `:active`, transition to `inset(0 0 0 0)` over 2s with linear timing. On release, snap back with 200ms ease-out. Add `scale(0.97)` on the button for press feedback.

### Image reveals on scroll

Start with `clip-path: inset(0 0 100% 0)` (hidden from bottom). Animate to `inset(0 0 0 0)` when the element enters the viewport. Use `IntersectionObserver` or Framer Motion's `useInView` with `{ once: true, margin: "-100px" }`.

### Comparison sliders

Overlay two images. Clip the top one with `clip-path: inset(0 50% 0 0)`. Adjust the right inset value based on drag position. No extra DOM elements needed, fully hardware-accelerated.

## Gesture and Drag Interactions

### Momentum-based dismissal

Don't require dragging past a threshold. Calculate velocity: `Math.abs(dragDistance) / elapsedTime`. If velocity exceeds ~0.11, dismiss regardless of distance. A quick flick should be enough.

```js
const timeTaken = new Date().getTime() - dragStartTime.current.getTime();
const velocity = Math.abs(swipeAmount) / timeTaken;

if (Math.abs(swipeAmount) >= SWIPE_THRESHOLD || velocity > 0.11) {
  dismiss();
}
```

### Damping at boundaries

When a user drags past the natural boundary (e.g., dragging a drawer up when already at top), apply damping. The more they drag, the less the element moves. Things in real life don't suddenly stop; they slow down first.

### Pointer capture for drag

Once dragging starts, set the element to capture all pointer events. This ensures dragging continues even if the pointer leaves the element bounds.

### Multi-touch protection

Ignore additional touch points after the initial drag begins. Without this, switching fingers mid-drag causes the element to jump to the new position.

```js
function onPress() {
  if (isDragging) return;
  // Start drag...
}
```

### Friction instead of hard stops

Instead of preventing upward drag entirely, allow it with increasing friction. It feels more natural than hitting an invisible wall.

## Performance Rules

### Only animate transform and opacity

These properties skip layout and paint, running on the GPU. Animating `padding`, `margin`, `height`, or `width` triggers all three rendering steps.

### CSS variables are inheritable

Changing a CSS variable on a parent recalculates styles for all children. In a drawer with many items, updating `--swipe-amount` on the container causes expensive style recalculation. Update `transform` directly on the element instead.

```js
// Bad: triggers recalc on all children
element.style.setProperty('--swipe-amount', `${distance}px`);

// Good: only affects this element
element.style.transform = `translateY(${distance}px)`;
```

### Framer Motion hardware acceleration caveat

Framer Motion's shorthand properties (`x`, `y`, `scale`) are NOT hardware-accelerated. They use `requestAnimationFrame` on the main thread. For hardware acceleration, use the full `transform` string:

```jsx
// NOT hardware accelerated (convenient but drops frames under load)
<motion.div animate={{ x: 100 }} />

// Hardware accelerated (stays smooth even when main thread is busy)
<motion.div animate={{ transform: "translateX(100px)" }} />
```

This matters when the browser is simultaneously loading content, running scripts, or painting. At Vercel, the dashboard tab animation used Shared Layout Animations and dropped frames during page loads. Switching to CSS animations (off main thread) fixed it.

### CSS animations beat JS under load

CSS animations run off the main thread. When the browser is busy loading a new page, Framer Motion animations (using `requestAnimationFrame`) drop frames. CSS animations remain smooth. Use CSS for predetermined animations; JS for dynamic, interruptible ones.

### Use WAAPI for programmatic CSS animations

The Web Animations API gives you JavaScript control with CSS performance. Hardware-accelerated, interruptible, and no library needed.

```js
element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }], {
  duration: 1000,
  fill: 'forwards',
  easing: 'cubic-bezier(0.77, 0, 0.175, 1)',
});
```

## Accessibility

### prefers-reduced-motion

Animations can cause motion sickness. Reduced motion means fewer and gentler animations, not zero. Keep opacity and color transitions that aid comprehension. Remove movement and position animations.

```css
@media (prefers-reduced-motion: reduce) {
  .element {
    animation: fade 0.2s ease;
    /* No transform-based motion */
  }
}
```

```jsx
const shouldReduceMotion = useReducedMotion();
const closedX = shouldReduceMotion ? 0 : '-100%';
```

### Touch device hover states

```css
@media (hover: hover) and (pointer: fine) {
  .element:hover {
    transform: scale(1.05);
  }
}
```

Touch devices trigger hover on tap, causing false positives. Gate hover animations behind this media query.

## The Sonner Principles (Building Loved Components)

These principles come from building Sonner (13M+ weekly npm downloads) and apply to any component:

1. **Developer experience is key.** No hooks, no context, no complex setup. Insert `<Toaster />` once, call `toast()` from anywhere. The less friction to adopt, the more people will use it.

2. **Good defaults matter more than options.** Ship beautiful out of the box. Most users never customize. The default easing, timing, and visual design should be excellent.

3. **Naming creates identity.** "Sonner" (French for "to ring") feels more elegant than "react-toast". Sacrifice discoverability for memorability when appropriate.

4. **Handle edge cases invisibly.** Pause toast timers when the tab is hidden. Fill gaps between stacked toasts with pseudo-elements to maintain hover state. Capture pointer events during drag. Users never notice these, and that is exactly right.

5. **Use transitions, not keyframes, for dynamic UI.** Toasts are added rapidly. Keyframes restart from zero on interruption. Transitions retarget smoothly.

6. **Build a great documentation site.** Let people touch the product, play with it, and understand it before they use it. Interactive examples with ready-to-use code snippets lower the barrier to adoption.

### Cohesion matters

Sonner's animation feels satisfying partly because the whole experience is cohesive. The easing and duration fit the vibe of the library. It is slightly slower than typical UI animations and uses `ease` rather than `ease-out` to feel more elegant. The animation style matches the toast design, the page design, the name — everything is in harmony.

When choosing animation values, consider the personality of the component. A playful component can be bouncier. A professional dashboard should be crisp and fast. Match the motion to the mood.

### The opacity + height combination

When items enter and exit a list (like Family's drawer), the opacity change must work well with the height animation. This is often trial and error. There is no formula — you adjust until it feels right.

### Review your work the next day

Review animations with fresh eyes. You notice imperfections the next day that you missed during development. Play animations in slow motion or frame by frame to spot timing issues that are invisible at full speed.

### Asymmetric enter/exit timing

Pressing should be slow when it needs to be deliberate (hold-to-delete: 2s linear), but release should always be snappy (200ms ease-out). This pattern applies broadly: slow where the user is deciding, fast where the system is responding.

```css
/* Release: fast */
.overlay {
  transition: clip-path 200ms ease-out;
}

/* Press: slow and deliberate */
.button:active .overlay {
  transition: clip-path 2s linear;
}
```

## Stagger Animations

When multiple elements enter together, stagger their appearance. Each element animates in with a small delay after the previous one. This creates a cascading effect that feels more natural than everything appearing at once.

```css
.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms ease-out forwards;
}

.item:nth-child(1) {
  animation-delay: 0ms;
}
.item:nth-child(2) {
  animation-delay: 50ms;
}
.item:nth-child(3) {
  animation-delay: 100ms;
}
.item:nth-child(4) {
  animation-delay: 150ms;
}

@keyframes fadeIn {
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

Keep stagger delays short (30-80ms between items). Long delays make the interface feel slow. Stagger is decorative — never block interaction while stagger animations are playing.

## Debugging Animations

### Slow motion testing

Play animations at reduced speed to spot issues invisible at full speed. Temporarily increase duration to 2-5x normal, or use browser DevTools animation inspector to slow playback.

Things to look for in slow motion:

- Do colors transition smoothly, or do you see two distinct states overlapping?
- Does the easing feel right, or does it start/stop abruptly?
- Is the transform-origin correct, or does the element scale from the wrong point?
- Are multiple animated properties (opacity, transform, color) in sync?

### Frame-by-frame inspection

Step through animations frame by frame in Chrome DevTools (Animations panel). This reveals timing issues between coordinated properties that you cannot see at full speed.

### Test on real devices

For touch interactions (drawers, swipe gestures), test on physical devices. Connect your phone via USB, visit your local dev server by IP address, and use Safari's remote devtools. The Xcode Simulator is an alternative but real hardware is better for gesture testing.

## Review Checklist

When reviewing UI code, check for:

| Issue                                      | Fix                                                              |
| ------------------------------------------ | ---------------------------------------------------------------- |
| `transition: all`                          | Specify exact properties: `transition: transform 200ms ease-out` |
| `scale(0)` entry animation                 | Start from `scale(0.95)` with `opacity: 0`                       |
| `ease-in` on UI element                    | Switch to `ease-out` or custom curve                             |
| `transform-origin: center` on popover      | Set to trigger location or use Base UI's `var(--transform-origin)` (modals are exempt — keep centered) |
| Animation on keyboard action               | Remove animation entirely                                        |
| Duration > 300ms on UI element             | Reduce to 150-250ms                                              |
| Hover animation without media query        | Add `@media (hover: hover) and (pointer: fine)`                  |
| Keyframes on rapidly-triggered element     | Use CSS transitions for interruptibility                         |
| Framer Motion `x`/`y` props under load     | Use `transform: "translateX()"` for hardware acceleration        |
| Same enter/exit transition speed           | Make exit faster than enter (e.g., enter 2s, exit 200ms)         |
| Elements all appear at once                | Add stagger delay (30-80ms between items)                        |
````

## File: skills/motion-architect/references/craft/recipes.md
size: 8183
sha: ec68ec515c061e566c4590aa30feddb1bf7c5c4a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/recipes.md

````text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Animation Recipes

Ready-to-build implementations for the cases that come up most. Start from the recipe, then adapt — don't rebuild from scratch.

Curves are the `--ease-out`, `--ease-in-out`, and `--ease-drawer` tokens defined in philosophy.md.

---

## Button press

Any pressable element. Instant feedback that the interface heard the user.

```css
.button {
  transition: transform 160ms var(--ease-out);
}

.button:active {
  transform: scale(0.97);
}
```

`scale()` scales children too — the label and icons come along, which is what makes it read as a physical press.

No hover gating needed here: `:active` is a real press on touch. Gate any `:hover` styling separately.

---

## Dropdown, popover, menu, select

Scales out of its trigger, not out of thin air.

```css
.popover {
  transform-origin: var(--transform-origin); /* Base UI supplies this */
  transition:
    opacity 200ms var(--ease-out),
    transform 200ms var(--ease-out);
}

.popover[data-starting-style],
.popover[data-ending-style] {
  opacity: 0;
  transform: scale(0.95);
}
```

The `transform-origin` is the whole point — the panel should look like it came out of the thing you clicked.

---

## Tooltip

Same shape as a popover, faster, plus the detail most implementations miss.

```css
.tooltip {
  transform-origin: var(--transform-origin);
  transition:
    transform 125ms var(--ease-out),
    opacity 125ms var(--ease-out);
}

.tooltip[data-starting-style],
.tooltip[data-ending-style] {
  opacity: 0;
  transform: scale(0.97);
}

/* Once one tooltip is open, neighbours open instantly */
.tooltip[data-instant] {
  transition-duration: 0ms;
}
```

The initial delay prevents accidental activation. After that, skipping both the delay and the animation makes the whole toolbar feel faster.

---

## Modal

The one popover that stays centered.

```css
.modal {
  transform-origin: center; /* exempt — not anchored to a trigger */
  transition:
    opacity 250ms var(--ease-out),
    transform 250ms var(--ease-out);
}

.modal[data-starting-style],
.modal[data-ending-style] {
  opacity: 0;
  transform: scale(0.96);
}

.backdrop {
  transition: opacity 250ms var(--ease-out);
}
```

Animate the backdrop's opacity alongside it so they read as one surface.

---

## Drawer / sheet

```css
.drawer {
  transform: translateY(0);
  transition: transform 500ms var(--ease-drawer);
}

.drawer[data-closed] {
  transform: translateY(100%);
}
```

This is how Vaul hides a drawer before animating it in.

Add drag and it becomes a gesture problem — see **Drag to dismiss** below.

---

## Toast

```css
.toast {
  opacity: 1;
  transform: translateY(0);
  transition:
    opacity 400ms ease,
    transform 400ms ease;

  @starting-style {
    opacity: 0;
    transform: translateY(100%);
  }
}
```

- `ease` rather than `ease-out`, slightly slower than typical UI: Sonner reads as elegant partly because its motion is tuned to the component's personality rather than to the generic UI budget.
- If `@starting-style` isn't available, fall back to the mount flag:

```jsx
useEffect(() => { setMounted(true); }, []);
// <div data-mounted={mounted}>
```

When toasts stack and the list reflows, the opacity change has to work against the height change. There's no formula for that pair — adjust until it feels right, then check it again the next day.

---

## Accordion / collapse

```css
.content {
  overflow: hidden;
  transition:
    height 200ms var(--ease-out),
    opacity 200ms var(--ease-out);
}
```

Keep it short — this is one of the few animations that costs layout on every frame, so a long duration is expensive as well as sluggish. Measure the content height in JS (or use a headless primitive that supplies it) rather than animating to `auto`.

---

## Stagger a group entrance

For a list or grid the user sees occasionally — not for a list they scroll past all day.

```css
.item {
  opacity: 0;
  transform: translateY(8px);
  animation: fadeIn 300ms var(--ease-out) forwards;
}

.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }
.item:nth-child(4) { animation-delay: 150ms; }

@keyframes fadeIn {
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

Stagger is decorative — it must never block interaction while it plays.

---

## Hold to confirm

For destructive actions where a plain click is too easy to fire by accident.

```css
.overlay {
  clip-path: inset(0 100% 0 0);
  transition: clip-path 200ms var(--ease-out); /* release: snappy */
}

.button:active .overlay {
  clip-path: inset(0 0 0 0);
  transition: clip-path 2s linear;             /* press: slow and deliberate */
}

.button:active {
  transform: scale(0.97);
}
```

`linear` is correct here — the fill is a progress indicator, and progress shouldn't ease.

---

## Tab indicator with a color transition

Timing individual color transitions across a tab list never quite lands. Clip instead.

Duplicate the tab list. Style the copy as the active state — different background, different text color. Clip the copy so only the active tab shows, and animate the clip on change:

```css
.tabs-active-copy {
  clip-path: inset(0 60% 0 20%); /* driven by the active tab's position */
  transition: clip-path 250ms var(--ease-in-out);
}
```

The text and background change together, in perfect sync, because they're one element being revealed rather than two colors being interpolated.

---

## Scroll reveal

Marketing surfaces only. Don't do this to functional UI a user visits daily.

```css
.reveal {
  clip-path: inset(0 0 100% 0);
  transition: clip-path 600ms var(--ease-in-out);
}

.reveal[data-visible] {
  clip-path: inset(0 0 0 0);
}
```

Trigger with `IntersectionObserver`, or Motion's `useInView` with `{ once: true, margin: "-100px" }`. Fire it once — re-animating on every scroll-by is an interface fighting its reader.

---

## Drag to dismiss

The gesture recipe. Springs, not durations, because the user can reverse mid-motion.

```js
// Dismiss on a flick, not just on distance
const timeTaken = Date.now() - dragStartTime.current;
const velocity = Math.abs(swipeAmount) / timeTaken;

if (Math.abs(swipeAmount) >= SWIPE_THRESHOLD || velocity > 0.11) {
  dismiss();
}
```

```js
// Set transform on the dragged element directly.
// Driving it through a CSS variable on the parent recalcs styles for every child.
element.style.transform = `translateY(${distance}px)`;
```

Four details that separate a good drag from a bad one:

- **Pointer capture** once the drag starts, so it continues when the pointer leaves the element's bounds.
- **Multi-touch protection** — `if (isDragging) return` on new touch points, or switching fingers mid-drag makes the element jump.
- **Damping past boundaries** — dragging beyond a natural edge moves the element less the further it goes. Real things slow before they stop.
- **Friction, not a wall** — allow the over-drag with rising resistance rather than refusing it.

Settle with a spring so an interrupted drag keeps its velocity:

```js
{ type: "spring", duration: 0.5, bounce: 0.2 }
```

---

## Masking a crossfade that won't settle

When two states overlap visibly during a transition and no amount of easing or duration tuning fixes it, blur the seam:

```css
.content {
  transition:
    filter 200ms ease,
    opacity 200ms ease;
}

.content.transitioning {
  filter: blur(2px);
  opacity: 0.7;
}
```

Without blur the eye reads two distinct objects swapping. Blur blends them into one perceived transformation. Keep it under 20px — heavy blur is expensive, especially in Safari.

---

## Programmatic, without a library

When the motion needs JS control but not a dependency, WAAPI gives you CSS-grade performance:

```js
element.animate(
  [{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
  { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' }
);
```

Hardware-accelerated, interruptible, no bundle cost.
````

## File: skills/motion-architect/references/craft/review.md
size: 8092
sha: 888c697ce2a7b91e8ce0fcce54f87a8845dac22f
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/review.md

```text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Reviewing Animations

A specialized review skill. It does ONE thing: review animation and motion code against a high craft bar. It does not write features, fix unrelated bugs, or review non-motion code. If asked to review general code, decline and point to a general review skill.

## Operating Posture

You are a senior design engineer with a brutal eye for craft. Your bias is toward **motion that feels right**, not motion that merely runs. A transition that "works" but feels sluggish, lands from the wrong origin, fires too often, or drops frames is a regression, not a pass. Default to flagging. Approval is earned, not assumed.

The substantive bar comes from Emil Kowalski's animation philosophy (animations.dev). The review *method* — non-negotiable standards, escalation triggers, a remedial hierarchy, tiered output, and explicit approval criteria — is adapted from aggressive code-quality review.

For the full rule catalog (easing curves, duration tables, spring config, gestures, clip-path, performance, a11y), see [STANDARDS.md](STANDARDS.md). Load it whenever a finding needs a precise value or citation.

## The Ten Non-Negotiable Standards

Every animation in the diff is measured against these. A violation is a finding.

1. **Justified motion.** Every animation must answer "why does this animate?" — spatial consistency, state indication, feedback, explanation, or preventing a jarring change. "It looks cool" on a frequently-seen element is a block.

2. **Frequency-appropriate.** Match motion to how often it's seen. Keyboard-initiated and 100+/day actions get **no** animation. Tens/day gets reduced motion. Occasional gets standard. Rare/first-time can have delight.

3. **Responsive easing.** Entering/exiting elements use `ease-out` or a strong custom curve. `ease-in` on UI is a block — it delays the moment the user watches most. Built-in CSS easings are too weak; expect custom cubic-beziers.

4. **Sub-300ms UI.** UI animations stay under 300ms; anything slower on a UI element needs justification or it's a finding. Per-element budgets live in [STANDARDS.md](STANDARDS.md).

5. **Origin & physical correctness.** Popovers/dropdowns/tooltips scale from their trigger (`transform-origin`), not center. Never animate from `scale(0)` — start from `scale(0.9–0.97)` + opacity (Modals are exempt — they stay centered.)

6. **Interruptibility.** Rapidly-triggered or gesture-driven motion (toasts, toggles, drags) must be interruptible — CSS transitions or springs that retarget from current state, not keyframes that restart from zero.

7. **GPU-only properties.** Animate `transform` and `opacity` only. Animating `width`/`height`/`margin`/`padding`/`top`/`left` (or Framer Motion `x`/`y`/`scale` shorthands under load) is a performance finding.

8. **Accessibility.** `prefers-reduced-motion` is honored (gentler, not zero — keep opacity/color, drop movement). Hover animations are gated behind `@media (hover: hover) and (pointer: fine)`.

9. **Asymmetric enter/exit.** Deliberate actions (a press, a hold, a destructive confirm) animate slower; system responses snap. Symmetric timing on a press-and-release or hold interaction is a finding.

10. **Cohesion.** Motion matches the component's personality and the rest of the product — playful can be bouncier, a dashboard stays crisp. Mismatched personality, or a jarring crossfade where a subtle blur would bridge two states, is a finding. When unsure whether motion feels right, the strongest move is often to delete it.

## Aggressive Escalation Triggers

Flag these on sight, hard:

- `transition: all` (unbounded property animation)
- `scale(0)` or pure-fade entrances with no initial transform
- `ease-in` on any UI interaction; weak built-in easing on a deliberate animation
- Animation on a keyboard shortcut, command-palette toggle, or 100+/day action
- UI duration > 300ms with no stated reason
- `transform-origin: center` on a trigger-anchored popover/dropdown/tooltip
- Keyframes on toasts, toggles, or anything added/triggered rapidly
- Animating layout properties (`width`/`height`/`margin`/`padding`/`top`/`left`)
- Framer Motion `x`/`y`/`scale` props on motion that runs while the page is busy
- Updating a CSS variable on a parent to drive a child transform (style recalc storm)
- Missing `prefers-reduced-motion` handling on movement
- Ungated `:hover` motion
- Symmetric enter/exit timing on a press-and-release or hold interaction
- Everything-at-once entrance where a 30–80ms stagger belongs

## Remedial Preference Hierarchy

When proposing fixes, prefer earlier moves over later ones:

1. **Delete the animation** (high-frequency / no purpose / keyboard-triggered).
2. **Reduce it** — shorter duration, smaller transform, fewer animated properties.
3. **Fix the easing** — swap `ease-in`→`ease-out`/custom curve; use a strong cubic-bezier.
4. **Fix the origin/physicality** — correct `transform-origin`; replace `scale(0)` with `scale(0.95)`+opacity.
5. **Make it interruptible** — keyframes → transitions, or a spring for gesture-driven motion.
6. **Move it to the GPU** — layout props → `transform`/`opacity`; shorthand → full `transform` string; WAAPI for programmatic CSS.
7. **Asymmetric timing** — slow the deliberate phase, snap the response.
8. **Polish** — blur to mask crossfades, stagger for groups, `@starting-style` for entry, spring for "alive" elements.
9. **Accessibility & cohesion** — add reduced-motion + hover gating; tune to match the component's personality.

## Required Output Format

Two parts, in this order.

### Part 1 — Findings table (REQUIRED)

A single markdown table. One row per issue. Never a "Before:/After:" list.

| Before | After | Why |
| --- | --- | --- |
| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; `all` animates unintended properties off-GPU |
| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing appears from nothing — `scale(0)` looks like it came from nowhere |
| `ease-in` on dropdown | `ease-out` + custom curve | `ease-in` delays the moment the user watches most; feels sluggish |
| `transform-origin: center` on popover | `var(--transform-origin)` (Base UI) | Popovers scale from their trigger, not center (modals are exempt) |

### Part 2 — Verdict (REQUIRED)

Group remaining commentary by impact tier, highest first. Omit empty tiers.

1. **Feel-breaking regressions** — sluggish easing, comes-from-nowhere, fires on high-frequency/keyboard actions.
2. **Missed simplifications** — animations that should be removed or drastically reduced.
3. **Performance** — non-GPU properties, dropped-frame risks, recalc storms.
4. **Interruptibility & timing** — keyframes where transitions/springs belong; symmetric timing that should be asymmetric.
5. **Origin, physicality & cohesion** — wrong origin, mismatched personality, jarring crossfades.
6. **Accessibility** — reduced-motion and pointer/hover gating.

Close with an explicit decision:

- **Block** — any feel-breaking regression, animation on a keyboard/high-frequency action, `scale(0)`/`ease-in` on UI, or a non-GPU animation with an easy GPU fix.
- **Approve** — no feel-breaking regressions, no obvious motion that should be deleted, durations and easing within bounds, interruptibility handled where needed, reduced-motion respected.

Be specific and cite `file:line`. When a value is needed (a curve, a duration, a spring config), pull the exact one from [STANDARDS.md](STANDARDS.md) rather than approximating.

## Guidelines

- Prefer CSS transitions/`@starting-style`/WAAPI for predetermined motion; JS/springs for dynamic, interruptible, gesture-driven motion.
- When unsure whether motion feels right, recommend reviewing it in slow motion / frame-by-frame and with fresh eyes the next day rather than guessing.
```

## File: skills/motion-architect/references/craft/standards.md
size: 10022
sha: 132f1d6308918e754f606ec0b4b0f17653b3d4eb
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/standards.md

````text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Animation Standards Reference

The precise values, curves, and rules behind the review. Cite these in findings instead of approximating. Distilled from Emil Kowalski's design engineering philosophy.

## Should it animate? (frequency table)

| Frequency | Decision |
| --- | --- |
| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |
| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
| Occasional (modals, drawers, toasts) | Standard animation |
| Rare / first-time (onboarding, feedback, celebrations) | Can add delight |

**Never animate keyboard-initiated actions** — they repeat hundreds of times daily; animation makes them feel slow and disconnected. (Raycast has no open/close animation — correct for something used hundreds of times a day.)

Valid purposes for motion: spatial consistency, state indication, explanation, feedback, preventing jarring change. "It looks cool" on a frequently-seen element is not valid.

## Easing

Decision order:
- Entering or exiting → **`ease-out`** (starts fast, feels responsive)
- Moving / morphing on screen → **`ease-in-out`**
- Hover / color change → **`ease`**
- Constant motion (marquee, progress) → **`linear`**
- Default → **`ease-out`**

**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.

Built-in CSS easings are too weak. Use strong custom curves:

```css
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
```

Find curves at [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) — don't hand-roll from scratch.

## Duration

| Element | Duration |
| --- | --- |
| Button press feedback | 100–160ms |
| Tooltips, small popovers | 125–200ms |
| Dropdowns, selects | 150–250ms |
| Modals, drawers | 200–500ms |
| Marketing / explanatory | Can be longer |

**Rule: UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. Faster spinners make load feel faster (same actual time). Instant tooltips after the first (skip delay + animation) make a toolbar feel faster.

## Physicality

- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
- **Origin-aware popovers.** Scale from the trigger, not center:
  ```css
  .popover { transform-origin: var(--transform-origin); } /* Base UI */
  ```
  **Modals are exempt** — they appear centered in the viewport, keep `transform-origin: center`.
- **Button press feedback.** `transform: scale(0.97)` on `:active`, `transition: transform 160ms ease-out`. Subtle (0.95–0.98). Applies to any pressable element.

## Springs

Feel natural because they simulate physics; no fixed duration — they settle on parameters. Use for: drag with momentum, "alive" elements (Dynamic Island), interruptible gestures, decorative mouse-tracking.

```js
// Apple-style (easier to reason about) — recommended
{ type: "spring", duration: 0.5, bounce: 0.2 }

// Traditional physics (more control)
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
```

Keep bounce subtle (0.1–0.3); avoid bounce in most UI — reserve for drag-to-dismiss and playful interactions. Springs maintain velocity when interrupted (keyframes restart from zero), so they're ideal for gestures users may reverse mid-motion.

Mouse interactions: interpolate with `useSpring` rather than tying value directly to mouse position (direct = artificial, no momentum). Only do this when the motion is decorative.

## Interruptibility

CSS **transitions** can be interrupted and retargeted mid-animation; **keyframes** restart from zero. For anything triggered rapidly (toasts being added, toggles), transitions are smoother.

```css
/* Interruptible — good for dynamic UI */
.toast { transition: transform 400ms ease; }

/* Not interruptible — avoid for dynamic UI */
@keyframes slideIn { from { transform: translateY(100%); } to { transform: translateY(0); } }
```

Use `@starting-style` for entry without JS:

```css
.toast {
  opacity: 1; transform: translateY(0);
  transition: opacity 400ms ease, transform 400ms ease;
  @starting-style { opacity: 0; transform: translateY(100%); }
}
```

Legacy fallback: `useEffect(() => setMounted(true), [])` + `data-mounted` attribute.

## Asymmetric timing

Slow where the user is deciding, fast where the system responds.

```css
.overlay { transition: clip-path 200ms ease-out; }            /* release: fast */
.button:active .overlay { transition: clip-path 2s linear; }  /* press: slow, deliberate */
```

## Performance

- **Only animate `transform` and `opacity`** — they skip layout/paint and run on the GPU. `padding`/`margin`/`height`/`width`/`top`/`left` trigger all three rendering steps.
- **Don't drive child transforms via a CSS variable on the parent** — it recalcs styles for all children. Set `transform` directly on the element.
  ```js
  element.style.setProperty('--swipe-amount', `${d}px`); // bad: recalc on all children
  element.style.transform = `translateY(${d}px)`;        // good: only this element
  ```
- **Framer Motion shorthands are NOT hardware-accelerated.** `x`/`y`/`scale` run on the main thread via rAF and drop frames under load. Use the full transform string:
  ```jsx
  <motion.div animate={{ x: 100 }} />                          // drops frames under load
  <motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
  ```
- **CSS animations beat JS under load** — they run off the main thread; rAF-based animations stutter while the browser loads/scripts/paints. Use CSS for predetermined motion, JS for dynamic/interruptible.
- **WAAPI** gives JS control with CSS performance (hardware-accelerated, interruptible, no library):
  ```js
  element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
    { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' });
  ```

## Transforms & clip-path

- **`translate` percentages** are relative to the element's own size — `translateY(100%)` moves by the element's height regardless of dimensions (how Sonner/Vaul position toasts/drawers). Prefer over hardcoded px.
- **`scale()` scales children too** (font, icons, content) — a feature for press feedback.
- **3D**: `rotateX/Y` + `transform-style: preserve-3d` for depth/orbit/flip without JS.
- **`clip-path: inset(t r b l)`** is a powerful animation tool: each value eats in from that side. Uses: reveal-on-scroll (`inset(0 0 100% 0)` → `inset(0 0 0 0)`), hold-to-delete overlay, seamless tab color transitions (duplicate + clip the active copy), comparison sliders.

## Gestures & drag

- **Momentum dismissal**: don't require crossing a distance threshold — compute velocity (`Math.abs(distance)/elapsedMs`); dismiss if `> ~0.11`. A flick should be enough.
- **Damping at boundaries**: dragging past a natural edge moves less the further you go (real things slow before stopping).
- **Pointer capture** once dragging starts, so it continues when the pointer leaves bounds.
- **Multi-touch protection**: ignore extra touch points after the drag begins (`if (isDragging) return`) — prevents jumps.
- **Friction over hard stops** — allow over-drag with rising resistance rather than an invisible wall.

## Masking imperfect crossfades

When a crossfade shows two overlapping states despite tuning easing/duration, add subtle `filter: blur(2px)` during the transition to blend them into one perceived transformation. Keep blur < 20px (heavy blur is expensive, especially Safari).

## Stagger

Stagger group entrances; 30–80ms between items. Longer delays feel slow. Stagger is decorative — never block interaction while it plays.

```css
.item { opacity: 0; transform: translateY(8px); animation: fadeIn 300ms ease-out forwards; }
.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }
@keyframes fadeIn { to { opacity: 1; transform: translateY(0); } }
```

## Accessibility

```css
@media (prefers-reduced-motion: reduce) {
  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
}
@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); } /* gate hover motion — touch fires false hovers on tap */
}
```

```jsx
const reduce = useReducedMotion();
const closedX = reduce ? 0 : '-100%';
```

Reduced motion means fewer and gentler animations, not zero — keep transitions that aid comprehension, remove movement/position changes.

## Debugging (recommend in reviews when feel is uncertain)

- **Slow motion**: bump duration 2–5× or use DevTools animation inspector. Check colors crossfade cleanly, easing doesn't stop abruptly, `transform-origin` is right, coordinated properties stay in sync.
- **Frame-by-frame**: Chrome DevTools Animations panel reveals timing drift between coordinated properties.
- **Real devices** for gestures (drawers, swipe) — connect a phone, hit the dev server by IP, use Safari remote devtools.
- **Fresh eyes next day** — imperfections invisible during development surface later.

## Cohesion

Match motion to the component's personality: playful can be bouncier; a professional dashboard should be crisp and fast. Sonner feels right partly because easing, duration, design, and even the name are in harmony — slightly slower, `ease` rather than `ease-out`, to feel elegant. Opacity + height in entering/exiting lists is trial and error; there's no formula — adjust until it feels right.
````

## File: skills/motion-architect/references/craft/vocabulary.md
size: 12869
sha: 690b0e6074946856aebee20b4a80c48c2144be9b
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/craft/vocabulary.md

````text
> Referencia interna de Motion Architect. Está escrita para interfaces web; en video aplica igual: donde diga CSS transition/keyframes, usa `interpolate`/`spring` de Remotion y las curvas de `studio/src/lib/motion.ts`.

# Animation Vocabulary

Turn a vague description of a motion or effect into the precise term, so the user knows what to ask for.

## Quick Start

The user describes an effect loosely. You return the matching term(s) in this format:

```
**Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
```

If several terms could fit, list the best match first, then 1–2 alternates with a one-line note on how they differ.

## Instructions

1. **Read for intent, not keywords.** Users describe what they *see* or *feel* ("springy", "slides off", "draws itself in"), not the technical name. Map the sensation to the glossary below.
2. **Quote the glossary verbatim.** Its descriptions are authoritative — use them as-is, don't paraphrase.
3. **Disambiguate close terms.** When two compete (*Clip-path* vs *Mask*, *Pop in* vs *Bounce*, *Shared element transition* vs *Layout animation*), contrast them so the user can pick.
4. **When nothing matches exactly,** name the closest term and say plainly it's an approximation, or describe the effect in the glossary's vocabulary (e.g. "that's a *stagger* of *scale-in* entrances").
5. **Stay within this glossary.** If a term genuinely isn't here, say so rather than inventing one — though you may explain the concept using these words.
6. **Keep it tight.** A naming question wants a name, not an essay. Lead with the term; expand only if asked.

## Examples

**Example 1 — feel-based**
User: "What's it called when a popover seems to grow out of the button you clicked instead of from its middle?"
Output:
```
**Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.
```

**Example 2 — disambiguation**
User: "The thing where one image turns into another image."
Output:
```
**Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.

Close alternates:
- **Crossfade** — if they simply fade over each other in the same spot.
- **Shared element transition** — if an element travels and transforms from one position into another.
```

**Example 3 — physics feel**
User: "That iOS scroll where it resists and snaps back when you pull too far."
Output:
```
**Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
```

## Glossary

_A curated snapshot mirroring the project's `/vocabulary` page; keep the two in sync when either changes._

### Entrances & Exits — how elements appear and disappear
- **Fade in / Fade out** — Element appears or disappears by changing opacity.
- **Slide in** — Element enters by sliding in from off-screen (left, right, top, or bottom).
- **Scale in** — Element grows from smaller to full size as it appears, often paired with a fade.
- **Pop in** — Element appears with a slight overshoot, like it bounces into place.
- **Reveal** — Content is uncovered gradually, often by animating a clip-path or mask.
- **Enter / Exit** — The animation an element plays when it's added to or removed from the screen.

### Sequencing & Timing — coordinating multiple elements or moments
- **Keyframes** — Defined points in an animation (0%, 50%, 100%) that the browser fills the gaps between.
- **Interpolation / Tween** — Generating all the in-between frames between a start and end value, so motion is continuous.
- **Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
- **Orchestration** — Deliberately timing multiple animations so they feel like one coordinated motion.
- **Delay** — Time before an animation starts.
- **Duration** — How long an animation takes.
- **Fill mode** — Whether an element keeps its first or last frame's styles before the animation starts or after it ends (e.g. forwards).
- **Stepped animation** — An animation that is divided into discrete steps, like a countdown timer.

### Movement & Transforms — changing an element's position, size, or angle
- **Translate** — Move an element along the X or Y axis.
- **Scale** — Make an element bigger or smaller.
- **Rotate** — Spin an element around a point.
- **Skew** — Slant an element along the X or Y axis, shearing it out of its rectangular shape.
- **3D tilt / Flip** — Rotate in 3D space (rotateX / rotateY) to add depth.
- **Perspective** — How strong the 3D effect looks — a lower value exaggerates depth, like the viewer is closer.
- **Transform origin** — The anchor point a scale or rotation grows or spins from.
- **Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.

### Transitions Between States — connecting one state, view, or element to another
- **Crossfade** — One element fades out as another fades in, in the same spot.
- **Continuity transition** — A change that keeps the user oriented by visually connecting before and after. For example, making the same rectangle bigger and smaller.
- **Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.
- **Shared element transition** — An element travels and transforms from one position into another, like a thumbnail expanding into a card.
- **Layout animation** — When an element's size or position changes, it animates to the new spot instead of snapping.
- **Accordion / Collapse** — A section smoothly expands and collapses its height to show or hide content.
- **Direction-aware transition** — Content slides one way going forward and the opposite way going back, so navigation has a sense of direction.

### Scroll — motion tied to scrolling or navigating between views
- **Scroll reveal** — Elements fade or slide into place as they enter the viewport.
- **Scroll-driven animation** — An animation whose progress is tied directly to scroll position.
- **Parallax** — Background and foreground move at different speeds while scrolling, creating depth.
- **Page transition** — An animation that plays when navigating from one page or route to another.
- **View transition** — The browser morphs between two states or pages, connecting shared elements.

### Feedback & Interaction — responding to the user's actions
- **Hover effect** — Visual change when the cursor moves over an element.
- **Press / Tap feedback** — A subtle scale-down when an element is clicked, so it feels physical.
- **Hold to confirm** — A progress effect that fills up while the user holds a button.
- **Drag** — Moving an element by grabbing it, often with momentum when released.
- **Drag to reorder** — Dragging items in a list to rearrange them, while the others shift to make room.
- **Swipe to dismiss** — Dragging an element off-screen to close it, like a drawer or toast.
- **Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
- **Shake / Wiggle** — A quick side-to-side jitter signaling an error or rejected input.
- **Ripple** — A circle expanding from the point of a tap, confirming the press.

### Easing — how speed changes over an animation
- **Easing** — The rate at which an animation speeds up or slows down.
- **Ease-out** — Starts fast, ends slow. The default for most UI and anything responding to the user.
- **Ease-in** — Starts slow, ends fast. Usually avoided; can feel sluggish.
- **Ease-in-out** — Slow, fast, slow. Good for elements already on screen moving from A to B.
- **Linear** — Constant speed. Avoid for UI; reserve for spinners or marquees.
- **Cubic-bezier** — A custom easing curve you define for precise control.
- **Asymmetric easing** — A curve that accelerates and decelerates at different rates. Feels more alive than a symmetric one.

### Spring Animations — physics-based motion as an alternative to fixed-duration easing
- **Spring** — Motion driven by physics (tension, mass, damping) rather than a set duration.
- **Stiffness / Tension** — How strongly the spring pulls toward its target. Higher feels snappier.
- **Damping** — How quickly a spring settles. Lower damping means more bounce and oscillation.
- **Mass** — How heavy the animated element feels. More mass makes it slower and more sluggish.
- **Bounce** — A spring that overshoots and settles, adding playfulness.
- **Perceptual duration** — How long a spring feels finished, even though it keeps micro-settling underneath.
- **Momentum** — Motion that carries velocity, especially after a drag or interruption.
- **Velocity** — How fast and in which direction an element is moving. A spring carries it into the next animation when interrupted, so a flicked element keeps its speed.
- **Interruptible animation** — An animation that can be smoothly redirected mid-flight instead of finishing first.

### Looping & Ambient Motion — animations that run on their own
- **Marquee** — Text or content that scrolls continuously in a loop.
- **Loop** — An animation that repeats, a set number of times or infinitely.
- **Alternate (yoyo)** — A loop that plays forward then reverses each iteration, instead of jumping back to the start.
- **Orbit** — An element circling around another in a continuous path.
- **Pulse** — A gentle repeating scale or opacity change to draw attention.
- **Float** — A gentle, continuous up-and-down drift that makes a static element feel alive and weightless.
- **Idle animation** — Subtle motion that plays while an element is just sitting there, waiting to be interacted with.

### Polish & Effects — the small touches that separate good from great
- **Blur** — A blur filter used to soften an element or mask tiny imperfections.
- **Clip-path** — Clipping an element to a shape, used for reveals, masks, and before/after sliders.
- **Mask** — Hiding or revealing parts of an element using a shape or gradient — like clip-path, but with soft, fadeable edges.
- **Before / after slider** — A draggable divider that wipes between two overlaid images to compare them.
- **Line drawing** — An SVG path that draws itself in, like an invisible pen tracing it.
- **Text morph** — Text that animates character by character when it changes, drawing attention to the new value.
- **Skeleton / Shimmer** — A placeholder with a moving sheen shown while content loads.
- **Number ticker** — Digits rolling or counting up to a value.
- **Tabular numbers** — Fixed-width digits so numbers don't shift around as they change. Essential for tickers, timers, and counters.
- **Typewriter** — Text appearing one character at a time, as if being typed.

### Performance — what keeps motion smooth instead of stuttering
- **Frame rate (FPS)** — Frames drawn per second. 60fps is the baseline for smooth motion; 120fps on newer displays.
- **Jank** — Visible stutter when the browser drops frames because it can't keep up with the animation.
- **Dropped frame** — A frame the browser missed its deadline to draw, causing a tiny hitch in motion.
- **Compositing** — Letting the GPU move or fade an element on its own layer without redoing layout or paint.
- **will-change** — A CSS hint that an element is about to animate, so the browser can promote it to its own layer ahead of time.
- **Layout thrashing** — Animating properties like width, height, top, or left that force the browser to recalculate layout every frame, causing jank.

### Principles to Know — concepts that guide when and how to animate
- **Purposeful animation** — Motion should serve a function — orient, give feedback, show relationships — not just decorate.
- **Anticipation** — A small wind-up in the opposite direction before a move, hinting at what's about to happen.
- **Follow-through** — Parts of an element keep moving and settle slightly after the main motion stops, adding weight.
- **Squash & stretch** — Deforming an element as it moves to convey weight, speed, and flexibility.
- **Perceived performance** — The right animation makes an interface feel faster, even when it isn't.
- **Frequency of use** — The more often a user sees an animation, the shorter and subtler it should be.
- **Spatial consistency** — Animating so an element keeps its identity and position across states, so users never lose track of where things went.
- **Hardware acceleration** — Animating transform and opacity lets the GPU keep motion smooth.
- **Reduced motion** — Respecting the user's prefers-reduced-motion setting by toning down or removing motion.
````

## File: skills/motion-architect/references/design-engine.md
size: 1248
sha: 8ef1b8bc735b3c169dc657b87cbd3587d88f899b
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/design-engine.md

````text
# Motor de diseño

Base de datos local de estilos, paletas, pares tipográficos y patrones visuales. No necesita internet ni dependencias: solo Python 3.

```bash
python3 <skill-dir>/engine/design/scripts/search.py "<producto> <industria> <mood>" --design-system -p "<Nombre>"
python3 <skill-dir>/engine/design/scripts/search.py "<mood>" --domain color -n 5
python3 <skill-dir>/engine/design/scripts/search.py "<mood>" --domain typography -n 5
python3 <skill-dir>/engine/design/scripts/search.py "<mood>" --domain google-fonts -n 5
python3 <skill-dir>/engine/design/scripts/search.py "<estilo>" --domain style
```

## Cómo usarlo para video
- `--design-system` te da estilo, paleta, tipografía y efectos de un jalón. Ignora lo que sea de web (secciones, formularios, navegación) y quédate con color, tipo, estilo y mood.
- Pasa la paleta a `studio/brand.json` y las fuentes a `studio/src/brand/brand.ts` (ver `brand.md`). Revisa que la fuente exista en `@remotion/google-fonts`.
- `--domain style` describe el carácter visual. Tradúcelo a movimiento: brutalism = cortes duros; glassmorphism = blur y capas; minimal = mucho aire y entradas lentas.
- Reglas rápidas de contraste y jerarquía: `<skill-dir>/engine/design/quick-reference.md`.
````

## File: skills/motion-architect/references/formats.md
size: 1735
sha: f775d36795f921c776207914d83cba56a40ce992
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/formats.md

````text
# Formatos

| Nombre | Tamaño | Uso | Id de composición |
|---|---|---|---|
| `landscape` | 1920×1080 (16:9) | YouTube, web, presentaciones | `<Id>-landscape` |
| `vertical` | 1080×1920 (9:16) | Reels, TikTok, Shorts, Stories | `<Id>-vertical` |
| `square` | 1080×1080 (1:1) | Feed, LinkedIn | `<Id>-square` |
| `portrait` | 1080×1350 (4:5) | Feed de Instagram | `<Id>-portrait` |

Todos van a 30 fps, h264 y yuv420p (configurado en `studio/remotion.config.ts`). Se definen en `studio/src/lib/formats.ts`.

## Safe zones
- **9:16**: deja libre el 14 % superior (usuario y audio) y el 20 % inferior (caption, botones). Tampoco pongas nada en los ~120 px de la derecha, donde van los íconos de like y comentario. `SafeArea` ya aplica los márgenes de arriba y abajo.
- **16:9**: margen de 80–96 px. Los títulos pueden ir alineados a la izquierda para un look editorial.
- **1:1 y 4:5**: margen de 96 px. El texto es un poco más chico que en 9:16.

## Diseño multi-formato
- Usa `useScale()`: `u` = lado corto / 1080. Escribe tamaños como `120 * u`.
- Usa `isVertical` e `isLandscape` para cambiar el layout: filas en horizontal, columnas en vertical.
- Revisa un still por formato. No asumas que si funciona en uno funciona en todos.

## Comandos
```bash
cd studio
npx remotion render src/index.ts <Id>-vertical out/<id>-vertical.mp4
npx remotion render src/index.ts <Id>-vertical out/<id>-vertical.mp4 --crf=16       # más calidad
npx remotion render src/index.ts <Id>-vertical out/<id>-vertical.gif --codec=gif --every-nth-frame=2 # GIF
npx remotion render src/index.ts <Id>-vertical out/<id>.mov --codec=prores --prores-profile=4444 # con alfa
npx remotion still  src/index.ts <Id>-vertical out/frame.png --frame=45
```
````

## File: skills/motion-architect/references/intake.md
size: 1323
sha: 3cb969ec4cd986a9861e0f80895725f06b151534
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/intake.md

```text
# Intake

Haz todas estas preguntas **en un solo mensaje**. Lo que no respondan, se asume con el default y se dice en una línea.

| # | Pregunta | Default |
|---|---|---|
| 1 | ¿Qué cuenta el video? (producto, anuncio, intro de canal, dato, lanzamiento, logo) | — (obligatorio) |
| 2 | ¿Formato? horizontal 16:9 · vertical 9:16 · cuadrado 1:1 · 4:5 feed · varios | vertical 9:16 |
| 3 | ¿Duración? | 15 s (rango sano: 6–30 s) |
| 4 | ¿Tono? default · polished · cinematic · chaotic · deadpan · app-store · editorial · o libre | default |
| 5 | ¿Tienes referencias? Videos (URL o archivo), imágenes, capturas | ninguna |
| 6 | ¿Marca? Logo, colores, fuentes, o "usa la de este sitio/imagen" | brand.json actual |
| 7 | ¿Texto exacto que debe salir? (nombre, claim, CTA, URL) | lo propones tú |
| 8 | ¿Música y SFX? ¿Tienes pista? | sin audio |

## Cómo leer las respuestas
- "Para Reels/TikTok/Shorts" significa 9:16. "Para YouTube o una presentación" significa 16:9. "Para el feed" significa 4:5.
- "Como este video" quiere decir que la persona quiere **el ritmo y el lenguaje de movimiento** de la referencia, no una copia. Extrae el motion spec y aplícalo con su marca.
- Si dicen "varios formatos", diseña primero para el más restrictivo (9:16) y luego verifica los demás con stills.
```

## File: skills/motion-architect/references/motion-principles.md
size: 2714
sha: 07915bc573f0a4dce13903eaf62bcfba16b5104e
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/motion-principles.md

```text
# Principios de movimiento

El resumen operativo para video. La versión completa está en `craft/` (filosofía, estándares, recetas y vocabulario).

## Easing
- **Entradas: ease-out.** Arrancan rápido y frenan suave, se sienten responsivas. Usa `ease.out` = `bezier(0.23, 1, 0.32, 1)`.
- **Movimiento dentro de pantalla: ease-in-out.** Usa `ease.inOut` = `bezier(0.77, 0, 0.175, 1)`.
- **Salidas: ease-in, y más cortas que la entrada** (más o menos el 70 % de su duración).
- **Lineal** solo para cosas constantes: rotación continua, progreso, contadores de reloj.
- Las curvas que vienen por defecto en CSS son débiles. Usa las de `lib/motion.ts`.

## Springs
- `springs.smooth` (sin rebote) es el default para todo lo serio.
- `springs.snappy` para tarjetas, botones y logos: rebote mínimo.
- `springs.bouncy` solo en tonos juguetones. Más de un rebote visible se siente barato.

## Escala y aparición
- Nunca `scale(0)`. Arranca entre 0.9 y 0.96 combinado con opacidad. En la vida real nada aparece de la nada.
- Opacidad + translateY de 16–40 px + blur de 4–8 px es la entrada base (`enterStyle`).
- Ojo con el `transform-origin`: si algo sale de un punto (un botón, una esquina), escala desde ahí.

## Timing (a 30 fps)
| Qué | Frames | Segundos |
|---|---|---|
| Micro (chip, icono) | 8–12 | 0.27–0.4 |
| Entrada de texto por palabra | 14–20 | 0.45–0.65 |
| Stagger entre palabras | 3–5 | 0.1–0.17 |
| Stagger entre tarjetas | 6–10 | 0.2–0.33 |
| Transición entre escenas | 10–18 | 0.33–0.6 |
| Hold mínimo de un titular | 30 + 3/letra | — |

## Jerarquía y foco
- Una sola cosa se mueve "en grande" a la vez. Lo demás espera o se queda quieto.
- El ojo sigue al movimiento. Mueve primero lo que quieres que se lea primero.
- Stagger con intención: el orden de entrada es el orden de lectura.

## Pulido que se nota sin verse
- `fontVariantNumeric: "tabular-nums"` en contadores, para que el ancho no baile.
- `letterSpacing` negativo (−0.02 a −0.05em) en titulares grandes.
- Sombras suaves y grandes en lugar de bordes duros.
- Pequeño drift de fondo (Background) para que la toma no se sienta congelada.
- Nada de easing "elástico" en texto largo.

## Checklist de revisión (estilo review-animations)
Entrega una tabla Antes | Después | Por qué para cada problema que encuentres:
1. ¿Alguna entrada usa ease-in o lineal?
2. ¿Algo escala desde 0 o aparece de golpe sin motivo?
3. ¿Se mueven varias cosas grandes a la vez?
4. ¿Algún texto está en pantalla menos de lo que tarda en leerse?
5. ¿Las salidas son más lentas que las entradas? Al revés de lo correcto.
6. ¿Hay algo en la safe zone de 9:16?
7. ¿El contraste de texto llega a 4.5:1?
```

## File: skills/motion-architect/references/references-from-video.md
size: 1906
sha: 9ca3cd595496f7cae1fd502a275a52a9befe8a68
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/references-from-video.md

````text
# Referencias desde video

La persona puede pasar una URL (YouTube, Instagram, TikTok, X; lo que soporte yt-dlp) o un archivo local.

## Cómo verlas
1. Usa el **motor de visión** (`vision.md`): `python3 <skill-dir>/engine/vision/analyze.py "<url-o-ruta>" --engine local`. Lee con Read los frames que devuelve.
   - Para movimiento fino: `--detail token-burner` o acota con `--start 0:05 --end 0:12 --fps 6`.
   - Sin llave de transcripción: `--no-whisper`.
2. Para medir cortes exactos también puedes usar ffmpeg:
   ```bash
   ffmpeg -i ref.mp4 -vf "select='gt(scene,0.3)',showinfo" -vsync vfr /tmp/cut_%03d.jpg 2>&1 | grep -o "pts_time:[0-9.]*"
   ```
3. Si hay varios videos, despacha el subagente `reference-analyst` (uno por video, en paralelo).

## Qué extraer (motion spec)
```json
{
  "fuente": "url o ruta",
  "duracion_s": 14.2,
  "formato": "9:16",
  "cortes_s": [0, 1.8, 3.1, 5.0],
  "ritmo": "rápido: escenas de 1.2–2 s, cortes en el beat",
  "paleta": ["#0E0E10", "#F2F2F2", "#C6FF3D"],
  "tipografia": "grotesk pesada, mayúsculas, tracking apretado",
  "movimientos": ["texto entra por máscara de abajo", "zoom-in lento sobre producto", "tarjetas en stagger"],
  "easing_percibido": "ease-out fuerte, sin rebote",
  "transiciones": ["corte duro", "whip-pan"],
  "audio": "beat electrónico ~120 bpm, SFX en cada corte",
  "lo_que_hace_que_funcione": "una palabra por beat y contraste brutal",
  "aplicar_a_nuestro_video": ["usar ritmo de 1.5 s", "máscara de abajo en KineticTitle"]
}
```

## Reglas
- Se toma el **lenguaje** (ritmo, estructura, tipo de movimiento), no el contenido ni los assets de la referencia.
- Copia los frames útiles a `studio/public/references/` solo como referencia de trabajo. No van en el video final a menos que sean de la persona.
- Estima el easing por la distancia entre frames consecutivos: mucho movimiento al inicio y poco al final es ease-out.
````

## File: skills/motion-architect/references/remotion-patterns.md
size: 3290
sha: 4d9a1ac422cb5292b5874fc0573f8d857cda3b01
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/remotion-patterns.md

````text
# Patrones de Remotion

Para la API completa: https://www.remotion.dev/docs (la búsqueda de la doc funciona bien con WebFetch).

## Reglas de oro
- **Todo se anima con `useCurrentFrame()`.** Nada de CSS transitions, `@keyframes`, `setTimeout` ni `requestAnimationFrame`: no se renderizan.
- **Determinismo**: nada de `Math.random()`. Usa `random("seed")` de `remotion`.
- **Assets** en `studio/public/`, referenciados con `staticFile("references/logo.png")`.
- Imágenes con `<Img>`, video con `<OffthreadVideo>`, audio con `<Audio>`. Todo se importa de `remotion`.

## Esqueleto de una composición
```tsx
import { linearTiming, TransitionSeries } from "@remotion/transitions";
import { fade } from "@remotion/transitions/fade";
import { AbsoluteFill } from "remotion";
import { Background, KineticTitle, LogoReveal, SafeArea } from "../components";

const T = 12;
export const MI_VIDEO_DURATION = 75 + 90 - T;

export const MiVideo: React.FC = () => (
  <AbsoluteFill>
    <Background />
    <TransitionSeries>
      <TransitionSeries.Sequence durationInFrames={75}>
        <SafeArea><KineticTitle text="Hook aquí." highlight={["Hook"]} /></SafeArea>
      </TransitionSeries.Sequence>
      <TransitionSeries.Transition presentation={fade()} timing={linearTiming({ durationInFrames: T })} />
      <TransitionSeries.Sequence durationInFrames={90}>
        <SafeArea><LogoReveal /></SafeArea>
      </TransitionSeries.Sequence>
    </TransitionSeries>
  </AbsoluteFill>
);
```
Después regístrala en `src/compositions/index.ts`:
```ts
{ id: "MiVideo", component: MiVideo, durationInFrames: MI_VIDEO_DURATION, formats: ["vertical", "landscape"] },
```

## Piezas clave
- `interpolate(frame, [a, b], [x, y], { easing, extrapolateLeft: "clamp", extrapolateRight: "clamp" })`. Siempre con clamp.
- `spring({ frame: frame - delay, fps, config })` devuelve un valor de 0 a 1 (puede pasarse de 1 si hay rebote).
- `<Sequence from={30} durationInFrames={60}>`: dentro, `useCurrentFrame()` arranca en 0.
- `<Series>` para escenas sin solape y `<TransitionSeries>` para escenas con transición. Las transiciones restan duración.
- Transiciones disponibles en `@remotion/transitions/*`: `fade`, `slide`, `wipe`, `flip`, `clockWipe`, `iris`.

## Componentes del kit (`src/components`)
| Componente | Para qué | Props clave |
|---|---|---|
| `Background` | Fondo de marca con brillo que deriva | `glow` |
| `SafeArea` | Márgenes por formato | `align` |
| `KineticTitle` | Texto palabra por palabra | `text`, `delay`, `stagger`, `size`, `highlight` |
| `LogoReveal` | Símbolo + nombre con máscara | `name`, `tagline`, `delay` |
| `Counter` | Número que sube | `to`, `prefix`, `suffix`, `label` |
| `CardStack` | Tarjetas una por una | `cards`, `stagger` |
| `Caption` | Chip, kicker o lower-third | `text`, `tone` |
| `ImagePan` | Ken Burns sobre imagen | `src`, `zoomFrom`, `zoomTo`, `overlay` |

## Video de la persona dentro de la composición
```tsx
import { OffthreadVideo, staticFile } from "remotion";
<OffthreadVideo src={staticFile("references/clip.mp4")} startFrom={30} muted />
```

## Fuentes
`@remotion/google-fonts/<NombreSinEspacios>` con `loadFont("normal", { weights: [...], subsets: ["latin"] })`. Las fuentes locales van con `@font-face` y `staticFile`. Revisa `brand.md`.
````

## File: skills/motion-architect/references/sfx-library.md
size: 7055
sha: a2015c62725721a1de95055fbcf91befaca17aef
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/sfx-library.md

```text
# SFX Analysis Summary

Source: [Kenney](https://kenney.nl/).

Use this as planning guidance for choosing tasteful SFX. Prefer low/medium high-frequency risk sounds for polished videos; reserve bright/high-risk files for tiny accents, chaotic tones, or deliberate glitches.

## Signal Guide

- `brightness`: warm / balanced / bright, based on spectral centroid and high-frequency energy.
- `highFrequencyRisk`: low / medium / high. High-risk SFX can feel sharp, hissy, clicky, or fatiguing if repeated.
- `brightBurden`: high-frequency energy weighted by level and duration. This separates sustained glassy ringing from short clicks.
- `highActiveDuration`: how long bright energy stays active above a useful level.
- `envelopeShape`: transient / textured / continuous. Continuous bright sounds are more fatiguing than sparse textured sounds.
- `transient.sharpness`: higher values feel clickier or more percussive.
- `duration`: short sounds work for UI and typing; longer sounds work for reveals and transitions.

## Safest General Picks

- `impact/impactSoft_medium_001.ogg` — 0.18s, warm, low HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_medium_004.ogg` — 0.15s, warm, low HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_medium_002.ogg` — 0.14s, warm, low HF risk, transient; use for hard transition, major reveal
- `interface/bong_001.ogg` — 0.12s, warm, low HF risk, textured; use for general accent
- `impact/impactSoft_medium_003.ogg` — 0.14s, warm, low HF risk, textured; use for hard transition, major reveal
- `impact/impactSoft_medium_000.ogg` — 0.12s, warm, low HF risk, textured; use for hard transition, major reveal
- `interface/click_003.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
- `interface/click_002.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
- `interface/click_005.ogg` — 0.01s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
- `ui/click2.ogg` — 0.06s, balanced, low HF risk, continuous; use for button press, selection, simulated user action
- `ui/rollover2.ogg` — 0.06s, balanced, low HF risk, continuous; use for general accent
- `interface/glitch_002.ogg` — 0.03s, bright, low HF risk, continuous; use for chaotic accent, comedic interruption, tiny accent only
- `impact/impactSoft_heavy_003.ogg` — 0.54s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_heavy_004.ogg` — 0.50s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_heavy_002.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_heavy_001.ogg` — 0.57s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactSoft_heavy_000.ogg` — 0.51s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/footstep_wood_004.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
- `impact/footstep_wood_002.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
- `impact/footstep_wood_000.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
- `impact/footstep_wood_001.ogg` — 0.25s, warm, medium HF risk, transient; use for general accent
- `impact/impactWood_medium_003.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactWood_medium_001.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal
- `impact/impactWood_medium_000.ogg` — 0.33s, warm, medium HF risk, transient; use for hard transition, major reveal

## Lower-Risk Picks By Use Case

- button press: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
- selection: `interface/click_003.ogg` (low), `interface/click_002.ogg` (low), `interface/click_005.ogg` (low), `ui/click2.ogg` (low), `interface/click_001.ogg` (medium)
- toggle: `interface/switch_007.ogg` (medium), `interface/switch_002.ogg` (medium), `interface/switch_006.ogg` (medium), `interface/switch_005.ogg` (medium), `ui/switch11.ogg` (medium)
- card reveal: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
- swipe: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
- sequential item: `casino/card-slide-1.ogg` (medium), `casino/card-place-1.ogg` (high), `casino/card-fan-2.ogg` (high), `casino/card-slide-8.ogg` (high), `casino/card-slide-3.ogg` (high)
- panel opening: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
- soft reveal: `casino/cards-pack-open-1.ogg` (high), `casino/cards-pack-open-2.ogg` (high)
- success: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
- logo payoff: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
- reveal confirmation: `impact/impactBell_heavy_000.ogg` (medium), `impact/impactBell_heavy_003.ogg` (medium), `impact/impactBell_heavy_004.ogg` (medium)
- major reveal: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
- hard transition: `impact/impactSoft_medium_001.ogg` (low), `impact/impactSoft_medium_004.ogg` (low), `impact/impactSoft_medium_002.ogg` (low), `impact/impactSoft_medium_003.ogg` (low), `impact/impactSoft_medium_000.ogg` (low)
- chaotic accent: `interface/glitch_002.ogg` (low), `interface/error_005.ogg` (medium), `interface/error_006.ogg` (medium), `interface/glitch_004.ogg` (medium)

## Family Summary

- `casino/`: 51 files; HF risk low/medium/high = 0/10/41; avg high-frequency energy 0.59
- `impact/`: 109 files; HF risk low/medium/high = 5/104/0; avg high-frequency energy 0.08
- `interface/`: 20 files; HF risk low/medium/high = 5/14/1; avg high-frequency energy 0.25
- `ui/`: 48 files; HF risk low/medium/high = 2/14/32; avg high-frequency energy 0.57

## Selection Rules

- Prefer low-risk SFX for repeated UI actions, text ticks, and dense sequences.
- Use medium-risk SFX for isolated reveals or when the motion needs a crisp edge.
- Avoid high-risk SFX for repeated ticks, long sequences, or polished/deadpan tones.
- Treat continuous bright SFX as more fatiguing than sparse/textured bright SFX.
- If using a bright SFX, keep it short, quiet, and isolated.
- Match SFX timing to the visual landing or start depending on the gesture: clicks at press/start, reveals at resolution/payoff.
```

## File: skills/motion-architect/references/storyboard.md
size: 1682
sha: 54fae00d6439dcf15183951ff5442077103fca2a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/storyboard.md

````text
# Storyboard

Un storyboard es una página. Es la estrella polar del video.

## Estructura por defecto
```
Hook (2–3 s) → Reveal → 2–3 Highlights → Punchline / Outro
```
- **Hook**: el momento más importante. ¿Qué palabra, imagen o movimiento se gana los siguientes 15 segundos?
- **Reveal**: qué es o quién es (nombre, logo).
- **Highlights**: uno por escena. Concretos ("el contador sube a 10,000"), no genéricos ("features").
- **Outro**: el remate, el nombre y el CTA. Que respire.

Adáptalo: un intro de canal puede ser solo Hook → Reveal, y un dato animado puede ser Hook → Counter → Outro.

## Plantilla (`studio/storyboards/<id>.md`)
```markdown
# <Título>
- Formato(s): vertical 1080x1920 [+ …]
- Duración: <s> s = <frames> frames @30fps
- Tono: <preset> — <una línea de interpretación>
- Referencias: <motion spec resumido o "ninguna">
- Marca: bg <hex> · texto <hex> · acento <hex> · display <fuente> · body <fuente>

## Escena 1 — Hook — 0–75 (2.5 s)
En pantalla: <qué se ve, texto exacto>
Movimiento: <componente + cómo entra: KineticTitle stagger 4, ease.out>
Transición → 2: <fade 12f / slide from-bottom / corte>
Audio: <whoosh suave en f60 / nada>

## Escena 2 — …
```

## Duración
- Suma las escenas y resta los frames de transición (las de `TransitionSeries` se solapan). Haz la cuenta.
- Rango sano: 6–30 s. Para redes, el punto ideal está entre 12 y 20 s.
- Por escena: 2–5 s. Menos de 1.5 s solo en tono `chaotic`.

## Antes de pedir aprobación
- ¿El hook se entiende en silencio y sin contexto?
- ¿Cada escena tiene una sola idea?
- ¿Todo el texto se puede leer en el tiempo que está en pantalla?
````

## File: skills/motion-architect/references/tones.md
size: 1390
sha: 0795a80c7c4888bcee6aee2841f8f26e119b3790
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/tones.md

```text
# Tonos

Presets traducidos a parámetros de Remotion. Cada tono cambia el ritmo, la tipografía y las transiciones.

| Tono | Escenas (15–20 s) | Por escena | Tipografía | Springs / easing | Transiciones |
|---|---|---|---|---|---|
| `default` | 4–5 | 3–5 s | Mixed case, peso 700–800 | `springs.snappy`, `ease.out` | fade 10–12 f, slide |
| `polished` | 3–4 | 4–6 s | Peso 400–600, tracking amplio | `springs.smooth`, entradas de 24–30 f | fade lento 18–24 f |
| `cinematic` | 4–5 | 3–5 s | Muy grande, serif o display condensada | `ease.inOut`, zooms lentos (ImagePan) | fade a negro, cross-zoom |
| `chaotic` | 6–8 | 0.7–2 s | MAYÚSCULAS, 800+, palabras rotadas | `springs.bouncy`, stagger 2 f | cortes duros, slide rápido 6 f |
| `deadpan` | 3–4 | 4–6 s | Una palabra a la vez, mucho vacío | lineal o `ease.out` muy corto | corte seco |
| `app-store` | 4–6 | 2.5–4 s | Limpia, sans, 600–700 | `springs.snappy`, CardStack | slide horizontal, fade |
| `editorial` | 4–5 | 3–4 s | Serif display + sans, alineado a la izquierda | `ease.out`, máscaras (clipPath) | wipe, fade |

## Tono libre
Si te dan algo como "tipo keynote de Apple" o "como anuncio de los 90", escribe una línea de interpretación en el storyboard: "pausas largas, fondo negro, texto blanco centrado, una idea por pantalla". Luego elige el preset más cercano como base.
```

## File: skills/motion-architect/references/vision.md
size: 1309
sha: cf59a77d35dd53d11eda80c2641b4a9be146d014
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/references/vision.md

````text
# Motor de visión

Ve videos de forma local: los descarga con yt-dlp si son URL, saca frames con ffmpeg (scene-aware) y trae los subtítulos si existen.

```bash
python3 <skill-dir>/engine/vision/setup.py --check        # exit 0 = listo; 2 = falta ffmpeg/yt-dlp → ./install.sh
python3 <skill-dir>/engine/vision/analyze.py "<url-o-ruta>" --engine local
```

Después, **lee con Read las rutas de frames** que imprime el reporte. Así es como ves el video.

## Flags útiles
| Flag | Uso |
|---|---|
| `--engine local` | **Siempre.** Todo se procesa en la máquina |
| `--detail efficient\|balanced\|token-burner` | Pocos frames, normal (default) o sin tope (para movimiento fino) |
| `--start 0:05 --end 0:12` | Solo un tramo |
| `--fps 6` | Más frames por segundo en el tramo (para medir easing) |
| `--no-whisper` | No intentar transcribir el audio |
| `--question "..."` | Pregunta concreta que quieres responder con el video |

## Transcripción (opcional)
Si el video no tiene subtítulos, el motor puede transcribir con Whisper si la persona configuró una llave en `~/.config/motion-architect/.env` (`GROQ_API_KEY=` u `OPENAI_API_KEY=`). Sin llave, usa `--no-whisper`: para analizar movimiento bastan los frames. Nunca pidas ni imprimas la llave; si la quieren configurar, diles en qué archivo va.
````

## File: skills/motion-architect/engine/design/data/app-interface.csv
size: 11046
sha: 95e328c807a23be02c9c32c736d0fa19109c6076
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/app-interface.csv

```text
No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
1,Accessibility,Icon Button Labels,icon button accessibilityLabel,iOS/Android/React Native,Icon-only buttons must expose an accessible label,Set accessibilityLabel or label prop on icon buttons,Icon buttons without accessible names,"<Pressable accessibilityLabel=""Close""><XIcon /></Pressable>",<Pressable><XIcon /></Pressable>,Critical
2,Accessibility,Form Control Labels,form input label accessibilityLabel,iOS/Android/React Native,All inputs must have a visible label and an accessibility label,Pair Text label with input and set accessibilityLabel,Inputs with placeholder only,"<View><Text>Email</Text><TextInput accessibilityLabel=""Email address"" /></View>","<TextInput placeholder=""Email"" /></View>",Critical
3,Accessibility,Role & Traits,accessibilityRole accessibilityTraits,iOS/Android/React Native,Interactive elements must expose correct roles/traits,Use accessibilityRole/button/link/checkbox etc.,Rely on generic views with no roles,"<Pressable accessibilityRole=""button"">Submit</Pressable>",<View onTouchStart={submit}>Submit</View>,High
4,Accessibility,Dynamic Updates,accessibilityLiveRegion announce,iOS/Android/React Native,Async status updates should be announced to screen readers,Use accessibilityLiveRegion or announceForAccessibility,Update text silently with no announcement,"<Text accessibilityLiveRegion=""polite"">{status}</Text>",<Text>{status}</Text>,Medium
5,Accessibility,Decorative Icons,accessible={false} importantForAccessibility,iOS/Android/React Native,Decorative icons should be hidden from screen readers,Mark decorative icons as not accessible,Have screen reader read every icon,"<Icon accessible={false} importantForAccessibility=""no"" />",<Icon />,Medium
6,Touch,Touch Target Size,touch target size platform runtime arbitration iOS 44pt Android 48dp web 24 CSS px React Native hitSlop,iOS/Android/React Native,Native targets use 44pt on iOS and 48dp on Android; web WCAG 2.2 has a separate 24 by 24 CSS px minimum with exceptions,Select 44pt for iOS and 48dp for Android at runtime; evaluate web targets separately against WCAG 2.5.8 and its exceptions,"Collapse iOS 44pt, Android 48dp, and web 24 CSS px into one cross-platform number","Platform.select({ ios: 44, android: 48 }); // web: evaluate 24 CSS px + WCAG exceptions",<Pressable><Icon size={16} /></Pressable>,Critical
7,Touch,Touch Spacing,touch spacing gap 8px,iOS/Android/React Native,Adjacent touch targets need enough spacing,Keep at least 8dp spacing between touchables,Cluster many buttons with no gap,<View style={{ gap: 8 }}><Button ... /><Button ... /></View>,<View><Button ... /><Button ... /></View>,Medium
8,Touch,Gesture Conflicts,scroll swipe back gesture,iOS/Android/React Native,Custom gestures must not break system scroll/back,Reserve horizontal swipes for carousels,Full-screen custom swipe conflicting with back,HorizontalPager inside vertical ScrollView,PanResponder on full screen blocking back,High
9,Navigation,Back Behavior,back handler navigation stack,iOS/Android/React Native,Back navigation should be predictable and preserve state,Use navigation.goBack and keep screen state,Reset stack or exit app unexpectedly,onPress={() => navigation.goBack()},BackHandler.exitApp() on first press,Critical
10,Navigation,Bottom Tabs,tab bar max items,iOS/Android/React Native,Bottom tab bar should have at most 5 primary items,Use 3–5 tabs and move extras to More/Settings,Overloaded tab bar with many icons,Home/Explore/Profile/Settings,Home/Explore/Shop/Cart/Profile/Settings/More,Medium
11,Navigation,Modal Escape,modal dismiss close affordance,iOS/Android/React Native,Modals/sheets must have clear close actions,Provide close button and swipe-down where platform expects,Trapping users in modal with no obvious exit,"<Modal><Button title=""Close"" onPress={onClose} /></Modal>",<Modal><View>{children}</View></Modal>,High
12,State,Preserve Screen State,navigation preserve state,iOS/Android/React Native,Returning to a screen should restore its scroll and form state,Keep components mounted or persist state,Reset list scroll and form inputs on every visit,<Tab.Navigator screenOptions={{ unmountOnBlur: false }}>,<Tab.Screen options={{ unmountOnBlur: true }} />,Medium
13,Feedback,Loading Indicators,activity indicator skeleton,iOS/Android/React Native,Show visible feedback during network operations,Use ActivityIndicator or skeleton for >300ms operations,Leave button and screen frozen,"{loading ? <ActivityIndicator /> : <Button title=""Save"" />}"," ""<Button title=""""Save"""" onPress={submit} /> // no loading""",High
14,Feedback,Success Feedback,toast checkmark banner,iOS/Android/React Native,Confirm successful actions with brief feedback,Show toast/checkmark or banner,Complete actions silently with no confirmation,showToast('Saved successfully'),// silently update state only,Medium
15,Feedback,Error Feedback,inline error banner,iOS/Android/React Native,Show clear error messages near the problem,input-level error + summary banner,Only change border color with no explanation,<TextInput ... /><Text style={{color:'red'}}>{error}</Text>,<TextInput style={{borderColor:'red'}} />,High
16,Forms,Inline Validation,onBlur validation,iOS/Android/React Native,Validate inputs on blur or submit with clear messaging,Validate onBlur and onSubmit,Validate on every keystroke causing jank,onBlur={() => validateEmail(value)},onChangeText={v => validateEmail(v)} // every char,Medium
17,Forms,Keyboard Type,keyboardType returnKeyType,iOS/Android/React Native,Use appropriate keyboardType and returnKeyType,Match email/tel/number/search types,Use default keyboard for all inputs,"<TextInput keyboardType=""email-address"" />","<TextInput keyboardType=""default"" />",Medium
18,Forms,Auto Focus & Next,autoFocus blurOnSubmit onSubmitEditing,iOS/Android/React Native,Guide users through form fields with Next/Done flows,Use onSubmitEditing to focus next input,Force users to tap each field manually,onSubmitEditing={() => nextRef.current?.focus()},"// no onSubmitEditing, manual tap only",Low
19,Forms,Password Visibility,secureTextEntry toggle,iOS/Android/React Native,Allow toggling password visibility securely,Provide Show/Hide icon toggling secureTextEntry,Force users to type blind with no option,<TextInput secureTextEntry={secure} /><Icon onPress={toggle} />,<TextInput secureTextEntry /> // no toggle,Medium
20,Performance,Virtualize Long Lists,FlatList SectionList virtualization,iOS/Android/React Native,Use FlatList/SectionList for lists over ~50 items,Use keyExtractor and initialNumToRender appropriately,Render hundreds of items with ScrollView,<FlatList data={items} renderItem={...} />,<ScrollView>{items.map(renderItem)}</ScrollView>,High
21,Performance,Image Size & Cache,Image resize cache,iOS/Android/React Native,Use correctly sized and cached images,Use Image component with proper resizeMode and caching,Load full-resolution images everywhere,"<Image source={{uri}} resizeMode=""cover"" />",<Image source={require('4k.png')} /> // small avatar,Medium
22,Performance,Debounce High-Freq Events,debounce scroll search,iOS/Android/React Native,Debounce scroll/search callbacks to avoid jank,Wrap handlers with debounce/throttle,Run heavy logic on every event,onScroll={debouncedHandleScroll},onScroll={handleScrollHeavy},Medium
23,Animation,Duration & Easing,animation duration easing,iOS/Android/React Native,Micro-interactions should be 150–300ms with native-like easing,Use ease-out for enter/ease-in for exit,Use long or linear animations for core UI,"Animated.timing(..., { duration: 200, easing: Easing.out(Easing.quad) })","Animated.timing(..., { duration: 800, easing: Easing.linear })",Medium
24,Animation,Respect Reduced Motion,reduced motion accessibility,iOS/Android/React Native,Respect OS reduced-motion accessibility setting,Check reduceMotionEnabled and simplify animations,Ignore user motion preferences,if (reduceMotionEnabled) skipAnimation(),Always run complex parallax animations,Critical
25,Animation,Limited Continuous Motion,loop animation loader,iOS/Android/React Native,Reserve infinite animations for loaders and live data,Use looping only where necessary,Keep decorative elements looping forever,Animated.loop(loaderAnim) for ActivityIndicator,Animated.loop(bounceAnim) on background icons,Medium
26,Typography,Base Font Size,fontScale dynamic type,iOS/Android/React Native,Body text must be readable and support Dynamic Type,Use platform fontScale and at least 14–16pt base,Render critical text below 12pt,<Text style={{ fontSize: 16 }}>Body</Text>,<Text style={{ fontSize: 10 }}>Body</Text>,High
27,Typography,Dynamic Type Support,allowFontScaling adjustsFontSizeToFit,iOS/Android/React Native,Support system text scaling without breaking layout,Set allowFontScaling and test large text,Disable scaling on all text globally,<Text allowFontScaling>{label}</Text>,<Text allowFontScaling={false}>{label}</Text>,High
28,Safe Areas,Safe Area Insets,safe area insets notch gesture,iOS/Android/React Native,Content must not overlap notches/gesture bars,Wrap screens in SafeAreaView or apply insets,Place tappable content under system bars,<SafeAreaView style={{ flex: 1 }}><Screen /></SafeAreaView>,<View style={{ flex: 1 }}><Screen /></View>,High
29,Theming,Light/Dark Contrast,dark mode contrast tokens,iOS/Android/React Native,Ensure sufficient contrast in both light and dark themes,Use semantic tokens and test both themes,Reuse light-theme grays directly in dark mode,colors.textPrimaryDark = '#F9FAFB',colors.textPrimaryDark = '#9CA3AF' on '#111827',High
30,Anti-Pattern,No Gesture-Only Actions,gesture only hidden controls,iOS/Android/React Native,Don't rely solely on hidden gestures for core actions,Provide visible buttons in addition to gestures,Rely on swipe/shake only with no UI affordance,Swipe to delete + visible Delete button,Only shake device to undo with no UI,Critical
31,Accessibility,Dragging Alternatives,accessible drag interaction drag single pointer alternative keyboard drag alternative reorder resize move buttons React Native native runtime platform router arbitration iOS Android web,iOS/Android/React Native,React Native drag and reorder operations need a non-drag path selected for the active native runtime,Provide named Move up/down buttons or a position menu beside drag handles; route iOS and Android behavior through the runtime platform adapter,"Make drag, swipe, or a web-only pointer handler the only way to reorder native content","<Button title=""Move up"" onPress={() => moveItem(index, index - 1)} />",<DragHandle /> only,High
32,Forms,Authentication Reuse,password manager passkey paste redundant entry,iOS/Android/React Native,Authentication and multi-step flows should reuse prior values,Support password managers passkeys paste and prefilled confirmed values,Force users to retype credentials or the same data in one flow,"textContentType=""password"" autoComplete=""current-password""",onPaste disabled,Critical
```

## File: skills/motion-architect/engine/design/data/catalog-summary.json
size: 2392
sha: f911c3ae48fac5863a5a5e210866ec5cabece164
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/catalog-summary.json

```text
{
  "schemaVersion": 1,
  "verifiedAt": "2026-08-26",
  "counts": {
    "styles": {
      "total": 88,
      "searchable": 79,
      "active": 50,
      "supplemental": 29,
      "deprecated": 9
    },
    "products": 192,
    "palettes": 192,
    "reasoningProfiles": 192,
    "fontPairings": 74,
    "googleFonts": 1934,
    "curatedIcons": 105,
    "upstreamPhosphorIcons": 1512,
    "uxGuidelines": 119,
    "motionPresets": 17,
    "chartTypes": 25,
    "stacks": 22,
    "stackGuidelines": 1271
  },
  "snapshots": {
    "google-fonts.csv": {
      "sha256": "1c8c3b2ea1faf6a1012da463756def8b3889db33f2226f0343bb4daa80307d03"
    },
    "google-font-licenses.json": {
      "sha256": "35688523f2955795caa1a47c53b83099e60c1708461476f9cc3a050cf3b0148a"
    },
    "icons.csv": {
      "sha256": "50816c6012030178195a16ee481ebf58b47bd985d70e8ec58886cc83f6eddafc"
    },
    "phosphor-icons-upstream.json": {
      "sha256": "2399325233b277b5c97a80e6a5e8941154f5d057beee4e7613db87c87d700236"
    }
  },
  "promotionPolicy": {
    "changedFamilySetRequiresExplicitApproval": true,
    "relevanceGateRequired": true,
    "unlicensedFamiliesExcluded": true
  },
  "pendingCandidates": [
    {
      "family": "Edu NSW ACT Cursive",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Edu NSW ACT Hand Pre",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Edu QLD Hand",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Edu SA Hand",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Edu VIC WA NT Hand",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Edu VIC WA NT Hand Pre",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Google Sans",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    },
    {
      "family": "Google Sans Flex",
      "reason": "No exact-family METADATA.pb entry in the official google/fonts repository snapshot"
    }
  ]
}
```

## File: skills/motion-architect/engine/design/data/charts.csv
size: 23365
sha: c6f4f875fd5b34379f24dbb541539492366a1058
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/charts.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/charts.csv

## File: skills/motion-architect/engine/design/data/colors.csv
size: 37940
sha: 5d2bf7389105f8a824b504b57cc93c00dc1d7e0a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/colors.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/colors.csv

## File: skills/motion-architect/engine/design/data/data-provenance.json
size: 36686
sha: e41d2e553bdc7e5a8e6d16f5daab565faf372188
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/data-provenance.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/data-provenance.json

## File: skills/motion-architect/engine/design/data/google-font-licenses.json
size: 433127
sha: 3ac2c34e80665bc902e265c52ab6c27b1654524c
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/google-font-licenses.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/google-font-licenses.json

## File: skills/motion-architect/engine/design/data/google-fonts.csv
size: 747241
sha: d7f87e3e0159b1caba083b9954793d9852256aa0
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/google-fonts.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/google-fonts.csv

## File: skills/motion-architect/engine/design/data/icons.csv
size: 57945
sha: cfc3f1eccd7e5aee15d8d70f86d8fa17ba737958
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/icons.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/icons.csv

## File: skills/motion-architect/engine/design/data/landing.csv
size: 25449
sha: 34858160aa2789c49dca274d48bb116d51dd3f0a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/landing.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/landing.csv

## File: skills/motion-architect/engine/design/data/motion.csv
size: 14679
sha: 8e0ca9ceb0e4cd4832aee60ac74713e1e1830de8
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/motion.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/motion.csv

## File: skills/motion-architect/engine/design/data/phosphor-icons-upstream.json
size: 823933
sha: ec1d76b8117ccbfdce5df214bf0d993e41a75318
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/phosphor-icons-upstream.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/phosphor-icons-upstream.json

## File: skills/motion-architect/engine/design/data/products.csv
size: 75623
sha: 9f40f1d1f9743c4a81603076dfbfd115bbb55246
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/products.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/products.csv

## File: skills/motion-architect/engine/design/data/react-performance.csv
size: 15080
sha: 425a8e76c6b3bae40e8c633ffbf7ad6222c9f73a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/react-performance.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/react-performance.csv

## File: skills/motion-architect/engine/design/data/stacks/angular.csv
size: 19863
sha: 5a1878dbee2b3c55c6468cbb18699b84d1a8c4d2
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/angular.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/angular.csv

## File: skills/motion-architect/engine/design/data/stacks/astro.csv
size: 14591
sha: 1fd2492420b20a0b311295ab883597fadb8245a6
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/astro.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/astro.csv

## File: skills/motion-architect/engine/design/data/stacks/avalonia.csv
size: 27327
sha: c67f4117105865587eda9020c57d8c209f3a929a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/avalonia.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/avalonia.csv

## File: skills/motion-architect/engine/design/data/stacks/flutter.csv
size: 14192
sha: 731805c4076bd9f2755ca4bd7def5be6f6df7e9c
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/flutter.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/flutter.csv

## File: skills/motion-architect/engine/design/data/stacks/html-tailwind.csv
size: 16551
sha: 9089eb0fc821ff0c8d135f8ee503be345e8fcb84
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/html-tailwind.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/html-tailwind.csv

## File: skills/motion-architect/engine/design/data/stacks/javafx.csv
size: 33577
sha: 744bd80f437f12bfb5bb9c84630a58022604675a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/javafx.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/javafx.csv

## File: skills/motion-architect/engine/design/data/stacks/jetpack-compose.csv
size: 12295
sha: 8daa0b8f9a2ca3f0f1711664d9d677cd1c38dd9e
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/jetpack-compose.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/jetpack-compose.csv

## File: skills/motion-architect/engine/design/data/stacks/laravel.csv
size: 20163
sha: ed11b0fba457e02857f996d1542fb0b8e1271756
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/laravel.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/laravel.csv

## File: skills/motion-architect/engine/design/data/stacks/nextjs.csv
size: 18687
sha: acdaf097dff26ba0d3b22ab4544bf6169c87afd4
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nextjs.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nextjs.csv

## File: skills/motion-architect/engine/design/data/stacks/nuxt-ui.csv
size: 28700
sha: e2aaeca45faa8b987bf94010162b14d458811dde
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nuxt-ui.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nuxt-ui.csv

## File: skills/motion-architect/engine/design/data/stacks/nuxtjs.csv
size: 23014
sha: ceab9cf3358d2788af0bd7dc14cb3fab769740d0
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nuxtjs.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/nuxtjs.csv

## File: skills/motion-architect/engine/design/data/stacks/react-native.csv
size: 14049
sha: a5aea45dc1d0341b11ee42076a86db842d4d2a19
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/react-native.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/react-native.csv

## File: skills/motion-architect/engine/design/data/stacks/react.csv
size: 21166
sha: fe8f001e695a978733449e04e99d7135af0f1bf3
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/react.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/react.csv

## File: skills/motion-architect/engine/design/data/stacks/shadcn.csv
size: 23184
sha: 0e8bedf3084e7a40d6310bcd3011c437efcb1700
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/shadcn.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/shadcn.csv

## File: skills/motion-architect/engine/design/data/stacks/svelte.csv
size: 15078
sha: 51684fe70448e15333cd16207db7da8aea0508e6
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/svelte.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/svelte.csv

## File: skills/motion-architect/engine/design/data/stacks/swiftui.csv
size: 15323
sha: ea9b95e8922e663b2adf27a7346e2c2f44c7a215
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/swiftui.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/swiftui.csv

## File: skills/motion-architect/engine/design/data/stacks/threejs.csv
size: 46769
sha: f62286320038beabbdc5e11e07ca2818d8e959a4
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/threejs.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/threejs.csv

## File: skills/motion-architect/engine/design/data/stacks/uno.csv
size: 30091
sha: 9cab32326b4ad3a3cf43451a3c24553a41126cc1
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/uno.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/uno.csv

## File: skills/motion-architect/engine/design/data/stacks/uwp.csv
size: 24692
sha: 04a84ea092a7657fef11e5daa97982be52dc6f59
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/uwp.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/uwp.csv

## File: skills/motion-architect/engine/design/data/stacks/vue.csv
size: 12813
sha: 83997c515775170f22b638635aae0a67a46dfc87
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/vue.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/vue.csv

## File: skills/motion-architect/engine/design/data/stacks/winui.csv
size: 27890
sha: 107ecead11728a83ec0ea10d815a9d1f43a35792
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/winui.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/winui.csv

## File: skills/motion-architect/engine/design/data/stacks/wpf.csv
size: 24158
sha: 4e88d6750833a74f85ba487cf2b8f4ff6ebd2f4a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/wpf.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/stacks/wpf.csv

## File: skills/motion-architect/engine/design/data/styles.csv
size: 149478
sha: d1eb2c216e453005ffa8232ffb94491c183afe3c
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/styles.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/styles.csv

## File: skills/motion-architect/engine/design/data/typography.csv
size: 49997
sha: 70d107d107de30150863c965767320ec33ef29ad
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/typography.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/typography.csv

## File: skills/motion-architect/engine/design/data/ui-reasoning.csv
size: 77360
sha: 8931d4c809f8e22ddac00ce612ce0c35f34a59b6
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/ui-reasoning.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/ui-reasoning.csv

## File: skills/motion-architect/engine/design/data/ux-guidelines.csv
size: 27516
sha: 4e7d52b296537a03513b18b2c3f2b946cc802051
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/ux-guidelines.csv

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/data/ux-guidelines.csv

## File: skills/motion-architect/engine/design/pro-rules.md
size: 10909
sha: b2ce233287e37ec9ca13476c4014b922e9d5a0e9
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/pro-rules.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/pro-rules.md

## File: skills/motion-architect/engine/design/quick-reference.md
size: 24526
sha: 7acc7e7540ca6981d878a90aae4455c1638e2385
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/quick-reference.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/quick-reference.md

## File: skills/motion-architect/engine/design/scripts/core.py
size: 41339
sha: fcd260bb30e6eb1c5479439a98b79417aa16ca33
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/core.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/core.py

## File: skills/motion-architect/engine/design/scripts/design_system.py
size: 71709
sha: 27b5a17bdbf6b5f94e8c385b341e11c8f08e6c45
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/design_system.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/design_system.py

## File: skills/motion-architect/engine/design/scripts/reasoning_contract.py
size: 5927
sha: edaba7548f162bd9eeb2de2f148e19708dcbb13a
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/reasoning_contract.py

```text
#!/usr/bin/env python3
# Copyright (c) 2026 Enrique Rocha (@soyenriquerocha)
# SPDX-License-Identifier: MIT
# id: er-22575577
"""Closed, non-executable grammar for design-system decision rules."""

import json
import re

CONDITION_SIGNALS = {
    "if_booking": ("booking", "appointment", "calendar"),
    "if_boutique": ("boutique",),
    "if_casual": ("casual", "playful"),
    "if_checkout": ("checkout", "payment", "purchase"),
    "if_children": ("child", "children", "kids"),
    "if_collaboration": ("collaboration", "multiplayer", "co-edit"),
    "if_competitive": ("competitive", "leaderboard"),
    "if_content_focused": ("content", "article", "reading", "documentation"),
    "if_conversion_focused": ("conversion", "sales", "signup", "purchase"),
    "if_creative_field": ("creative", "artist", "portfolio"),
    "if_crop_focused": ("crop", "farm", "agriculture"),
    "if_dashboard": ("dashboard", "operations", "monitoring"),
    "if_data_heavy": ("data heavy", "data-heavy", "analytics", "large dataset"),
    "if_delivery": ("delivery", "courier", "shipping"),
    "if_discovery_focused": ("discover", "discovery", "browse", "directory"),
    "if_engagement_metric": ("engagement", "retention", "contribution"),
    "if_experience_focused": ("experience", "immersive", "journey"),
    "if_gamification": ("gamification", "badges", "streak"),
    "if_health": ("health", "medical", "patient"),
    "if_hero_needed": ("hero", "showcase", "launch"),
    "if_large_dataset": ("large dataset", "thousands", "millions"),
    "if_light_mode_needed": ("light mode", "light theme"),
    "if_low_performance": ("low performance", "low-end", "slow device"),
    "if_luxury": ("luxury", "premium", "high-end"),
    "if_medication": ("medication", "medicine", "prescription"),
    "if_meditation": ("meditation", "breathing", "mindfulness"),
    "if_minimal_portfolio": ("minimal portfolio", "simple portfolio"),
    "if_mobile": ("mobile", "phone", "tablet", "ios", "android"),
    "if_personalized": ("personalized", "personalised", "recommendation"),
    "if_pre_launch": ("pre-launch", "prelaunch", "coming soon", "waitlist"),
    "if_salary_focused": ("salary", "compensation", "pay range"),
    "if_team_collaboration": ("team collaboration", "team workspace"),
    "if_trust_needed": ("trust", "secure", "verified", "authority"),
    "if_ux_focused": ("ux", "usability", "accessibility", "accessible"),
    "if_video_ready": ("video ready", "product video", "demo video"),
}

ALLOWED_CONDITIONS = {"must_have", *CONDITION_SIGNALS}
ACTION_PREFIXES = {"constraint", "style", "pattern", "mode"}
TOKEN_ACTION_PREFIXES = {"constraint", "style"}
TOKEN_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
CONDITION_PATTERNS = {
    condition: tuple(
        re.compile(r"(?<!\w)" + re.escape(signal) + r"(?!\w)")
        for signal in signals
    )
    for condition, signals in CONDITION_SIGNALS.items()
}

def _object_without_duplicates(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError("duplicate decision-rule key: {}".format(key))
        result[key] = value
    return result

def parse_decision_rules(raw):
    """Parse the canonical condition -> action-array representation."""
    try:
        rules = json.loads(raw or "{}", object_pairs_hook=_object_without_duplicates)
    except json.JSONDecodeError as error:
        raise ValueError("invalid decision-rule JSON: {}".format(error)) from error
    if not isinstance(rules, dict):
        raise ValueError("decision rules must be a JSON object")
    for condition, actions in rules.items():
        if condition not in ALLOWED_CONDITIONS:
            raise ValueError("unknown decision-rule condition: {}".format(condition))
        if not isinstance(actions, list) or not actions:
            raise ValueError("{} must map to a non-empty action array".format(condition))
        for action in actions:
            _validate_action(action)
        if len(actions) != len(set(actions)):
            raise ValueError("{} contains duplicate actions".format(condition))
    return rules

def _validate_action(action):
    if not isinstance(action, str) or ":" not in action:
        raise ValueError("action must use a known prefix: {}".format(action))
    prefix, value = action.split(":", 1)
    if prefix not in ACTION_PREFIXES:
        raise ValueError("unknown decision-rule action: {}".format(action))
    if prefix in TOKEN_ACTION_PREFIXES and not TOKEN_RE.fullmatch(value):
        raise ValueError("invalid {} action value: {}".format(prefix, value))
    if prefix == "pattern" and not value.strip():
        raise ValueError("pattern action must name a pattern")
    if prefix == "mode" and value not in {"dark", "light"}:
        raise ValueError("mode action must be dark or light")

def apply_decision_rules(rules, query):
    """Return deterministic mutations and an audit trail; never execute data."""
    normalized = str(query or "").casefold()
    result = {"activated": [], "style_ids": [], "constraints": [],
              "pattern": None, "mode": None}
    for condition, actions in rules.items():
        active = condition == "must_have" or any(
            pattern.search(normalized)
            for pattern in CONDITION_PATTERNS.get(condition, ()))
        if not active:
            continue
        result["activated"].append({"condition": condition, "actions": list(actions)})
        for action in actions:
            prefix, value = action.split(":", 1)
            if prefix == "style" and value not in result["style_ids"]:
                result["style_ids"].append(value)
            elif prefix == "constraint" and value not in result["constraints"]:
                result["constraints"].append(value)
            elif prefix == "pattern":
                result["pattern"] = value
            elif prefix == "mode":
                result["mode"] = value
    return result
```

## File: skills/motion-architect/engine/design/scripts/search.py
size: 9560
sha: f1c79c0a85d3186220f01c53de1568299bc2d67f
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/search.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/design/scripts/search.py

## File: skills/motion-architect/engine/vision/analyze.py
size: 21324
sha: 201c8fe29b19dd5805e52a8812eb7aecb9707ac4
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/analyze.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/analyze.py

## File: skills/motion-architect/engine/vision/config.py
size: 7372
sha: c51652f29833c5828297e19f671e25e0c1255642
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/config.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/config.py

## File: skills/motion-architect/engine/vision/download.py
size: 10926
sha: c94ec649c0e9253edbc407304b34167854e60017
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/download.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/download.py

## File: skills/motion-architect/engine/vision/frames.py
size: 29187
sha: 979eaf3f9efdb9261c2b2c980591024faea29395
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/frames.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/frames.py

## File: skills/motion-architect/engine/vision/gemini.py
size: 8364
sha: 7f219d437ca6abb5dc885710fe4b8cd8ead5abb8
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/gemini.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/gemini.py

## File: skills/motion-architect/engine/vision/local_whisperx.py
size: 7204
sha: 6ff9110ceabf77f0be4983544bd0791325037a09
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/local_whisperx.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/local_whisperx.py

## File: skills/motion-architect/engine/vision/runtime.py
size: 1480
sha: 411708675404a427f79d5adac36e53cf1b524cac
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/runtime.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/runtime.py

## File: skills/motion-architect/engine/vision/setup.py
size: 15882
sha: bd1879c5f20521adfb7826b73f5750936f09f814
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/setup.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/setup.py

## File: skills/motion-architect/engine/vision/transcribe.py
size: 4538
sha: 7ea8efb8c6253d28d9d113d8e1ed3ca10b4dd931
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/transcribe.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/transcribe.py

## File: skills/motion-architect/engine/vision/whisper.py
size: 16161
sha: 3b324f59f0ed277ffabca0e4bef5aec19c299b0c
upstream: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/whisper.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/hainrixz/motion-architect/blob/main/skills/motion-architect/engine/vision/whisper.py

## File: README.md
upstream: https://github.com/hainrixz/motion-architect/blob/main/README.md

````text
<p align="center">
  <img src="docs/hero.svg" alt="Motion Architect — motion graphics con Claude y Remotion, todo local" width="100%">
</p>

<p align="center">
  <b>Motion graphics con Claude, en tu compu.</b><br>
  Le das videos, imágenes y tu marca. Claude diseña, anima y renderiza con Remotion.
</p>

<p align="center">
  <a href="#instalación">Instalación</a> ·
  <a href="#cómo-se-usa">Cómo se usa</a> ·
  <a href="#formatos">Formatos</a> ·
  <a href="#cómo-funciona-por-dentro">Cómo funciona</a> ·
  <a href="README.en.md">English</a>
</p>

<p align="center">
  <img alt="Remotion" src="https://img.shields.io/badge/Remotion-4.0-FF5B3A?style=flat-square">
  <img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-plugin-0B0B0F?style=flat-square">
  <img alt="Local" src="https://img.shields.io/badge/100%25-local-7CE0C3?style=flat-square">
  <img alt="MIT" src="https://img.shields.io/badge/license-MIT-F4F1EA?style=flat-square">
</p>

---

## Qué es

**Motion Architect** es un agente para Claude Code que hace motion graphics por ti. Le hablas como a un motion designer y te entrega el video renderizado.

| | |
|---|---|
| 👁 **Ve tus referencias** | Le pasas un video (link o archivo) o una imagen y entiende el ritmo, los cortes, la paleta y el tipo de movimiento |
| 🎨 **Diseña con tu marca** | Colores, tipografías y estilo visual, ya sea de tu marca o propuestos por él |
| 🎬 **Escribe el storyboard** | Hook, desarrollo y remate, con tiempos exactos. Tú lo apruebas antes de que se anime nada |
| ✨ **Anima con criterio** | Easing, timing y springs pensados para que se sienta profesional, no "hecho con IA" |
| 📐 **Renderiza en cualquier formato** | Vertical, horizontal, cuadrado o 4:5, con safe zones para Reels y TikTok |
| 🔊 **Pone sonido** | Librería de efectos incluida, sincronizados con la animación |

## La misión

Que cualquiera pueda hacer motion graphics de calidad hablando con Claude, como si tuviera un motion designer al lado. Sin After Effects y sin pelearse con keyframes. Le muestras un video que te gusta, le pasas tu logo y le dices *"algo así, pero para mi lanzamiento, en vertical"*.

Todo corre **en tu computadora**: el render, el análisis de videos y el preview. Nada se sube a ningún lado.

<p align="center">
  <img src="docs/demo.gif" alt="Demo renderizada con Motion Architect" width="80%"><br>
  <sub>Este demo salió del estudio incluido: <code>npx remotion render src/index.ts Demo-landscape</code></sub>
</p>

## Instalación

**Requisitos:** macOS o Linux, [Claude Code](https://claude.com/claude-code), Node 18+, ffmpeg, yt-dlp y Python 3. El instalador revisa todo y, en macOS, ofrece instalar con Homebrew lo que falte.

```bash
git clone https://github.com/Hainrixz/motion-architect.git
cd motion-architect
./install.sh
```

Eso es todo. El instalador revisa lo que falta, prepara el estudio de animación y deja el agente listo en Claude Code. Puedes correrlo varias veces sin problema, y con `./install.sh --yes` no te pregunta nada. Al terminar, reinicia Claude Code.

> **Repo privado:** mientras el repo sea privado, para clonarlo necesitas acceso en GitHub.

<details>
<summary><b>Opcional: transcripción de videos sin subtítulos</b></summary>

Motion Architect usa los subtítulos del video cuando existen. Para los que no tienen, puede transcribir el audio si agregas **una** de estas líneas en `~/.config/motion-architect/.env`:

```
GROQ_API_KEY=...
OPENAI_API_KEY=...
```

Sin llave, igual ve los frames del video, que es lo que importa para analizar movimiento.
</details>

## Cómo se usa

Abre Claude Code en la carpeta del repo (o en cualquier otra; el agente encuentra el estudio) y pide:

```
/motion un reel vertical de 15 s anunciando mi app de finanzas, estilo cinematic
```

Claude va a:

1. **Preguntarte lo que falte, todo en un mensaje:** formato, duración, tono, marca y música.
2. **Ver tus referencias:** videos (URL o archivo), imágenes y capturas.
3. **Armar tu marca:** colores, fuentes y estilo en `studio/brand.json`.
4. **Escribir el storyboard** y esperar a que lo apruebes.
5. **Construir la animación** y revisarla cuadro por cuadro antes de mostrártela.
6. **Abrir Remotion Studio** en `localhost:3000` para que veas el preview y lo ajustes.
7. **Renderizar** el mp4 en los formatos que pediste, con poster.

### Ejemplos de prompts

```
/motion anima mi logo (está en ~/Desktop/logo.svg), 5 segundos, 16:9 y 9:16
```
```
Mira este video https://www.instagram.com/reel/... y hazme algo con ese ritmo
pero con mi marca. Vertical, 12 s.
```
```
/motion intro para mi canal de YouTube, estilo editorial, colores de esta imagen: ./captura.png
```
```
/motion un dato animado: "pasamos de 0 a 10,000 usuarios en 30 días", 4:5 para el feed
```
```
/motion-render MiVideo all
```

### Preview en vivo

```bash
cd studio && npm run studio     # → http://localhost:3000
```

Ahí ves cada composición en cada formato, puedes scrubbear el timeline y los cambios que hace Claude aparecen al instante.

## Formatos

| Formato | Tamaño | Para |
|---|---|---|
| **Vertical** 9:16 | 1080×1920 | Reels, TikTok, Shorts, Stories |
| **Horizontal** 16:9 | 1920×1080 | YouTube, web, presentaciones |
| **Cuadrado** 1:1 | 1080×1080 | Feed, LinkedIn |
| **Feed** 4:5 | 1080×1350 | Feed de Instagram |

Todo se diseña con unidades relativas, así que una misma animación se adapta a los cuatro. Las safe zones de Reels y TikTok ya vienen respetadas.

## Cómo funciona por dentro

```mermaid
flowchart LR
  A[Tu idea + referencias] --> B{/motion}
  B --> C[Análisis<br/>de referencias]
  B --> D[Marca<br/>y estilo]
  C --> E[Storyboard]
  D --> E
  E -->|apruebas| F[Animación]
  F --> G[Revisión<br/>de calidad]
  G --> H[Preview en vivo]
  H --> I[mp4 en 9:16 · 16:9 · 1:1 · 4:5]
```

```
motion-architect/
├─ install.sh                    instalador de un comando
├─ .claude-plugin/               plugin de Claude Code
├─ skills/motion-architect/      el agente: método, motores de visión y diseño, criterio de animación
├─ agents/reference-analyst.md   subagente que analiza videos de referencia
├─ commands/                     /motion y /motion-render
└─ studio/                       proyecto Remotion
   ├─ brand.json                 tu marca: colores, fuentes, estilo
   ├─ src/components/            KineticTitle, LogoReveal, Counter, CardStack, Caption, ImagePan…
   ├─ src/lib/motion.ts          curvas de easing y springs
   ├─ src/compositions/          tus videos (Demo incluido)
   └─ public/                    referencias, música, SFX, logos
```

## Licencia

Motion Architect es **MIT**. Los componentes open source incluidos están listados en [third_party/NOTICES.md](third_party/NOTICES.md).

**Ojo:** el motor de video es [Remotion](https://www.remotion.dev), que es gratis para personas, organizaciones sin fines de lucro y empresas de hasta 3 personas. Las empresas más grandes necesitan una [licencia de empresa](https://www.remotion.dev/license). Revisa sus términos antes de usarlo comercialmente.

---

<p align="center"><sub>Hecho por <a href="https://github.com/Hainrixz">Enrique Rocha</a> · Tododeia</sub></p>

<!-- marca-agua:inicio -->

---

<sub>Hecho por **Enrique Rocha (@soyenriquerocha)** · [tododeia.com](https://www.tododeia.com)⁠​‌‌​​‌​‌​‌‌‌​​‌​​​‌​‌‌​‌​​‌‌​​‌​​​‌‌​​‌​​​‌‌​‌​‌​​‌‌​‌‌‌​​‌‌​‌​‌​​‌‌​‌​‌​​‌‌​‌‌‌​​‌‌​‌‌‌⁠</sub>
<!-- marca-agua:fin -->
````