From f8fad54261d53652cf03e96bd2ccc43fd1d2fafe Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 26 Mar 2026 11:15:16 -0700 Subject: [PATCH] feat(skill): house style guide for compose-video (#59) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(cli): non-interactive by default, --human-friendly for UI Following ElevenLabs CLI pattern: default mode is agent-friendly (flag-driven, plain text output, fail fast on missing args). Interactive clack UI is opt-in via --human-friendly. Init command: - --template required in default mode (errors with example if missing) - --video / --audio flags for media input - --skip-skills / --skip-transcribe to control optional steps - --human-friendly enables the existing interactive prompts - --help shows examples for every flag combination - Transcription runs automatically in default mode (unless --skip-transcribe) - Plain console.log output, process.exit(1) on errors Skills command: - Added --human-friendly flag - Added examples to --help output Co-Authored-By: Claude Opus 4.6 (1M context) * fix(cli): improve --help documentation and add --yes/--check to upgrade - upgrade: add --yes and --check flags to skip interactive prompt - benchmark: clarify description — preset fps/quality/worker configs - browser: describe each subcommand (ensure/path/clear) in help - docs: list available topics inline in --help output Co-Authored-By: Claude Opus 4.6 (1M context) * feat(skill): add house style guide with motion defaults, palettes, and anti-defaults When no visual-style.md is provided, compose-video now follows house-style.md for professional output quality. Includes: - Motion: easing variety, timing, entrance patterns, choreography - Sizing: text scale contrast, element fill, travel distance - Visual depth: gradient/shadow/texture guidance - Typography: weight contrast, tracking, case - Anti-defaults: table of generic AI patterns to avoid - 72 curated color palettes across 9 categories - Content interpretation: generate real content, not prompt text Eval-validated across 5 iterations with 50+ test compositions. Co-Authored-By: Claude Opus 4.6 (1M context) * feat(skill): add container anti-default and typography guidance - Anti-default: discourage card/container patterns in favor of content placed directly on canvas (professional video style vs web UI style) - Typography section: weight contrast, deliberate case, tracking, one typeface at two weights - Visual depth: softened to avoid templating (content-appropriate, not every-composition-the-same) Co-Authored-By: Claude Opus 4.6 (1M context) * feat(skill): add scene pacing guidance to house style Three-phase composition structure: build (staggered entrances), breathe (subtle motion to keep holds alive), resolve (fast exits with intention). Prevents front-loading all animation into the first second and dead static holds. Co-Authored-By: Claude Opus 4.6 (1M context) * fix(skill): replace zoom-in monoculture with ambient motion variety The viewport scale and end emphasis code examples were being copied verbatim to every composition. Now offers 6 ambient motion options (pan, rotation, scale in/out, parallax, color shift, stillness) and 4 ending options instead of always zooming. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- skills/compose-video/SKILL.md | 2 + skills/compose-video/house-style.md | 127 ++++++++++++++++++ .../compose-video/palettes/bold-energetic.md | 14 ++ .../compose-video/palettes/clean-corporate.md | 14 ++ skills/compose-video/palettes/dark-premium.md | 14 ++ skills/compose-video/palettes/jewel-rich.md | 14 ++ skills/compose-video/palettes/monochrome.md | 14 ++ skills/compose-video/palettes/nature-earth.md | 14 ++ .../compose-video/palettes/neon-electric.md | 14 ++ skills/compose-video/palettes/pastel-soft.md | 14 ++ .../compose-video/palettes/warm-editorial.md | 14 ++ 11 files changed, 255 insertions(+) create mode 100644 skills/compose-video/house-style.md create mode 100644 skills/compose-video/palettes/bold-energetic.md create mode 100644 skills/compose-video/palettes/clean-corporate.md create mode 100644 skills/compose-video/palettes/dark-premium.md create mode 100644 skills/compose-video/palettes/jewel-rich.md create mode 100644 skills/compose-video/palettes/monochrome.md create mode 100644 skills/compose-video/palettes/nature-earth.md create mode 100644 skills/compose-video/palettes/neon-electric.md create mode 100644 skills/compose-video/palettes/pastel-soft.md create mode 100644 skills/compose-video/palettes/warm-editorial.md diff --git a/skills/compose-video/SKILL.md b/skills/compose-video/SKILL.md index 540e76450..7227394c3 100644 --- a/skills/compose-video/SKILL.md +++ b/skills/compose-video/SKILL.md @@ -18,6 +18,8 @@ Before writing HTML, think at a high level: For small edits (fix a color, adjust timing, add one element), skip straight to the rules. +When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for motion defaults, sizing, and color palettes. + ## Data Attributes ### All Clips diff --git a/skills/compose-video/house-style.md b/skills/compose-video/house-style.md new file mode 100644 index 000000000..09f333d76 --- /dev/null +++ b/skills/compose-video/house-style.md @@ -0,0 +1,127 @@ +# House Style + +Defaults when no `visual-style.md` or animation direction is provided. These raise the floor — not a brand identity, just professional quality. + +## Before Writing HTML + +1. **Interpret the prompt.** Generate real content for the topic — don't use the prompt text as body copy. A recipe lists real ingredients. A stats dashboard shows the actual numbers given. A product showcase names real features and specs. A sci-fi HUD has actual crosshairs and readouts, not a heading that says "sci-fi HUD." +2. **Pick a palette.** First decide: does this content call for a light or dark canvas? Food, weddings, children, wellness, education, lifestyle, nature, and celebrations → light palette (Warm/Editorial, Clean/Corporate, Nature/Earth, Pastel/Soft). Tech, finance, cinema, nightlife, horror, gaming, and premium → dark palette. Then load the file and pick one palette. Declare your bg, fg, and accent colors before writing any code. +3. **Pick a typeface.** Don't reach for Sora, Space Grotesk, Outfit, Playfair Display, Cormorant Garamond, or Bodoni Moda — they're overused. Explore the full range of Google Fonts. Serif for editorial, mono for technical, display for impact, handwritten for personal. +4. **Pick your entrance patterns.** Plan how elements enter — never use the same entrance pattern twice in a composition. + +## Motion + +### Easing + +Vary your eases. Don't use the same ease on more than 2 tweens in a composition. Pick from the full GSAP vocabulary: + +`power1-4.in/out/inOut`, `back.out(1.4-2.5)`, `elastic.out(1, 0.3-0.5)`, `circ.out`, `expo.out`, `sine.inOut`, `steps(n)` + +A few principles: + +- Opacity fades should be gentle (`power1` or `none`) — don't draw attention to the fade itself +- Overshoot on scale or position feels alive — `back.out` or `elastic.out` +- Snappy moves want `expo.out` or `power4.out` — fast departure, hard stop +- Smooth arcs want `sine.inOut` or `circ.inOut` — no hard edges + +### Timing + +- **0.3–0.6s** for most moves. Shorter than you think. +- **Exits 2x faster** than entrances. +- **Nothing starts at t=0** — offset first animation 0.1–0.3s. +- **Overlap entries** — next element starts before previous finishes. Use GSAP position parameter: `tl.to(el, {...}, "-=0.15")` +- **Stagger with easing**, not uniform: `stagger: { each: 0.08, ease: "power2.in" }` + +### Entrance Patterns + +Never fade-in alone. Combine opacity with at least one transform. Never repeat the same entrance in a composition. Invent your own combinations — mix properties creatively: + +- **Position** — x, y, or both (diagonal). Vary the axis and distance per element. +- **Scale** — from smaller or larger. Pair with overshoot easing. +- **Rotation** — small angles (3-12deg) feel intentional. Large angles (45-180deg) feel dramatic. +- **Clip path** — `inset()`, `circle()`, `polygon()`. Direction matters: left, right, top, center outward. +- **Blur + opacity** — `filter: blur(8px)` combined with opacity creates a focus-pull effect. +- **Letter spacing / word spacing** — for text, animate tracking from wide to tight or vice versa. +- **Skew** — `skewX` or `skewY` gives a motion-blur feeling without actual blur. +- **3D transforms** — `rotationX`, `rotationY` with `transformPerspective` for depth. + +Don't copy the same combination across compositions. Each composition should feel like it has its own motion personality. + +### Choreography + +- **Combined transforms** — animate 2–3 properties together (position + scale, rotation + opacity), not one at a time. +- **Coordinated entry** — when a new element enters, existing elements react. Anchor moves, follower tracks. +- **Ambient motion** — keep the composition alive during holds. Don't default to zoom-in every time. Pick one per composition: + - Slow pan (x or y drift on a container) + - Subtle rotation (0.5–2deg over several seconds) + - Scale push or pull (zoom in OR out — both work) + - Parallax layers (background moves slower than foreground) + - Color/opacity shift on an accent element + - No ambient motion at all — stillness can be powerful +- **End with intention** — don't always zoom at the end. Options: snap to black, fade to stillness, final element snaps into place, a hard cut. Vary this across compositions. + +### Scene Pacing + +Structure compositions in three phases — don't front-load everything: + +- **Build (0–30%)** — elements enter. Stagger arrivals so there's a sequence, not a simultaneous dump. +- **Breathe (30–70%)** — content is visible. Keep it alive with subtle motion: slow camera push, gentle drift, a color shift, a pulsing accent. Static holds feel dead. +- **Resolve (70–100%)** — elements exit or the composition punctuates. Exits are faster than entrances. End with intention — a final zoom, a fade to black, a snap to stillness. + +Don't crowd the build phase. If you have 6 elements, let 2-3 enter, breathe, then bring in the rest. Layers of reveals beat a single wave. + +## Sizing + +- **Text scale contrast** — headings at 3–5x body size, not 1.5x. Big contrast reads as cinematic. +- **Element fill** — hero elements fill 60–80% of the frame. Don't leave them floating at 30%. +- **Travel distance** — entrance moves should cover 80–200px. Under 20px looks like a glitch. +- **Overshoot** — 5–10% overshoot reads as energy. Under 2% reads as a bug. + +## Visual Depth + +Flat single-color backgrounds look digital. Avoid pure solid backgrounds — add some visual layer to break the flatness. Options include gradients, subtle background shapes, texture, shadows on cards, or border accents. Pick what fits the content — not every composition needs the same treatment. A luxury product wants subtle gradients. A children's show wants bold shapes. A news graphic wants clean borders. + +## Typography + +Beyond choosing a typeface: + +- **Weight contrast** — pair a heavy weight (700-900) headline with a light weight (300-400) body. Don't use the same weight on everything. +- **Case deliberately** — ALL CAPS for labels and short text (under 5 words). Sentence case for longer text. Don't uppercase paragraphs. +- **Tracking** — tight tracking (-0.02em) on large headlines. Normal or wide tracking on small labels. +- **One typeface, two weights** — don't mix typefaces unless you have a reason. One family at two weights creates more hierarchy than two families at one weight each. + +## Anti-Defaults + +Things the LLM reaches for that look generic. Do the opposite. + +| Default | Instead | +| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Inter / Roboto / system font | Pick a typeface with character — commit to it | +| `#f5f5f5` / `#333` / mid-gray | Go high contrast. Near-black or near-white, not the middle | +| Blue accent `#3b82f6` | No blue unless the user asks for blue | +| Everything centered, equal weight | One focal point per frame. Lead the eye somewhere | +| Uniform spacing | Tight clusters and open gaps. Vary deliberately | +| Same entrance on every element | Never repeat an entrance pattern in a composition | +| 1s duration on everything | 0.3–0.6s. Shorter than you think | +| `power2.out` on everything | Vary eases — no more than 2 independent tweens with the same ease (staggers are exempt) | +| Always dark background | Match the content: food, weddings, kids, wellness, education → light palette | +| Inventing colors per-element | Declare palette up front. Every element references it | +| Content in cards/containers | Place content directly on the canvas — separate with space and alignment, not box boundaries. Cards are a web pattern. Exception: dashboards, lower thirds, captions over footage | + +## Palettes + +Before writing any HTML, declare your palette: one background, one foreground, one accent. Pick from a category below — don't invent colors. **Match palette to content** — don't default to dark. Children's content, food, weddings, wellness, education, and lifestyle content should typically use light or warm palettes. + +| Category | Use for | File | +| ----------------- | --------------------------------------------- | ---------------------------------------------------------- | +| Bold / Energetic | Product launches, social media, announcements | [palettes/bold-energetic.md](palettes/bold-energetic.md) | +| Warm / Editorial | Storytelling, documentaries, case studies | [palettes/warm-editorial.md](palettes/warm-editorial.md) | +| Dark / Premium | Tech, finance, luxury, cinematic | [palettes/dark-premium.md](palettes/dark-premium.md) | +| Clean / Corporate | Explainers, tutorials, presentations | [palettes/clean-corporate.md](palettes/clean-corporate.md) | +| Nature / Earth | Sustainability, outdoor, organic | [palettes/nature-earth.md](palettes/nature-earth.md) | +| Neon / Electric | Gaming, tech, nightlife | [palettes/neon-electric.md](palettes/neon-electric.md) | +| Pastel / Soft | Fashion, beauty, lifestyle, wellness | [palettes/pastel-soft.md](palettes/pastel-soft.md) | +| Jewel / Rich | Luxury, events, sophisticated | [palettes/jewel-rich.md](palettes/jewel-rich.md) | +| Monochrome | Dramatic, typography-focused | [palettes/monochrome.md](palettes/monochrome.md) | + +**Escape hatch:** If no category fits, derive from the color wheel — pick a base hue, take its complement or triadic, pull a dark from OKLCH lightness 15% and a light from 90%. diff --git a/skills/compose-video/palettes/bold-energetic.md b/skills/compose-video/palettes/bold-energetic.md new file mode 100644 index 000000000..e60e2d76a --- /dev/null +++ b/skills/compose-video/palettes/bold-energetic.md @@ -0,0 +1,14 @@ +# Bold / Energetic + +Product launches, social media, announcements, high-energy content. + +``` +#FFBE0B #FB5607 #FF006E #8338EC #3A86FF +#F72585 #7209B7 #3A0CA3 #4361EE #4CC9F0 +#EF476F #FFD166 #06D6A0 #118AB2 #073B4C +#FF595E #FFCA3A #8AC926 #1982C4 #6A4C93 +#9B5DE5 #F15BB5 #FEE440 #00BBF9 #00F5D4 +#390099 #9E0059 #FF0054 #FF5400 #FFBD00 +#3D348B #7678ED #F7B801 #F18701 #F35B04 +#FFBC42 #D81159 #8F2D56 #218380 #73D2DE +``` diff --git a/skills/compose-video/palettes/clean-corporate.md b/skills/compose-video/palettes/clean-corporate.md new file mode 100644 index 000000000..a4b79c939 --- /dev/null +++ b/skills/compose-video/palettes/clean-corporate.md @@ -0,0 +1,14 @@ +# Clean / Corporate + +Explainers, tutorials, presentations, professional content. + +``` +#FFFCF2 #CCC5B9 #403D39 #252422 #EB5E28 +#22223B #4A4E69 #9A8C98 #C9ADA7 #F2E9E4 +#3D5A80 #98C1D9 #E0FBFC #EE6C4D #293241 +#2B2D42 #8D99AE #EDF2F4 #EF233C #D90429 +#353535 #3C6E71 #FFFFFF #D9D9D9 #284B63 +#E7ECEF #274C77 #6096BA #A3CEF1 #8B8C89 +#CFDBD5 #E8EDDF #F5CB5C #242423 #333533 +#2F6690 #3A7CA5 #D9DCD6 #16425B #81C3D7 +``` diff --git a/skills/compose-video/palettes/dark-premium.md b/skills/compose-video/palettes/dark-premium.md new file mode 100644 index 000000000..84f81d562 --- /dev/null +++ b/skills/compose-video/palettes/dark-premium.md @@ -0,0 +1,14 @@ +# Dark / Premium + +Tech, finance, luxury, cinematic content. + +``` +#000000 #14213D #FCA311 #E5E5E5 #FFFFFF +#000814 #001D3D #003566 #FFC300 #FFD60A +#0D1B2A #1B263B #415A77 #778DA9 #E0E1DD +#0D1321 #1D2D44 #3E5C76 #748CAB #F0EBD8 +#011627 #FDFFFC #2EC4B6 #E71D36 #FF9F1C +#0B090A #161A1D #660708 #A4161A #E5383B +#001427 #708D81 #F4D58D #BF0603 #8D0801 +#001524 #15616D #FFECD1 #FF7D00 #78290F +``` diff --git a/skills/compose-video/palettes/jewel-rich.md b/skills/compose-video/palettes/jewel-rich.md new file mode 100644 index 000000000..fbd5542b2 --- /dev/null +++ b/skills/compose-video/palettes/jewel-rich.md @@ -0,0 +1,14 @@ +# Jewel / Rich + +Luxury, events, sophisticated, high-end content. + +``` +#5F0F40 #9A031E #FB8B24 #E36414 #0F4C5C +#780000 #C1121F #FDF0D5 #003049 #669BBC +#10002B #240046 #3C096C #5A189A #7B2CBF +#355070 #6D597A #B56576 #E56B6F #EAAC8B +#6F1D1B #BB9457 #432818 #99582A #FFE6A7 +#231942 #5E548E #9F86C0 #BE95C4 #E0B1CB +#461220 #8C2F39 #B23A48 #FCB9B2 #FED0BB +#780116 #F7B538 #DB7C26 #D8572A #C32F27 +``` diff --git a/skills/compose-video/palettes/monochrome.md b/skills/compose-video/palettes/monochrome.md new file mode 100644 index 000000000..e26d24737 --- /dev/null +++ b/skills/compose-video/palettes/monochrome.md @@ -0,0 +1,14 @@ +# Monochrome + +Dramatic, typography-focused, serious content. + +``` +#F8F9FA #E9ECEF #DEE2E6 #CED4DA #ADB5BD #6C757D #495057 #343A40 #212529 +#0466C8 #0353A4 #023E7D #002855 #001233 +#012A4A #013A63 #01497C #2A6F97 #468FAF #89C2D9 +#582F0E #7F4F24 #936639 #A68A64 #C2C5AA +#463F3A #8A817C #BCB8B1 #F4F3EE #E0AFA0 +#03071E #370617 #6A040F #9D0208 #DC2F02 #F48C06 #FFBA08 +#590D22 #800F2F #A4133C #FF4D6D #FF8FA3 #FFCCD5 +#220901 #621708 #941B0C #BC3908 #F6AA1C +``` diff --git a/skills/compose-video/palettes/nature-earth.md b/skills/compose-video/palettes/nature-earth.md new file mode 100644 index 000000000..cc3cb9d63 --- /dev/null +++ b/skills/compose-video/palettes/nature-earth.md @@ -0,0 +1,14 @@ +# Nature / Earth + +Sustainability, outdoor, organic, wellness content. + +``` +#606C38 #283618 #FEFAE0 #DDA15E #BC6C25 +#DAD7CD #A3B18A #588157 #3A5A40 #344E41 +#386641 #6A994E #A7C957 #F2E8CF #BC4749 +#CAD2C5 #84A98C #52796F #354F52 #2F3E46 +#F0EAD2 #DDE5B6 #ADC178 #A98467 #6C584C +#132A13 #31572C #4F772D #90A955 #ECF39E +#6B9080 #A4C3B2 #CCE3DE #EAF4F4 #F6FFF8 +#233D4D #FE7F2D #FCCA46 #A1C181 #619B8A +``` diff --git a/skills/compose-video/palettes/neon-electric.md b/skills/compose-video/palettes/neon-electric.md new file mode 100644 index 000000000..94c3e86e8 --- /dev/null +++ b/skills/compose-video/palettes/neon-electric.md @@ -0,0 +1,14 @@ +# Neon / Electric + +Gaming, tech, nightlife, Gen Z content. + +``` +#F72585 #B5179E #7209B7 #560BAD #3A0CA3 +#70D6FF #FF70A6 #FF9770 #FFD670 #E9FF70 +#7400B8 #6930C3 #5E60CE #5390D9 #48BFE3 +#0B132B #1C2541 #3A506B #5BC0BE #6FFFE9 +#540D6E #EE4266 #FFD23F #3BCEAC #0EAD69 +#2D00F7 #6A00F4 #8900F2 #A100F2 #F20089 +#FF6D00 #FF7900 #FF8500 #FF9100 #240046 +#BBFBFF #8DD8FF #4E71FF #5409DA +``` diff --git a/skills/compose-video/palettes/pastel-soft.md b/skills/compose-video/palettes/pastel-soft.md new file mode 100644 index 000000000..f4e99c538 --- /dev/null +++ b/skills/compose-video/palettes/pastel-soft.md @@ -0,0 +1,14 @@ +# Pastel / Soft + +Fashion, beauty, lifestyle, wellness content. + +``` +#CDB4DB #FFC8DD #FFAFCC #BDE0FE #A2D2FF +#CCD5AE #E9EDC9 #FEFAE0 #FAEDCD #D4A373 +#FFD6FF #E7C6FF #C8B6FF #B8C0FF #BBD0FF +#FFA69E #FAF3DD #B8F2E6 #AED9E0 #5E6472 +#EDAFB8 #F7E1D7 #DEDBD2 #B0C4B1 #4A5759 +#555B6E #89B0AE #BEE3DB #FAF9F9 #FFD6BA +#006D77 #83C5BE #EDF6F9 #FFDDD2 #E29578 +#0081A7 #00AFB9 #FDFCDC #FED9B7 #F07167 +``` diff --git a/skills/compose-video/palettes/warm-editorial.md b/skills/compose-video/palettes/warm-editorial.md new file mode 100644 index 000000000..2b1907aac --- /dev/null +++ b/skills/compose-video/palettes/warm-editorial.md @@ -0,0 +1,14 @@ +# Warm / Editorial + +Storytelling, documentaries, case studies, narrative content. + +``` +#264653 #2A9D8F #E9C46A #F4A261 #E76F51 +#335C67 #FFF3B0 #E09F3E #9E2A2B #540B0E +#F4F1DE #E07A5F #3D405B #81B29A #F2CC8F +#F6BD60 #F7EDE2 #F5CAC3 #84A59D #F28482 +#003049 #D62828 #F77F00 #FCBF49 #EAE2B7 +#588B8B #FFFFFF #FFD5C2 #F28F3B #C8553D +#283D3B #197278 #EDDDD4 #C44536 #772E25 +#0D3B66 #FAF0CA #F4D35E #EE964B #F95738 +```