@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/mage-beauty/references/anti-patterns.md

@@ -0,0 +1,148 @@
+# anti-patterns — 15 deal-breakers (rule → why it fails → fix)
+
+## Charter
+
+These are the 15 patterns that mark a design as AI-generic, untrained, or careless. Each one fails for a specific reason traceable to typography, color, motion, composition, or microcopy theory. Each has a specific fix. This list supersedes the partial anti-patterns block in the `frontend-design` skill — that file points here.
+
+This reference is read first by every verb's pre-check. If a candidate output violates any rule below, the verb redirects before delivering.
+
+---
+
+## Typography
+
+### 1. Inter (or Geist, or system font) for everything
+
+**Why it fails:** Inter is the universally-used, AI-default sans. When every page uses it for both heading and body, the design has no typographic identity. The reader's brain registers "another LLM-generated UI" before any content is read.
+
+**Fix:** pair Inter (or the body sans) with a distinctive heading family. Examples that work: Outfit + Inter, Space Grotesk + Inter, Sora + Inter, Cormorant Garamond + Inter, Playfair Display + Inter. Use the heading font for H1/H2 only — body stays Inter. Cost: 1 extra font load.
+
+### 2. Decorative text-shadow on body type
+
+**Why it fails:** Drop shadows on small body text reduce legibility, look amateurish, and date the design to ~2009. They survive in CSS tutorials and never in production work from teams that have shipped a real product.
+
+**Fix:** remove all `text-shadow` from body type. Reserve subtle shadows (e.g., `text-shadow: 0 1px 2px rgba(0,0,0,0.1)`) only for text overlaid on busy media (Remotion captions, hero text on photos), and even then prefer a backdrop plate.
+
+### 3. ALL CAPS body paragraphs
+
+**Why it fails:** capitals strip ascender/descender variation, slowing reading speed by ~15%. Acceptable for short labels (5–6 chars). Catastrophic for sentences.
+
+**Fix:** sentence case for body. Reserve ALL CAPS for navigation labels, badges, and short button text. Always pair caps with `letter-spacing: +0.05em` minimum.
+
+---
+
+## Color
+
+### 4. Purple-to-blue gradient hero
+
+**Why it fails:** universally read as "AI demo." The default Vercel template, the OpenAI brand, every demo of every JavaScript framework launch in 2023–2024. Visual recognition is instant: this is generic.
+
+**Fix:** commit to a single dominant tone. If a gradient is wanted, use within-hue (`oklch(15% 0.1 264) → oklch(35% 0.15 264)`) or temperature-shift (warm → cool with low saturation). Never default-purple → default-blue.
+
+### 5. Gray text on colored background
+
+**Why it fails:** `#9CA3AF` on `#3B82F6` is 2.4:1 contrast — fails WCAG AA. The most common accessibility miss in AI-generated UIs. Looks "fine" until tested.
+
+**Fix:** for text on colored surface, use a tint of the background (lightened/darkened version) or a high-contrast neutral (`#FFFFFF` / `#0F172A`). Always verify with browser DevTools contrast checker.
+
+### 6. Pure #000 or pure #FFF
+
+**Why it fails:** pure black backgrounds crush detail under any film grain or photographic content. Pure white text on dark glares. Both signal "no thought given to the visual."
+
+**Fix:** tint your neutrals. `oklch(14% 0.025 264)` for cool dark backgrounds. `oklch(98% 0.01 80)` for warm light. The viewer can't name why it feels better, but it does.
+
+---
+
+## Motion
+
+### 7. Bounce or elastic easing
+
+**Why it fails:** `ease: 'bounce'` and `cubic-bezier(0.68, -0.55, 0.265, 1.55)` were briefly popular ~2014. Today they read as juvenile or untrained. Used universally in AI-generated demos.
+
+**Fix:** use `cubic-bezier(0.16, 1, 0.3, 1)` for entrances (smooth ease-out). Use spring physics with `stiffness: 300, damping: 30` for natural-feeling motion. Reserve bounce for explicitly playful contexts (kids' apps, game UI), and even then sparingly.
+
+### 8. Parallax abuse on every scroll element
+
+**Why it fails:** parallax on the hero alone is fine. Parallax on every section creates seasickness, fails on low-power devices, and ignores `prefers-reduced-motion`. The user experiences it as "this site is slow."
+
+**Fix:** parallax on at most one element per page (usually a hero background). Always wrapped in `@media (prefers-reduced-motion: no-preference)`. Use `transform: translateY()` (GPU-accelerated) — never animate `top/bottom`.
+
+### 9. Autoplay video with sound
+
+**Why it fails:** browsers block this by default for good reason. When it does play, users instinctively close the tab. Hostile UX.
+
+**Fix:** autoplay muted only, with a clear unmute affordance. For Remotion output: never embed audio in a video that's expected to autoplay on a feed (Instagram, TikTok handle this — but landing-page hero videos must mute by default).
+
+---
+
+## Composition
+
+### 10. Card nested inside card
+
+**Why it fails:** `border + bg-white + shadow` inside another `border + bg-white + shadow` reads as visual noise without information gain. The eye sees two borders where one would communicate the same hierarchy.
+
+**Fix:** flatten the inner card. Use spacing and typography to separate the inner content from the outer container. If the inner element really needs a container, drop the border (`bg-surface-elevated` only) so it reads as a layer, not a separate widget.
+
+### 11. Centered everything
+
+**Why it fails:** centered hero, centered features in a row, centered testimonials, centered CTA. Symmetric and forgettable. The page has no rhythm because every element shares the same horizontal axis.
+
+**Fix:** vary composition by section. Hero asymmetric (60/40 split, image right). Features in a 2-up grid offset left. One full-bleed image. Testimonials in a horizontal carousel. Single base alignment per section, but vary across sections.
+
+### 12. Equal visual weight across navigation items
+
+**Why it fails:** "Home / Pricing / Features / About / Contact / Blog / Docs / Login / Sign Up" all in identical font weight and size. The user has no signal about what's primary. Conversion tanks because the eye has nowhere to land.
+
+**Fix:** primary action (typically Sign Up / Get Started / Start Free Trial) gets a button treatment with the accent color. Login is secondary text. Other nav items are neutral. Visual hierarchy = clarity.
+
+---
+
+## Microcopy
+
+### 13. "Get Started" as the primary CTA
+
+**Why it fails:** "Get Started" is the most-used CTA in AI-generated landing pages because it's safe, generic, and answers no question. Started doing what?
+
+**Fix:** describe the outcome. "Build your first video," "Plan your campaign," "Estimate your project," "Try the free 7-day trial." The user reads the button before anything else — make it tell them what happens.
+
+### 14. Em-dash overuse in body copy
+
+**Why it fails:** em-dashes are LLM-generated copy's most identifiable tell — every paragraph contains at least one — interrupting flow without earning the pause. (See what just happened.)
+
+**Fix:** allow yourself one em-dash per ~150 words maximum. Replace with: a comma if the aside is short, a period and new sentence if standalone, parentheses if truly parenthetical. Read your copy out loud. If you stop at every em-dash, cut some.
+
+### 15. Validation jargon in error messages
+
+**Why it fails:** "Invalid format," "Field required," "Constraint violation," "ERR_VALIDATION_FAILED" — these are messages from the validation library, not a human. The user has no path forward.
+
+**Fix:** rewrite every error to (a) say what's wrong in human terms, (b) show the correction path. "Invalid format" → "Use a phone number with area code, like (555) 123-4567." Costs nothing in code, transforms the experience.
+
+---
+
+## Cross-references
+
+- For typography reasoning behind rules 1–3: read `typography.md` in this skill
+- For color reasoning behind rules 4–6: read `color-and-contrast.md` in this skill
+- For motion reasoning behind rules 7–9: read `motion-design.md` in this skill
+- For composition reasoning behind rules 10–12: read `spatial-design.md` in this skill
+- For microcopy reasoning behind rules 13–15: read `voice-and-microcopy.md` in this skill
+- The `frontend-design` skill anti-patterns section (lines 96–107) is now superseded by this file
+
+## Quick scan
+
+Before declaring any design done, confirm:
+
+- [ ] Not Inter alone — paired with distinctive heading family
+- [ ] No drop shadows on body type
+- [ ] Body in sentence case (caps reserved for short labels)
+- [ ] No purple→blue gradient
+- [ ] All text/background contrast verified ≥ WCAG AA
+- [ ] Backgrounds tinted (no pure #000/#FFF)
+- [ ] No bounce/elastic easing
+- [ ] No parallax abuse, motion respects reduced-motion
+- [ ] No autoplay with sound
+- [ ] No card-in-card nesting
+- [ ] Composition varies across sections (no centered-everything)
+- [ ] Nav has clear primary/secondary hierarchy
+- [ ] CTAs describe outcomes (no generic "Get Started")
+- [ ] ≤ 1 em-dash per 150 words
+- [ ] All errors say what to do, not just what's wrong

package/.merlin-core/skills/general/mage-beauty/references/color-and-contrast.md

@@ -0,0 +1,87 @@
+# color-and-contrast — Tinted neutrals, OKLCH, intentional weight
+
+## Charter
+
+Most AI-generated palettes fail in the same five ways: pure black background, pure white text, three accent colors fighting for attention, gray-on-color combos that fail WCAG, and a purple-to-blue gradient that screams "demo." Beauty in color comes from restraint, perceptual uniformity, and a single accent that earns its place. Tint your neutrals, commit to a dominant tone, and let the color do meaning, not decoration.
+
+## Principles
+
+1. **Never use pure #000 or #FFF.** Pure black backgrounds crush detail; pure white text on dark surfaces glares. Tint backgrounds toward a hue (`oklch(14% 0.025 264)` for cool dark, `oklch(98% 0.01 80)` for warm light). The viewer can't name why it feels better, but it does.
+2. **OKLCH over HSL.** OKLCH is perceptually uniform — equal lightness values look equally bright across hues. HSL lies (a yellow at 50% lightness looks brighter than a blue at the same value). Use `oklch(L% C H)` everywhere modern browsers support it, with HSL/hex fallbacks via `color-mix()` or build-time conversion.
+3. **60-30-10 rule.** 60% dominant (background + structural surfaces), 30% secondary (cards, panels, navigation), 10% accent (CTAs, focus rings, key data). Equal-weight palettes are noise.
+4. **One accent, used everywhere it appears.** A landing page with three different "accent" colors is visually unparseable. If you need urgency + success + warning + info, those are semantic states, not accents.
+5. **WCAG AA is the floor, not the ceiling.** 4.5:1 for normal text, 3:1 for large text and UI components. AAA (7:1 / 4.5:1) is the bar for healthcare, education, government. Test every text/background pair, every button state, every focus ring.
+6. **Gray text on colored backgrounds fails most of the time.** `#9CA3AF` on `#3B82F6` is 2.4:1 — fails normal text. Switch to a tint of the background or a high-contrast neutral.
+7. **Dark mode is not inverted light mode.** Light-mode `#F8FAFC` background does not invert to `#070806`. Dark mode wants its own surface ladder: bg < surface < surface-elevated, with each step ~3-5% lighter.
+8. **Accent saturation drops in dark mode.** A pure `oklch(60% 0.25 264)` blue that pops on white is jarring on dark. Drop chroma to `0.15-0.18` for dark surfaces.
+
+## Web application
+
+**Token architecture:**
+
+```css
+@theme {
+  --color-bg: oklch(98% 0.005 80);
+  --color-surface: oklch(100% 0 0);
+  --color-surface-elevated: oklch(100% 0 0);
+  --color-text: oklch(15% 0.02 264);
+  --color-text-muted: oklch(46% 0.02 264);
+  --color-border: oklch(90% 0.01 264);
+  --color-accent: oklch(60% 0.18 264);
+}
+```
+
+Every color token must trace to a semantic role. Never reference raw hex from a component. The `design-system` skill enforces this — see its pre-delivery checklist.
+
+**Dark mode pairing:**
+
+```css
+.dark {
+  --color-bg: oklch(14% 0.025 264);
+  --color-surface: oklch(18% 0.025 264);
+  --color-surface-elevated: oklch(22% 0.025 264);
+  --color-text: oklch(96% 0.01 264);
+  --color-text-muted: oklch(65% 0.02 264);
+  --color-border: oklch(28% 0.02 264);
+  --color-accent: oklch(70% 0.15 264);
+}
+```
+
+**Verification:** browser DevTools > Inspect > Accessibility tab shows contrast ratios live. Don't ship without checking.
+
+## Remotion application
+
+Color in video behaves differently from color on screen:
+
+1. **30 fps + H.264 compression desaturates.** A `chroma 0.25` accent on a static screen renders at `~0.20` after encoding. Bump chroma 15–20% for video sources, then verify after the first render.
+2. **Pure red bleeds.** `#FF0000` (oklch ~58% 0.25 27) blooms across pixels under H.264 chroma subsampling. Drop to `oklch(55% 0.22 27)` or shift slightly toward orange.
+3. **`cinematic/ColorGrade` presets do the heavy lifting.** The 10 presets in FF (`dystopia, carnival, noir, golden-hour, cyberpunk, dream, horror, vintage, ice, neon`) are not just LUTs — they shift the entire palette. Use them as the foundation, then layer accents on top.
+4. **Caption text needs background plates or stronger weight.** White text on busy footage will fail at 4.5:1 over half the frames. `text/SubtitleOverlay` should default to a 70%-opacity black plate behind the text, or a 500-weight font with text-shadow.
+
+**Bridge to ColorGrade presets** (read `remotion-bridge.md` for full mapping):
+
+- `noir` → desaturated, high contrast, neutral palette only
+- `golden-hour` → warm tint shift, +chroma in oranges, -chroma in blues
+- `cyberpunk` → magenta + cyan duality, near-black background
+- `dream` → low contrast, soft tint, +luminance overall
+
+## Cross-references
+
+- For 96 industry palettes by product type: read `design-palette` skill, `references/full-palettes.md`
+- For semantic token enforcement: read `design-system` skill
+- For Tailwind v4 OKLCH setup: read `tailwind-design-system` skill
+- For ColorGrade composition: read `remotion-bridge.md` in this skill
+- For text contrast specifically: read `typography.md` in this skill
+
+## Quick checklist
+
+- [ ] No pure #000 or #FFF anywhere
+- [ ] Background tinted toward a hue (cool blue, warm yellow, neutral green-gray)
+- [ ] Single accent color, used consistently
+- [ ] WCAG AA verified for every text/background pair
+- [ ] Focus ring visible at 3:1 minimum against adjacent colors
+- [ ] Dark mode has its own surface ladder, not inverted light mode
+- [ ] Accent chroma reduced ~30% for dark mode
+- [ ] OKLCH used (with hex fallback if needed)
+- [ ] No gray text on colored backgrounds (fails AA)
+- [ ] For Remotion: chroma bumped 15–20% to compensate compression

package/.merlin-core/skills/general/mage-beauty/references/interaction-design.md

@@ -0,0 +1,99 @@
+# interaction-design — Forms, focus, loading, feedback
+
+## Charter
+
+Interaction design is where most products fail silently. The page looks fine until you tab through it and realize the focus rings vanish, the form gives no feedback on submit, the loading state is a blank screen, and the disabled button doesn't tell you why it's disabled. Beauty in interaction is invisible when it works and devastating when it doesn't. Every state has to be designed — default, hover, active, focus, disabled, loading, error, empty, success.
+
+**Note: Most principles in this reference do not apply to Remotion (non-interactive medium). For video targets, skip this file.**
+
+## Principles
+
+1. **Every interactive element has 5 states minimum.** Default, hover, focus, active, disabled. Often: loading, error, success. Designing only the default state is the most common gap.
+2. **Focus rings are non-negotiable.** Removing the default focus outline without replacing it is an accessibility crime. Use `focus-visible:ring-2 focus-visible:ring-offset-2` minimum. The ring color must hit 3:1 against adjacent surfaces.
+3. **Touch targets are 44 × 44 px minimum.** Apple HIG, Material guidelines, WCAG 2.5.5 all converge here. Smaller targets are unreachable on mobile. Add invisible padding (`hitSlop` in React Native, generous padding in CSS) if the visual element is smaller.
+4. **Loading states are mandatory for any async operation.** Skeleton screens beat spinners for perceived performance. Show structure of what's loading. Never show a blank screen for more than 200 ms.
+5. **Error messages live next to the input that caused them.** A toast notification telling you "form has errors" without showing where is hostile. Display the error inline, in red (with an icon — color alone fails colorblind users), and auto-focus the first invalid field on submit.
+6. **Disabled states explain why.** A grayed-out button with no tooltip is a dead end. `aria-disabled="true"` with a tooltip explaining "Complete the form to enable" turns frustration into progress.
+7. **Optimistic UI for fast operations.** Toggle a like, send a message, edit inline — show success immediately, roll back on failure. Waiting for the server makes the app feel slow even when it's not.
+8. **Undo over confirm.** "Are you sure you want to delete this?" is a tax on every user. A 5-second undo toast handles the same risk without breaking flow. Reserve confirmation dialogs for genuinely destructive, irreversible actions.
+
+## Form design
+
+**Progressive disclosure**: show 3–5 fields first, hide advanced options behind "More options ▾". Long forms are abandoned. Even a 2-step wizard converts better than a single 12-field form.
+
+**Labels above inputs, always.** Floating labels look clever and fail for screen readers, fail when the field is pre-filled, fail at small sizes. Standard label-above is boring and works perfectly.
+
+**Input types matter:**
+
+- `type="email"` — auto-correct off, keyboard with `@`
+- `type="tel"` — numeric keypad on mobile
+- `type="url"` — keyboard with `/`, `.`, `:`
+- `type="number"` for actual numbers (not phone numbers)
+- `inputmode="numeric"` for OTP/PIN inputs
+
+**Validation timing:**
+
+- On blur: format checks (email looks like email, phone has enough digits)
+- On submit: server validation, business rules
+- Never on every keystroke (jarring, especially for password rules)
+
+**Submission states:**
+
+1. Idle (default button)
+2. Submitting (button disabled + spinner inside the button, NOT replacing the button — keeps layout stable)
+3. Success (brief confirmation, then progress)
+4. Error (inline, near the bad field, focus moved there, page scrolled into view)
+
+**Autosave for long forms.** Forms with 5+ fields should save drafts to localStorage every 2–3 seconds. Lost work from a navigation accident is unacceptable.
+
+## Focus management
+
+**Tab order should be logical.** Browser default tab order follows DOM order. If the visual layout differs (e.g., 2-column form), make sure DOM order matches reading order, not visual position.
+
+**Skip link as first focusable element.** `<a href="#main" class="sr-only focus:not-sr-only">Skip to content</a>`. Without this, keyboard users wade through nav on every page.
+
+**Trap focus in modals.** Tab from inside a modal must stay inside until dismissed. Esc closes. Focus returns to the trigger element on close.
+
+**Visible focus on every interactive element.** Buttons, links, inputs, custom controls. The ring must persist for at least 200 ms after activation so the user sees where focus landed.
+
+## Loading patterns
+
+**Skeleton screens** > spinners for content load. Match the shape of what's coming.
+
+**Optimistic loaders** for buttons: spinner inside the button, button text either disappears or changes to "Saving…", layout stays stable.
+
+**Progress bars for known-duration tasks** (file upload, video render). Spinners only when duration is unknown.
+
+**No spinners under 200 ms.** Operations that complete in 100 ms with a 50 ms loading flash feel broken. Either show no indicator or guarantee the indicator stays for ≥400 ms.
+
+## Empty states are designed
+
+A blank list with "No items" is a missed opportunity. Empty states should:
+
+1. Explain what would be there (context)
+2. Show the user how to add the first item (action)
+3. Use illustration sparingly (custom > stock)
+
+## Cross-references
+
+- For form patterns full catalog: read `design-ux-patterns` skill, `references/ux-guidelines.md`
+- For motion timing on hover/focus: read `motion-design.md` in this skill
+- For UX copy on errors and labels: read `voice-and-microcopy.md` in this skill
+- For visual focus ring color choices: read `color-and-contrast.md` in this skill
+
+## Quick checklist
+
+- [ ] Every interactive element has visible focus state
+- [ ] Touch targets ≥ 44 × 44 px
+- [ ] Loading states on all async operations
+- [ ] Skeleton screens preferred over spinners for content
+- [ ] No spinner flicker under 200 ms
+- [ ] Error messages inline next to the invalid input
+- [ ] Disabled states explain why (tooltip or aria)
+- [ ] Optimistic UI for fast toggles
+- [ ] Undo for reversible destructive actions
+- [ ] Progressive disclosure on long forms
+- [ ] Labels above inputs (no floating labels)
+- [ ] Skip-to-content link as first focusable
+- [ ] Modal focus trap + Esc close + focus return
+- [ ] Tab order matches reading order

package/.merlin-core/skills/general/mage-beauty/references/motion-design.md

@@ -0,0 +1,90 @@
+# motion-design — Easing, stagger, reduced-motion, video-first
+
+## Charter
+
+Motion is the language that says "someone cared about this." Static screens can pass for competent; motion is where craftsmanship shows. Most AI-generated motion fails for three reasons: bounce easing (feels dated since 2018), uniform timing across all elements (no rhythm), and zero respect for `prefers-reduced-motion`. Beauty in motion comes from physics-grade easing, deliberate stagger, faster exits than entrances, and never animating just because you can.
+
+## Principles
+
+1. **Use spring physics or cubic-bezier curves, never linear.** Linear easing is robotic. Bounce/elastic feels juvenile. The professional defaults: `ease-out` (cubic-bezier(0.16, 1, 0.3, 1)) for entrances, `ease-in` (cubic-bezier(0.7, 0, 0.84, 0)) for exits, `ease-in-out` for transformations. Or use spring with `stiffness 300, damping 30`.
+2. **Stagger reveals 50–100 ms apart.** A list of 5 items animating in simultaneously feels like a glitch. Stagger 80 ms apart (so the eye reads the cascade) and the same list feels intentional.
+3. **Exits are faster than entrances.** Entrance 300–400 ms, exit 150–200 ms. Users perceive fast as "responsive" and slow as "deliberate." Apply the right speed to each.
+4. **Hover states 100–200 ms.** Anything over 250 ms on hover feels sluggish. Anything under 80 ms feels jumpy. Sweet spot is 150 ms.
+5. **Respect `prefers-reduced-motion`.** Wrap all non-essential animation in `@media (prefers-reduced-motion: no-preference)`. Page-load animations, scroll-triggered effects, decorative particles — all should disappear when the user has opted out. Loading indicators and progress bars stay (functional motion).
+6. **Animate transform and opacity, never width/height/margin.** GPU-accelerated properties (transform, opacity, filter) hit 60 fps cheaply. Animating layout properties triggers reflow and stutters on weaker devices.
+7. **Motion has a rhythm signature.** A product that animates everything at 200 ms feels different from one at 400 ms. Pick a base duration (300 ms recommended) and let it set the tempo.
+8. **Don't animate just to animate.** A page-load reveal where 47 elements stagger in over 4 seconds is not delightful — it's a tax on the user's attention. Animate to clarify, not to perform.
+
+## Web application
+
+**Tokens for consistency:**
+
+```css
+@theme {
+  --duration-fast: 150ms;
+  --duration-base: 300ms;
+  --duration-slow: 500ms;
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+```
+
+**Common patterns:**
+
+- **Page load reveal** — staggered fade-in-up, 80 ms between elements, 400 ms duration each
+- **Scroll-triggered** — Intersection Observer + transform/opacity, single trigger (don't re-animate on re-scroll)
+- **Hover micro-interactions** — transform: translateY(-2px), scale(1.02), shadow shift — 150 ms `ease-out`
+- **Modal entrance** — backdrop fade-in (200 ms) + modal scale(0.96 → 1) + fade-in (300 ms `ease-out`)
+- **List re-order** — FLIP technique (First Last Invert Play) for smooth reordering
+- **Loading skeleton** — shimmer gradient, 1.5 s loop, no easing (linear is correct here)
+
+**Framer Motion (React):** the modern default. Spring presets `default`, `gentle`, `wobbly` cover most cases. `whileHover`, `whileTap`, `whileInView` for declarative interactions.
+
+## Remotion application
+
+Video is overwhelmingly a motion medium. The principles above apply, but FF's component library encodes specific behaviors:
+
+**`animation/` bucket:**
+
+- `SpringEntrance` — spring-based reveal, configurable stiffness/damping
+- `StaggeredList` — automatically staggers child elements 80 ms apart
+- `FadeIn` / `SlideIn` / `ZoomIn` — atomic primitives, used as building blocks
+
+**`cinematic/` bucket:**
+
+- `CameraMotion` (14 presets): Ken Burns (slow drift), dolly (forward push), pan (lateral), tilt (vertical), drift (random gentle), breathe (zoom in/out cycle). Pick by emotion: Ken Burns = nostalgic, dolly = urgent, breathe = meditative.
+- `TransitionEffect` library: cross-dissolve (default safe choice), fade (clean break), glitch (energy/disruption), wipe (directional movement), flip (reveal). Match the transition to the content shift — same scene = dissolve, scene change = fade, energy spike = glitch.
+- `ParticleSystem` — sparks, confetti, embers, snow, fireflies, glitch-blocks. Use sparingly. One particle effect per video maximum.
+
+**Timing for video:**
+
+- **Text reveal**: 12 frames (400 ms at 30 fps) for titles, 8 frames for subtitles
+- **Stagger between text lines**: 6–8 frames (200–270 ms at 30 fps)
+- **Transition between scenes**: 18–24 frames (600–800 ms) for narrative content, 6–10 frames for fast-cut energetic
+- **Camera motion duration**: full segment length (don't end the camera move before the cut)
+
+**`dataviz/Counter` arrival pacing:**
+A counter from 0 to 1247 over 60 frames feels different from over 90 frames. Slower for big numbers (financial impact), faster for small numbers (engagement metrics). Always end the count 6 frames before the cut so the viewer reads the final value.
+
+## Cross-references
+
+- For Remotion component composition: read `remotion-bridge.md` in this skill
+- For text reveal animations specifically: read `typography.md` in this skill
+- For hover/focus interaction patterns: read `interaction-design.md` in this skill
+- For animation libraries detail: see Merlin's `frontend-ui-animator` skill (if available)
+
+## Quick checklist
+
+- [ ] No bounce or elastic easing on UI motion
+- [ ] No linear easing except for loading shimmers
+- [ ] Stagger reveals 50–100 ms apart
+- [ ] Exits faster than entrances
+- [ ] Hover states 100–200 ms
+- [ ] Animate transform/opacity only (no width/height/margin)
+- [ ] `prefers-reduced-motion` respected for non-essential animation
+- [ ] Single base duration token used consistently
+- [ ] For Remotion: camera motion runs the full segment
+- [ ] For Remotion: counter ends 6 frames before cut
+- [ ] For Remotion: max one particle system per video
+- [ ] No animation that exists "just because"

package/.merlin-core/skills/general/mage-beauty/references/remotion-bridge.md

@@ -0,0 +1,187 @@
+# remotion-bridge — Web principles → renderer Remotion components
+
+## Charter
+
+This file is the canonical translation layer between the 8 thematic references in this skill and the renderer's 9 Remotion component buckets. When a verb runs against a Remotion target, this file is loaded first — it tells the verb which thematic reference applies to which bucket, and what the bucket-specific overrides are.
+
+The 9 buckets in the renderer (`<renderer>/src/components/`):
+
+- `animation/` — primitive motion (FadeIn, SlideIn, ZoomIn, SpringEntrance, StaggeredList)
+- `text/` — typographic components (Title, Subtitle, Paragraph, Counter, Typewriter, WordHighlight, SubtitleOverlay)
+- `layout/` — spatial composition (CenteredContent, SplitScreen, Overlay, FullBleed, Grid)
+- `media/` — content carriers (BackgroundMedia, ImageGallery, VideoEmbed, AudioLayer)
+- `scene/` — composed segments (IntroScene, ContentScene, QuoteScene, ListScene, ComparisonScene, DataVizScene, CTAScene, OutroScene)
+- `cinematic/` — high-impact effects (ColorGrade, CameraMotion, ParticleSystem, TransitionEffect, CinematicSegment, VideoLayerStack)
+- `dataviz/` — quantitative storytelling (BarChart, ProgressBar, StatCounter)
+- `education/` — instructional overlays (ClassSubtitles, LowerThird)
+- `music/` — music-video specific (AtmosphericOverlay, LyricsOverlay, EnergyBattery, SegmentTimeline, VideoSegment)
+
+---
+
+## Web principle → Remotion bucket map
+
+| Web principle (reference)      | Primary Remotion buckets                                                                | Notes                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| typography.md                  | `text/`, `education/`                                                                   | Letter-spacing animatable; weights ≥500 (compression) |
+| color-and-contrast.md          | `cinematic/ColorGrade`, all visible buckets                                             | Bump chroma 15–20% to compensate H.264                |
+| spatial-design.md              | `layout/`, `scene/`                                                                     | Safe areas per platform are mandatory                 |
+| motion-design.md               | `animation/`, `cinematic/CameraMotion`, `cinematic/TransitionEffect`, `dataviz/Counter` | Stagger 6–8 frames; durations in frames not ms        |
+| interaction-design.md          | (skip)                                                                                  | Non-interactive medium                                |
+| responsive-and-multi-format.md | `layout/`, `scene/`                                                                     | 9 templates × 3+ aspect ratios; format ≠ crop         |
+| voice-and-microcopy.md         | `text/`, `education/`, `music/LyricsOverlay`                                            | 17 chars/sec reading speed                            |
+| anti-patterns.md               | All buckets                                                                             | Same 15 rules apply, with video-specific intensity    |
+
+---
+
+## Bucket → reference map (read these per bucket)
+
+### `animation/` (primitive motion)
+
+**Read:** motion-design.md (primary), spatial-design.md (for entrance origin), anti-patterns rule 7
+
+**Components:**
+
+- `FadeIn` / `FadeOut` — opacity 0→1 / 1→0, duration 12–18 frames default
+- `SlideIn` — translate from offset, default `from="bottom"` 24px, 12 frames `ease-out`
+- `ZoomIn` — scale 0.92→1, 12 frames spring (stiffness 300, damping 30)
+- `SpringEntrance` — spring-based combined transform
+- `StaggeredList` — auto-stagger 6 frames between children
+
+**Rules:**
+
+- Default duration 12 frames (400 ms at 30 fps)
+- Stagger between siblings 6 frames (200 ms)
+- Use spring for character (StaggeredList, SpringEntrance), use ease for clarity (FadeIn, SlideIn)
+
+### `text/` (typographic components)
+
+**Read:** typography.md (primary), motion-design.md (for reveals), color-and-contrast.md (for legibility)
+
+**Components & rules:**
+
+- `Title` — display weight (700+), letter-spacing animates from `+0.08em` → `0` over 12 frames, line height 1.1
+- `Subtitle` — body+1 size, weight 500, no letter-spacing animation
+- `Paragraph` — body size, weight 400, line height 1.4 (tighter than web)
+- `Counter` — tabular-nums always, end count 6 frames before cut
+- `Typewriter` — monospace family, char-reveal animation, fixed-width
+- `WordHighlight` — accent color shift only, no font-family swap
+- `SubtitleOverlay` — weight 500 + text-shadow OR backdrop plate at 70% opacity
+
+### `layout/` (spatial composition)
+
+**Read:** spatial-design.md (primary), responsive-and-multi-format.md (for safe areas)
+
+**Components & rules:**
+
+- `CenteredContent` — used for typographic moments (quotes, single statements)
+- `SplitScreen` — 50/50 by default; before/after, comparison, dialogue
+- `Overlay` — text/graphic over media; requires backdrop plate or text-shadow
+- `FullBleed` — edge-to-edge media, hero shots in 16:9, full-frame in 9:16
+- `Grid` — multi-cell, max 4 cells before viewer loses track
+
+**Composition by aspect:**
+
+- **9:16 vertical:** vertical hierarchy. Top-third hero, mid-third support, bottom-third CTA (above safe area)
+- **1:1 square:** single focal point, balanced. Avoid wide horizontal layouts.
+- **16:9 wide:** rule of thirds. Lower-third graphics at 80% from top.
+
+### `media/` (content carriers)
+
+**Read:** color-and-contrast.md (for media-text contrast), spatial-design.md (for placement)
+
+**Components:**
+
+- `BackgroundMedia` — image/video, requires gradient overlay if any text on top
+- `ImageGallery` — sequence of stills with transitions
+- `VideoEmbed` — embedded video segment, respects parent safe areas
+- `AudioLayer` — non-visible, but affects pacing decisions
+
+### `scene/` (composed segments)
+
+**Read:** all references (scenes are composed of all primitive types)
+
+**8 scene types:**
+
+- `IntroScene` — title + supporting elements, 60–90 frames typical
+- `ContentScene` — body content, 90–180 frames per beat
+- `QuoteScene` — single statement, large type, generous breathing room
+- `ListScene` — staggered items, 90–150 frames total
+- `ComparisonScene` — uses `layout/SplitScreen`
+- `DataVizScene` — uses `dataviz/` components
+- `CTAScene` — terminal scene, action message, 60–90 frames
+- `OutroScene` — wrap-up, brand mark, 60–90 frames
+
+### `cinematic/` (high-impact effects)
+
+**Read:** color-and-contrast.md (for ColorGrade), motion-design.md (for CameraMotion + TransitionEffect)
+
+**Components:**
+
+- `ColorGrade` (10 presets) — apply at scene level, not per-element
+  - `noir` — desaturated, high contrast, neutrals only
+  - `golden-hour` — warm tint, +chroma oranges, -chroma blues
+  - `dystopia` — desaturated, cold, low chroma overall
+  - `carnival` — high saturation, mixed warm hues
+  - `cyberpunk` — magenta + cyan duality, near-black bg
+  - `dream` — low contrast, soft tint, +luminance
+  - `horror` — desaturated, high contrast, green-tinted shadows
+  - `vintage` — warm fade, lifted blacks, lower contrast
+  - `ice` — cool tint, +chroma blues, -chroma warms
+  - `neon` — high saturation, dark bg, glow effects
+- `CameraMotion` (14 presets) — Ken Burns, dolly, pan, tilt, drift, breathe + variants. Pick by emotion.
+- `ParticleSystem` — sparks, confetti, embers, snow, fireflies, glitch-blocks. **Max one per video.**
+- `TransitionEffect` — cross-dissolve (default), fade, glitch (energy), wipe (direction), flip (reveal)
+- `CinematicSegment` — composes ColorGrade + CameraMotion + TransitionEffect into a unit
+- `VideoLayerStack` — max 4 layers per segment
+
+### `dataviz/` (quantitative)
+
+**Read:** typography.md (for tabular nums), motion-design.md (for arrival pacing), color-and-contrast.md
+
+**Components:**
+
+- `BarChart` — animated reveal, stagger bars 6 frames
+- `ProgressBar` — animated fill, end 6 frames before cut
+- `StatCounter` — count 0→N over 60 frames typical, tabular-nums
+
+### `education/` (instructional)
+
+**Read:** typography.md (for caption type), voice-and-microcopy.md (for tone), color-and-contrast.md
+
+**Components:**
+
+- `ClassSubtitles` — natural phrase-boundary breaks, never mid-clause, max 50 chars/cue at 17 chars/sec
+- `LowerThird` — 3 lines max (name / role / context), positioned 80% from top in 16:9
+
+### `music/` (music-video specific)
+
+**Read:** motion-design.md (for sync), voice-and-microcopy.md (for lyrics), color-and-contrast.md
+
+**Components:**
+
+- `AtmosphericOverlay` — color-tinted layer for mood
+- `LyricsOverlay` — cue-word timed accent shifts
+- `EnergyBattery` — visualization of segment energy
+- `SegmentTimeline` — meta-component showing structure
+- `VideoSegment` — base music-video segment unit
+
+---
+
+## Verb-specific Remotion overrides
+
+When these verbs run on Remotion targets, additional rules apply:
+
+| Verb             | Additional rule                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `verb-cinematic` | Stack ColorGrade + CameraMotion + TransitionEffect. Pick all three from the same emotional register (e.g., noir + dolly + glitch for dystopia). |
+| `verb-animate`   | Default to `cinematic/CameraMotion` over `animation/` primitives for scenes; reserve `animation/` for individual element entrances.             |
+| `verb-colorize`  | Always start with a ColorGrade preset before tweaking individual elements.                                                                      |
+| `verb-typeset`   | Verify weights ≥500 for compression survival.                                                                                                   |
+| `verb-rebrand`   | Choose ColorGrade preset first; let it dictate accent shifts across all `text/` components.                                                     |
+| `verb-overdrive` | Maximum stack: ColorGrade + CameraMotion + ParticleSystem + 2 TransitionEffect variants per scene transition. Use sparingly.                    |
+
+## Cross-references
+
+- For each thematic reference: see the corresponding `references/<name>.md` in this skill
+- For actual component implementations: `<your-renderer>/src/components/<bucket>/`
+- For schemas (Zod): `<your-renderer>/src/schemas/`