@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/mage-beauty/references/verb-quieter.md

@@ -0,0 +1,95 @@
+# verb-quieter — Tone down maximalist designs
+
+## Trigger
+
+User invokes `/beauty quieter [target]` or asks to "tone this down," "calm this," "this is too much," "more restraint," "make it whisper." Antagonist of `verb-bolder`. Used when a design is shouting where it should murmur — usually after over-amplification or template-energy maximalism.
+
+## Inputs
+
+- A target that feels visually loud, over-decorated, or trying-too-hard
+- Optional: a dimension to quiet ("quieter color only", "quieter motion")
+
+## Process
+
+1. Identify the noise sources: too many accent colors, type contrast too high, motion on every element, decorative shadows, gradient overlays, particle effects.
+2. Read relevant references: `typography.md`, `color-and-contrast.md`, `spatial-design.md`, `motion-design.md`. Anti-patterns 1, 4, 6, 8 are most relevant.
+3. Apply a **0.5x rule** per dimension to quiet:
+   - **Type:** drop one weight (700 → 500), narrow size range (delete H4, H5)
+   - **Color:** chroma cut 30%, fewer accents (3 → 1), neutrals warmer/cooler but more muted
+   - **Composition:** larger negative space, fewer elements per section, more breathing room
+   - **Motion:** longer durations (snappy → considered), fewer elements animated, subtler hover (transform: translateY(-1px) instead of -4px)
+   - **Decoration:** remove decorative shadows, simplify gradients, drop particles
+4. Anti-pattern check: quiet must not introduce new failures (no gray-on-color, no card-in-card from "removing differentiation").
+
+## Output
+
+Target file with reductions applied + before/after log.
+
+```
+Quieter applied:
+- Removed 2 accent colors (kept primary only)
+- H1 weight 800 → 600
+- Hero motion: 6 elements animating → 1 (just the title)
+- Removed text-shadow on body
+- Spacing increased ~30% across sections (more breathing)
+- Particle system removed entirely
+```
+
+## Pre-checks
+
+- [ ] No anti-patterns introduced (less ≠ flat hierarchy, less ≠ all-equal-weight)
+- [ ] Hierarchy still readable after reduction
+- [ ] Brand identity not stripped — quieter ≠ generic
+- [ ] WCAG AA still passes (lower contrast ≠ failing contrast)
+- [ ] Loading + error states still feel deliberate
+- [ ] For Remotion: pacing not killed (quieter ≠ boring)
+
+## Examples
+
+**Web target quieter pass:**
+
+```
+File: components/Pricing.tsx
+
+Before:
+- 3 accent colors (orange CTA, green checkmark, red "save")
+- H2 weight 800, decorative gradient text-fill
+- Card backgrounds at 4 different surface levels
+- Hover: scale-105 + shadow-2xl + rotate-1
+- Confetti particles on hover
+
+After:
+- 1 accent color (orange CTA), neutral text checkmarks, no red badge (replaced with subtle "Most popular" label)
+- H2 weight 600, solid color
+- 2 surface levels (default + elevated for highlighted plan)
+- Hover: scale-[1.01] + shadow-md (subtle)
+- No particles
+
+Identity preserved (still feels confident), noise gone.
+```
+
+**Remotion target quieter pass:**
+
+```
+File: scene/QuoteScene.tsx
+
+Before:
+- Title at 800 weight + LetterSpacing animation + ScaleIn + slow zoom Background
+- ColorGrade preset="neon" (very loud)
+- ParticleSystem preset="confetti"
+- TransitionEffect preset="glitch"
+
+After:
+- Title at 500 weight, simple FadeIn over 18 frames
+- ColorGrade preset="dream" (low contrast, soft tint)
+- No particles
+- TransitionEffect preset="cross-dissolve" 24 frames (slower, contemplative)
+
+Quote scenes now feel reflective instead of frantic.
+```
+
+## Cross-references
+
+- Cites: `typography.md`, `color-and-contrast.md`, `spatial-design.md`, `motion-design.md`, `anti-patterns.md`
+- Antagonist verb: `verb-bolder`
+- Sibling: `verb-distill` (when reduction goes further to "what's the essential element")

package/.merlin-core/skills/general/mage-beauty/references/verb-rebrand.md

@@ -0,0 +1,127 @@
+# verb-rebrand — Apply a different aesthetic direction holistically
+
+## Trigger
+
+User invokes `/beauty rebrand [target]` or asks to "rebrand this," "change the whole feel," "this is too corporate, make it editorial," "what if this were minimalist instead." Goes deeper than `verb-colorize` or `verb-typeset` — shifts the **entire aesthetic** in one coordinated pass. Added by mage-beauty as a native verb (not in upstream).
+
+## Inputs
+
+- A target with a current aesthetic direction
+- A new aesthetic direction (named style, reference brand, or descriptor)
+
+## Process
+
+1. Read all references — rebrand touches every dimension: `typography.md`, `color-and-contrast.md`, `spatial-design.md`, `motion-design.md`, `voice-and-microcopy.md`, `anti-patterns.md`. For Remotion: `remotion-bridge.md`.
+2. **Decode the new direction** into 6 concrete decisions:
+   - **Mood:** 3–5 adjectives describing the target feeling
+   - **Type pairing:** 2 fonts that pair on contrast
+   - **Palette:** 3–5 OKLCH values with semantic roles
+   - **Layout:** grid system + spacing rhythm + 1 break style
+   - **Motion:** base duration + easing + stagger pace
+   - **Voice:** 3 adjectives + 3 anti-adjectives
+3. Apply coordinated changes — every dimension shifts together:
+   - Type: replace heading + body families simultaneously
+   - Palette: regenerate tokens with new OKLCH values, both light + dark mode
+   - Spacing: adjust scale (tighter for editorial, looser for luxury)
+   - Motion: replace duration tokens, easing curves
+   - Microcopy: rewrite key labels in new voice
+   - For Remotion: pick a different ColorGrade + CameraMotion emotional set
+4. Verify identity coherence — every touched element should feel like the same person designed it. Mismatches signal incomplete rebrand.
+5. Anti-patterns scan one final time — rebrands often inherit AI-generic defaults if not careful.
+
+## Common rebrand directions
+
+| Direction              | Type pairing                     | Palette                                 | Spacing                        | Motion                  |
+| ---------------------- | -------------------------------- | --------------------------------------- | ------------------------------ | ----------------------- |
+| Editorial premium      | Cormorant + Inter                | warm neutrals + 1 luxe gold             | generous, single column        | slow (400 ms), ease-out |
+| Brutalist              | Space Mono + Space Mono          | high-contrast B/W + 1 saturated accent  | grid-locked, asymmetric breaks | fast (150 ms), linear   |
+| Liquid glass           | Outfit + Inter                   | dark + iridescent + transparency layers | layered overlap                | spring physics          |
+| Bento (Apple-style)    | Inter + Inter (variable weights) | tinted neutrals + 1-2 accents           | grid cells, generous           | snappy springs          |
+| Cyberpunk              | Orbitron + JetBrains Mono        | neon + black                            | tight, technical               | sharp, high stagger     |
+| Swiss minimalism       | Inter or Helvetica + Inter       | neutral grays + 1 red                   | strict 12-col grid             | minimal motion          |
+| Organic biophilic      | Lora + Nunito                    | warm earth + sage + cream               | flowing, asymmetric            | gentle springs          |
+| AI-native (deliberate) | Geist Sans + Geist Mono          | OKLCH gradients + glow                  | bento + diagonal               | spring + stagger        |
+
+## Output
+
+Target with full rebrand applied + new design tokens + voice doc + change log.
+
+```
+Rebrand applied: corporate SaaS → editorial premium
+
+Tokens (new):
+- Heading family: Inter → Cormorant Garamond (700)
+- Body family: Inter → Inter (kept, but weight 300 for editorial body)
+- Type scale: 1.25 → 1.333 (more dramatic)
+- --color-bg: oklch(98% 0.005 264) → oklch(98% 0.01 80) (warm cream)
+- --color-text: oklch(15% 0.025 264) → oklch(20% 0.05 30) (warm dark, ink-toned)
+- --color-accent: oklch(55% 0.15 264) → oklch(50% 0.20 80) (luxe gold)
+- Spacing scale: tightened (8px base → 6px base for editorial density)
+- --duration-base: 300ms → 400ms (slower, considered)
+- --ease: cubic-bezier(0.16, 1, 0.3, 1) → cubic-bezier(0.4, 0, 0.2, 1) (gentler)
+
+Voice doc (new):
+- We are: considered, generous, literary
+- We are not: punchy, casual, technical-jargony
+- We say: "Read more about the philosophy behind…"
+- We don't say: "Get started in 60 seconds"
+
+Microcopy rewrites:
+- "Try free for 14 days" → "Begin a 14-day quiet trial"
+- "Get notified" → "Subscribe for letters"
+- "Sign up" → "Become a member"
+
+Coherence: every element now reads as the same editorial publication.
+```
+
+## Pre-checks
+
+- [ ] All 6 dimensions addressed (mood/type/palette/layout/motion/voice)
+- [ ] Light + dark mode both regenerated
+- [ ] Anti-patterns scan: did the rebrand introduce any (purple gradient on "modern", Inter alone on "minimal", etc.)?
+- [ ] WCAG AA verified on every text/bg pair in the new palette
+- [ ] Voice doc updated and consistent
+- [ ] Microcopy rewrites cover key surfaces (CTAs, errors, empty states)
+- [ ] Type pairing has explicit contrast rationale
+- [ ] Motion signature differs concretely from the previous direction
+- [ ] For Remotion: ColorGrade preset reset, CameraMotion + TransitionEffect re-evaluated
+- [ ] Identity coherence test: would 8 of 10 designers identify this as one cohesive brand?
+
+## Examples
+
+**Web target rebrand pass — corporate SaaS → editorial premium:**
+
+```
+File: app/landing/page.tsx + globals.css
+
+Before: Inter everywhere, indigo + orange palette, 8 px spacing scale, 300 ms snappy motion.
+Before microcopy: "Get Started" / "14-day free trial" / "Sign up now"
+
+After: Cormorant + Inter (light), warm cream + luxe gold + ink-text, 6 px tighter spacing, 400 ms gentle motion.
+After microcopy: "Begin a 14-day quiet trial" / "Subscribe for letters" / "Become a member"
+
+Same product, different voice. Identity coherence: 9/10 designers would call this an editorial publication.
+```
+
+**Remotion target rebrand pass — corporate explainer → cinematic noir:**
+
+```
+File: scene/IntroScene.tsx + scene/ContentScene.tsx + scene/OutroScene.tsx
+
+Before: default neutral palette, no ColorGrade, hard-cut transitions, weight 500 type.
+Before pace: 200ms reveals, energetic.
+
+After: cinematic/ColorGrade preset="noir" across all scenes, cinematic/CameraMotion preset="dolly" (slow), TransitionEffect "fade" 18 frames between scenes, weight 700 + tracking-tight type, monochromatic palette only.
+After pace: 18-frame reveals, deliberate.
+
+Brand has shifted from explainer-corporate to literary-noir. Coherence verified across 3 scenes.
+```
+
+## Cross-references
+
+- Cites: ALL references in this skill (rebrand is the holistic verb)
+- For palette catalog by industry/style: `design-palette` skill
+- For typography pairing catalog: `design-typography` skill
+- For style mapping (25 styles): `design-inspiration` skill
+- Antagonist: `verb-polish` (small refinements within the existing direction); `verb-distill` (reduction within direction)
+- Companion: `verb-shape` (when starting from scratch with the new direction is cleaner than retrofitting)

package/.merlin-core/skills/general/mage-beauty/references/verb-shape.md

@@ -0,0 +1,160 @@
+# verb-shape — Plan UX/UI before code
+
+## Trigger
+
+User invokes `/beauty shape [description]` or asks to "design a [thing] before I code it," "plan the UX," "what should this look like," "give me a brief." This verb is **pre-implementation** — it produces a binding design brief, not code. It delegates heavily to Merlin's `design-inspiration` skill, which already has the brief-generation engine.
+
+## Inputs
+
+- A description of what's being built (product type, target audience, use case)
+- Optional: industry context ("for fintech", "for healthcare")
+- Optional: brand reference ("like Linear", "like Aesop")
+
+## Process
+
+1. Invoke `design-inspiration` skill's 4-phase reasoning engine:
+   - Phase 1: Analyze the request (extract product type, audience, style preferences)
+   - Phase 2: Match product type to style + palette + landing pattern (from its 20-row mapping)
+   - Phase 3: Apply industry anti-patterns (`design-inspiration` has industry-specific rules)
+   - Phase 4: Generate the binding brief
+2. Augment the brief with mage-beauty's references:
+   - Pull a typography pairing recommendation (cite `typography.md` principles)
+   - Pull a palette direction with OKLCH values (cite `color-and-contrast.md`)
+   - Choose a landing/composition pattern (`spatial-design.md`)
+   - Specify motion signature (timing tokens) per `motion-design.md`
+3. For Remotion targets: select a base ColorGrade preset and CameraMotion preset (`remotion-bridge.md`)
+4. Output the binding brief in 5 sections.
+
+## Output
+
+```
+DESIGN BRIEF — [project name]
+
+1. Mood & Tone
+   3–5 adjectives, 1 reference style, 1 emotional anchor
+
+2. Color Palette
+   3–5 OKLCH values with semantic roles (primary, bg, text, accent, error)
+   Light mode + dark mode
+
+3. Typography
+   Heading family + body family (must pair on contrast)
+   Type scale ratio (1.25 default, 1.333 editorial, 1.125 dashboard)
+   Font weights to load (max 3)
+
+4. Layout & Composition
+   Grid system (12-col / asymmetric / bento)
+   Spacing base (4 / 8 px)
+   Breakpoints
+   1 grid-break element per major section
+
+5. Motion Signature
+   Base duration token (300 ms default)
+   Easing default (cubic-bezier(0.16, 1, 0.3, 1))
+   Stagger interval (50–100 ms)
+   Reduced-motion strategy
+
+[For Remotion only:]
+6. Cinematic Stack
+   ColorGrade preset (1 of 10)
+   CameraMotion preset (1 of 14)
+   TransitionEffect default
+   Particle system (or none)
+```
+
+The brief is **binding** — once generated, all subsequent visual work conforms to it. Deviations require an explicit brief amendment.
+
+## Pre-checks
+
+- [ ] Brief covers all 5 (or 6 for Remotion) sections
+- [ ] Color values are OKLCH (or hex with OKLCH equivalent noted)
+- [ ] No anti-patterns chosen as defaults (no purple→blue gradient, no Inter alone)
+- [ ] Industry-specific rules applied (no neon for healthcare, no playful fonts for finance)
+- [ ] Type pairing has explicit contrast rationale
+- [ ] Motion signature tokens are concrete (300 ms, not "fast enough")
+
+## Examples
+
+**Web target shape (fintech dashboard):**
+
+```
+DESIGN BRIEF — Lampada Analytics Dashboard
+
+1. Mood & Tone
+   Trustworthy, dense, calm-luxurious, modern. Reference: Stripe + Linear.
+
+2. Color Palette (OKLCH)
+   --bg: oklch(98% 0.005 264)        # near-white, cool tinted
+   --surface: oklch(100% 0 0)         # pure white panels
+   --text: oklch(15% 0.025 264)       # near-black, cool
+   --primary: oklch(50% 0.15 264)     # trust blue
+   --accent: oklch(65% 0.18 27)       # signal orange (10% rule)
+   --success: oklch(55% 0.16 145)
+   --error: oklch(55% 0.20 27)
+   Dark mode: bg oklch(14% 0.025 264), surface oklch(18% 0.025 264), text oklch(96% 0.01 264).
+
+3. Typography
+   Heading: Sora (geometric sans, 600/700)
+   Body: Inter (humanist sans, 400/500)
+   Scale: 1.25 modular. Body 16 px / heading H1 49 px.
+   Weights: 400, 500, 700.
+
+4. Layout & Composition
+   12-column grid, max-width 1280 px
+   Spacing base 8 px
+   Breakpoints 640 / 768 / 1024 / 1440
+   1 grid-break: hero photo bleeds full-width while content stays constrained
+
+5. Motion Signature
+   --duration-base: 300ms
+   --ease-out: cubic-bezier(0.16, 1, 0.3, 1)
+   Stagger 80 ms between siblings
+   prefers-reduced-motion: disable all decorative animation
+
+Brief is binding. All implementation conforms.
+```
+
+**Remotion target shape (campaign reel):**
+
+```
+DESIGN BRIEF — Acme LMS Promo Reel (1080×1920)
+
+1. Mood & Tone
+   Energetic, warm, educational, generous. Reference: Duolingo's celebratory moments.
+
+2. Color Palette (OKLCH, video-bumped chroma)
+   bg: oklch(20% 0.05 30)             # warm dark
+   text: oklch(96% 0.02 80)           # warm white
+   accent: oklch(72% 0.20 50)         # warm gold
+   chroma bumped 18% to compensate H.264
+
+3. Typography
+   Heading: Outfit 700
+   Body / captions: Inter 500
+   Scale 1.333
+
+4. Composition (9:16)
+   Vertical hierarchy. Hero element top-third, body mid-third, CTA bottom-third (above 250 px caption safe area).
+   Top 200 px reserved (Instagram username).
+
+5. Motion Signature
+   Duration: 12 frames default reveal
+   Stagger: 6 frames between text lines
+   Exit: 8 frames
+
+6. Cinematic Stack
+   ColorGrade: golden-hour
+   CameraMotion: ken-burns (slow drift, nostalgic warmth)
+   TransitionEffect: cross-dissolve (default), 18 frames
+   Particles: none (clean educational feel)
+
+Brief is binding.
+```
+
+## Cross-references
+
+- Delegates 4-phase reasoning to `design-inspiration` skill
+- Cites: `typography.md`, `color-and-contrast.md`, `spatial-design.md`, `motion-design.md`, `remotion-bridge.md`
+- For palette catalog: `design-palette` skill
+- For typography pairing catalog: `design-typography` skill
+- For landing pattern catalog: `design-ux-patterns` skill

package/.merlin-core/skills/general/mage-beauty/references/verb-typeset.md

@@ -0,0 +1,109 @@
+# verb-typeset — Fix font choices, hierarchy, sizing
+
+## Trigger
+
+User invokes `/beauty typeset [target]` or asks to "fix the typography," "the hierarchy is unclear," "wrong fonts," "tighten the type." Specifically a typography pass — doesn't change color, motion, or composition.
+
+## Inputs
+
+- A target with typographic problems (Inter for everything, weak hierarchy, arbitrary sizes, bad pairing)
+
+## Process
+
+1. Read `references/typography.md` (primary). For Remotion: also `remotion-bridge.md` (text bucket section).
+2. Audit current state:
+   - Font count and family — is anything paired?
+   - Type scale — is it modular (1.25 / 1.333 / 1.125) or arbitrary?
+   - Weight range — too few (no hierarchy) or too many (visual chaos)?
+   - Body size — ≥ 16 px on screen? ≥ weight 500 in video?
+   - Line height — 1.5 body / 1.2 heading / 1.4 video subtitles?
+   - Letter-spacing — appropriate per size?
+   - Line length — body at 65–75 ch?
+3. Replace defaults:
+   - **If Inter alone:** add a distinctive heading family (Outfit, Sora, Space Grotesk, Cormorant Garamond, Playfair Display, etc.)
+   - **Type scale:** lock to 1.25 (default) or 1.333 (editorial)
+   - **Weights:** load 3 max (e.g., 400 / 500 / 700)
+4. Apply tokens, not arbitrary values.
+
+## Output
+
+Target with typography corrected + tokens added + log.
+
+```
+Typeset applied:
+- Heading family: Inter → Outfit (700 for H1/H2, 600 for H3)
+- Body remains Inter (400 / 500)
+- Type scale locked to 1.25 modular: text-base 16 → text-2xl 31 → text-4xl 49
+- Removed: text-[19px] arbitrary value at line 47 → text-lg (20)
+- Letter-spacing on H1: default → -0.04em (display tightening)
+- Line height: H1 1.4 → 1.2 (architectural feel)
+- Body line-length: full width → max-w-prose (65 ch)
+- Weights loaded: was 6 (300/400/500/600/700/800), now 3 (400/500/700)
+```
+
+## Pre-checks
+
+- [ ] At least 2 font families (heading + body) OR 1 family used with strong weight contrast
+- [ ] Modular type scale, no arbitrary px values
+- [ ] Body ≥ 16 px web / weight ≥ 500 Remotion
+- [ ] Line heights match: 1.5 body / 1.2 heading / 1.4 captions / 1.7 long-form
+- [ ] Letter-spacing applied: negative on display, positive on caps, neutral on body
+- [ ] Line length 65–75 ch on body
+- [ ] Max 3 weights per family loaded
+- [ ] `font-display: swap` on Google Font imports
+- [ ] No Inter alone (anti-pattern #1)
+- [ ] No ALL CAPS body paragraphs (anti-pattern #3)
+- [ ] No decorative text-shadow on body (anti-pattern #2)
+- [ ] For Remotion: weights ≥ 500 for compression
+
+## Examples
+
+**Web target typeset pass:**
+
+```
+File: app/landing/page.tsx + globals.css
+
+Before:
+- All Inter, weights 300/400/500/600/700/800 (6 weights loaded, ~80 KB)
+- H1: text-[42px], H2: text-[28px], H3: text-[20px] — arbitrary
+- Body: text-sm (14 px) — too small for primary content
+- Line length unbounded
+
+After:
+- Imported Outfit (heading) + Inter (body) via next/font
+- Loaded 3 weights each
+- H1: text-5xl (48 px) Outfit 700 + tracking-tight
+- H2: text-3xl (30 px) Outfit 600
+- H3: text-xl (20 px) Outfit 600
+- Body: text-base (16 px) Inter 400 / text-lg leading-relaxed for hero subtitle
+- max-w-prose on long body sections
+
+Bundle: ~80 KB → ~36 KB.
+Hierarchy reads cleanly across mobile + desktop.
+```
+
+**Remotion target typeset pass:**
+
+```
+File: scene/IntroScene.tsx
+
+Before:
+- Title: weight 400 Inter (degrades under H.264 compression)
+- Subtitle: weight 300 (catastrophically thin for video)
+
+After:
+- Title: weight 700 Outfit (display tightness)
+- Subtitle: weight 500 Inter
+- Title letter-spacing animates +0.08em → 0 over 12 frames
+- Line height: 1.1 title / 1.4 subtitle (video-tighter than web)
+- Caption (SubtitleOverlay): weight 500 + backdrop plate at 70% opacity
+
+Compression survives. Letterforms remain crisp at 8 Mbps.
+```
+
+## Cross-references
+
+- Cites: `typography.md` (primary), `remotion-bridge.md` (Remotion text bucket)
+- For 57-pairing catalog: `design-typography` skill, `references/full-pairings.md`
+- For Tailwind v4 font setup: `tailwind-design-system` skill
+- Companion: `verb-clarify` (improves the words inside the typeset hierarchy)

package/.merlin-core/skills/general/mage-beauty/references/voice-and-microcopy.md

@@ -0,0 +1,137 @@
+# voice-and-microcopy — Labels, errors, captions, tone
+
+## Charter
+
+Microcopy is the difference between an interface that respects the user and one that talks down to them. Every word is a chance to feel human or feel corporate. AI-generated UI consistently fails here: generic "Get Started" CTAs, cryptic validation errors, empty states that say nothing useful, captions that summarize the obvious. Beauty in voice comes from specificity, brevity, and a tone that's the same across the UI, the captions, and the voiceover script — one voice for one product.
+
+## Principles
+
+1. **Buttons describe the outcome.** "Save changes" beats "Submit." "Send invite" beats "OK." "Delete project permanently" beats "Confirm." The user reads the button label faster than any other text — make it tell them what happens.
+2. **Errors say what to do, not just what's wrong.** "Email is invalid" is hostile. "Use a format like name@example.com" is helpful. Always end an error with the correction path.
+3. **Empty states have three jobs.** Explain what's normally here, show the action to populate it, and stay encouraging. "No projects yet — create your first one" beats "No data found."
+4. **Tone matches the moment.** Loading: patient, brief. Error: calm, helpful. Success: warm but not effusive. Confirmation: matter-of-fact. A 200% over-cheerful "Awesome! 🎉" on every action wears thin in 30 seconds.
+5. **Avoid jargon and feature names users don't know.** "Webhook delivery failed" means nothing to half your users. "We couldn't notify your other apps about this update" means something to all of them.
+6. **One voice across modalities.** The button label, the error message, the email confirmation, the video caption, and the voiceover script should sound like the same person wrote them. Build a voice doc (3 adjectives + 3 anti-adjectives, see below).
+7. **Specificity wins.** "Recently" → "2 hours ago." "Some users" → "37 users in the last 7 days." "Available now" → "Available since Tuesday." Specificity is care made visible.
+8. **Brevity respects time.** Cut every word that doesn't earn its place. "Please be advised that..." → delete. "In order to..." → "To...". "Make sure you..." → "Check that...". Short prose isn't dumbed-down; it's harder to write.
+
+## Voice doc template
+
+A product's voice can be defined in 6 lines:
+
+```
+We are: [3 adjectives] (e.g., direct, warm, technical)
+We are not: [3 anti-adjectives] (e.g., cute, corporate, vague)
+
+We say: [example phrasing the product would use]
+We don't say: [example phrasing that's wrong for this product]
+```
+
+Every microcopy decision then maps back to this doc. New writers (or LLMs) can self-check.
+
+## Button label patterns
+
+**Outcome-first:**
+
+- "Save changes" / "Save draft" / "Save and continue"
+- "Send invite" / "Send for review"
+- "Publish post" / "Publish to all"
+- "Delete project" / "Delete permanently"
+
+**Avoid:**
+
+- "Submit" (what does it do?)
+- "OK" (what am I OK-ing?)
+- "Get Started" on every CTA (placeholder energy)
+- "Click here" (links describe the destination)
+
+## Error message patterns
+
+**Inline form errors:**
+
+- "Email looks like a typo — try `name@example.com`"
+- "Password needs 8+ characters and at least one number"
+- "This name's taken. Try `marketing-team-2`?"
+
+**System-level errors:**
+
+- "We couldn't connect to the payment provider. Try again in a moment, or contact support."
+- "The file's too big — keep videos under 500 MB."
+- "Looks like you're offline. We'll save your work locally and sync when you're back."
+
+**Avoid:**
+
+- "Error: 500" (means nothing to users)
+- "Invalid input" (which input? what's invalid?)
+- "Something went wrong" (without next-step)
+- "Please try again" alone (without context)
+
+## Empty state patterns
+
+```
+[Illustration or icon]
+[Single-sentence explanation of what's normally here]
+[Primary action button]
+[Optional secondary text or link]
+```
+
+Examples:
+
+- **Empty inbox**: "No new messages — when you get one, it'll show up here. [Compose →]"
+- **Empty project list**: "Create your first project to get started. [+ New Project]"
+- **Empty search**: "No results for `[query]`. Try fewer keywords, or [view all]."
+
+## Loading + waiting microcopy
+
+- "Loading…" is the floor
+- "Saving your changes…" is better
+- "Generating your video — this usually takes 30 seconds" is best (sets expectation)
+- For >5s waits, show progress: "Step 2 of 4: rendering scenes…"
+
+## Confirmation dialogs
+
+Reserve for genuinely destructive, irreversible actions. Always include:
+
+- What's being done (specific, including the object name: "Delete project `Q3-launch`?")
+- What happens next ("This can't be undone — 47 files will be deleted.")
+- Two clearly-labeled actions: dismiss + confirm. NEVER make "Confirm" the destructive verb without explicit re-statement.
+
+## Remotion application
+
+Captions, lower-thirds, and voice-over scripts share the voice doc with the UI. Specific rules for video:
+
+1. **Caption brevity ≈ 17 chars/second reading speed.** A 3-second clip can hold ~50 chars of caption. Anything longer cuts off comprehension.
+2. **`education/ClassSubtitles`** — break captions on natural phrase boundaries. Not mid-clause. Two short cards beat one cramped one.
+3. **`education/LowerThird`** — name + role + brief context. Three lines max. "Maria Silva / Founder, Acme Inc / Speaking at SXSW 2025."
+4. **`music/LyricsOverlay`** — match cue word timing exactly. Use accent color shift, never font-family swap.
+5. **Voice-over script tone** matches the UI tone. If the product UI says "Save draft," the voiceover doesn't say "Click submit to commit your work."
+
+**Reading speed table:**
+| Audience | Words/min | Chars/sec |
+|---|---|---|
+| Educational, careful | 140 | ~12 |
+| Default | 160 | ~14 |
+| Energetic, social | 180 | ~17 |
+| Fast-cut, hype | 200+ | ~19 |
+
+## Cross-references
+
+- For typography that holds the microcopy: read `typography.md` in this skill
+- For caption color/contrast: read `color-and-contrast.md` in this skill
+- For interaction-state UX text (errors, loading): read `interaction-design.md` in this skill
+- For copywriting depth: read Merlin's `copywriting` skill (general/)
+
+## Quick checklist
+
+- [ ] Voice doc exists (3 adjectives + 3 anti-adjectives + 2 examples)
+- [ ] Every button label describes the outcome
+- [ ] No "Submit" / "OK" / "Click here" on actions
+- [ ] Errors include the correction path
+- [ ] Empty states show the next action
+- [ ] No jargon the user wouldn't recognize
+- [ ] Loading messages set time expectations when >5 s
+- [ ] Confirmation dialogs name the specific object + consequence
+- [ ] Tone consistent UI ↔ captions ↔ voiceover
+- [ ] For Remotion: caption brevity ≤ 17 chars/sec
+- [ ] For Remotion: lower-thirds limited to 3 lines
+- [ ] Specific over generic ("2 hours ago" not "recently")