From c26d8bf6d213b80baced465014dda39bf27aa4b8 Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:27:14 -0700 Subject: [PATCH 1/2] feat(skills): adopt design.md as source of truth, replace visual-style.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace all visual-style.md references with design.md across SKILL.md and house-style.md. Add Step 0 design system gate: when design.md exists in a project, read it and use its values for all visual decisions. Add design adherence eval to Quality Checks — verifies colors, typography, corners, spacing, depth, and don'ts compliance after composition authoring. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 51 ++++++++++++++++--------------- skills/hyperframes/house-style.md | 2 +- 2 files changed, 28 insertions(+), 25 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index 5584493f3..d695b0b50 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -9,6 +9,16 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ## Approach +### Step 0: Design system + +Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project. If none exists, follow [house-style.md](./house-style.md) defaults. + +### Using design.md during construction + +If a `design.md` exists, it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +### Step 1: Plan + Before writing HTML, think at a high level: 1. **What** — what should the viewer experience? Identify the narrative arc, key moments, and emotional beats. @@ -19,27 +29,6 @@ Before writing HTML, think at a high level: For small edits (fix a color, adjust timing, add one element), skip straight to the rules. -### Visual Identity Gate - - -Before writing ANY composition HTML, you MUST have a visual identity defined. Do NOT write compositions with default or generic colors. - -Check in this order: - -1. **DESIGN.md exists in the project?** → Read it. Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints. -2. **visual-style.md exists?** → Read it. Apply its `style_prompt_full` and structured fields. (Note: `visual-style.md` is a project-specific file. `visual-styles.md` is the style library with 8 named presets — different files.) -3. **User named a style** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for the 8 named presets. Generate a minimal DESIGN.md with: `## Style Prompt` (one paragraph), `## Colors` (3-5 hex values with roles), `## Typography` (1-2 font families), `## What NOT to Do` (3-5 anti-patterns). -4. **None of the above?** → Ask 3 questions before writing any HTML: - - What's the mood? (explosive / cinematic / fluid / technical / chaotic / warm) - - Light or dark canvas? - - Any specific brand colors, fonts, or visual references? - Then generate a minimal DESIGN.md from the answers. - -Every composition must trace its palette and typography back to a DESIGN.md, visual-style.md, or explicit user direction. If you're reaching for `#333`, `#3b82f6`, or `Roboto` — you skipped this step. - - -For motion defaults, sizing, entrance patterns, and easing — follow [house-style.md](./house-style.md). The house style handles HOW things move. The DESIGN.md handles WHAT things look like. - ## Layout Before Animation Position every element where it should be at its **most visible moment** — the frame where it's fully entered, correctly placed, and not yet exiting. Write this as static HTML+CSS first. No GSAP yet. @@ -259,7 +248,7 @@ tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, - 60px+ headlines, 20px+ body, 16px+ data labels for rendered video - `font-variant-numeric: tabular-nums` on number columns -When no `visual-style.md` or animation direction is provided, follow [house-style.md](./house-style.md) for aesthetic defaults. +If no `design.md` was established in Step 0, follow [house-style.md](./house-style.md) for aesthetic defaults. ## Typography and Assets @@ -277,6 +266,7 @@ When no `visual-style.md` or animation direction is provided, follow [house-styl ## Output Checklist - [ ] `npx hyperframes lint` and `npx hyperframes validate` both pass +- [ ] Design adherence verified if design.md exists (see Quality Checks below) - [ ] Contrast warnings addressed (see Quality Checks below) - [ ] Animation choreography verified (see Quality Checks below) @@ -300,6 +290,19 @@ If warnings appear: Use `--no-contrast` to skip if iterating rapidly and you'll check later. +### Design Adherence + +If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check: + +1. **Colors** — every hex value in the composition appears in design.md's palette (accent, muted, surface, bg, fg). Flag any invented colors. +2. **Typography** — font families and weights match design.md's headline/body spec. No substitutions. +3. **Corners** — border-radius values match the declared corner style. +4. **Spacing** — padding and gap values fall within the declared density range. +5. **Depth** — shadow usage matches the declared depth level (flat = none, subtle = light, layered = glows). +6. **"What NOT to Do"** — if design.md has a don'ts section, verify none are present. + +Report violations as a checklist. Fix each one before serving. + ### Animation Map After authoring animations, run the animation map to verify choreography: @@ -333,8 +336,8 @@ Skip on small edits (fixing a color, adjusting one duration). Run on new composi - **[references/css-patterns.md](references/css-patterns.md)** — CSS+GSAP marker highlighting: highlight, circle, burst, scribble, sketchout. Deterministic, fully seekable. Read when adding visual emphasis to text. - **[references/typography.md](references/typography.md)** — Typography: font pairing, OpenType features, dark-background adjustments, font discovery script. **Always read** — every composition has text. - **[references/motion-principles.md](references/motion-principles.md)** — Motion design principles: easing as emotion, timing as weight, choreography as hierarchy, scene pacing, ambient motion, anti-patterns. Read when choreographing GSAP animations. -- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating DESIGN.md. -- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no style is specified. +- **[visual-styles.md](visual-styles.md)** — 8 named visual styles (Swiss Pulse, Velvet Standard, Deconstructed, Maximalist Type, Data Drift, Soft Signal, Folk Frequency, Shadow Cut) with hex palettes, GSAP easing signatures, and shader pairings. Read when user names a style or when generating design.md. +- **[house-style.md](house-style.md)** — Default motion, sizing, and color palettes when no design.md is specified. - **[patterns.md](patterns.md)** — PiP, title cards, slide show patterns. - **[data-in-motion.md](data-in-motion.md)** — Data, stats, and infographic patterns. - **[references/transcript-guide.md](references/transcript-guide.md)** — Transcription commands, whisper models, external APIs, troubleshooting. diff --git a/skills/hyperframes/house-style.md b/skills/hyperframes/house-style.md index a5edc4b05..6d5161552 100644 --- a/skills/hyperframes/house-style.md +++ b/skills/hyperframes/house-style.md @@ -1,6 +1,6 @@ # House Style -Creative direction for compositions when no `visual-style.md` is provided. These are starting points — override anything that doesn't serve the content. +Creative direction for compositions when no `design.md` is provided. These are starting points — override anything that doesn't serve the content. ## Before Writing HTML From fad75f45b52a9d4abeec4ac9628894eb4b550eda Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Thu, 23 Apr 2026 12:43:00 -0700 Subject: [PATCH 2/2] =?UTF-8?q?fix(skills):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20restore=20named-style=20path,=20align=20adherence=20check?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restore named-style detection in Step 0: if user names a style or mood, look up visual-styles.md and generate a design.md before falling through to house-style defaults - Restore motion/style boundary: design.md defines appearance, house-style defines motion, design.md motion rules take precedence - Soften adherence check vocabulary: don't assume specific field names, match however the user labeled their palette/don'ts sections - Add house-style consistency check for no-design.md path: palette consistency across scenes + lazy defaults audit Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/hyperframes/SKILL.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/skills/hyperframes/SKILL.md b/skills/hyperframes/SKILL.md index d695b0b50..f598a4be9 100644 --- a/skills/hyperframes/SKILL.md +++ b/skills/hyperframes/SKILL.md @@ -11,11 +11,17 @@ HTML is the source of truth for video. A composition is an HTML file with `data- ### Step 0: Design system -Check for a `design.md` in the project root. If one exists, read it — it defines colors, typography, motion, and mood for all compositions in this project. If none exists, follow [house-style.md](./house-style.md) defaults. +Check for a `design.md` in the project root: + +1. **design.md exists?** → Read it. It defines colors, typography, motion, and mood for all compositions in this project. +2. **User named a style or mood** (e.g., "Swiss Pulse", "dark and techy", "luxury brand")? → Read [visual-styles.md](./visual-styles.md) for matching presets. Generate a `design.md` with: `## Mood` (one paragraph), `## Colors` (bg, fg, accent hex values), `## Typography` (headline + body families and weights), `## What NOT to Do` (3–5 anti-patterns). Save to `design.md`. +3. **None of the above?** → Follow [house-style.md](./house-style.md) defaults. ### Using design.md during construction -If a `design.md` exists, it is the source of truth for all visual decisions. Use only the values it defines — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. +If a `design.md` exists, it is the source of truth for all visual decisions — colors, fonts, spacing, corners, depth, component treatments, and any other fields the user has added. Do not invent new colors, substitute fonts, or override its rules. If the composition needs a value the design.md doesn't cover, follow [house-style.md](./house-style.md) for that specific decision. + +design.md defines appearance. [house-style.md](./house-style.md) defines motion. If design.md includes motion rules, they take precedence for that specific property. ### Step 1: Plan @@ -294,15 +300,20 @@ Use `--no-contrast` to skip if iterating rapidly and you'll check later. If a `design.md` exists, verify the composition follows it after authoring. Read the HTML and check: -1. **Colors** — every hex value in the composition appears in design.md's palette (accent, muted, surface, bg, fg). Flag any invented colors. -2. **Typography** — font families and weights match design.md's headline/body spec. No substitutions. -3. **Corners** — border-radius values match the declared corner style. -4. **Spacing** — padding and gap values fall within the declared density range. -5. **Depth** — shadow usage matches the declared depth level (flat = none, subtle = light, layered = glows). -6. **"What NOT to Do"** — if design.md has a don'ts section, verify none are present. +1. **Colors** — every hex value in the composition appears in design.md's palette section (however the user labeled it: Colors, Palette, Theme, etc.). Flag any invented colors. +2. **Typography** — font families and weights match design.md's type spec. No substitutions. +3. **Corners** — border-radius values match the declared corner style, if specified. +4. **Spacing** — padding and gap values fall within the declared density range, if specified. +5. **Depth** — shadow usage matches the declared depth level, if specified (flat = none, subtle = light, layered = glows). +6. **Avoidance rules** — if design.md has a section listing things to avoid (commonly "What NOT to Do", "Don'ts", "Anti-patterns", or "Do's and Don'ts"), verify none are present. Report violations as a checklist. Fix each one before serving. +If no `design.md` exists (house-style-only path), verify: + +1. **Palette consistency** — the same bg, fg, and accent colors are used across all scenes. No per-scene color invention. +2. **No lazy defaults** — check the composition against house-style.md's "Lazy Defaults to Question" list. If any appear, they must be a deliberate choice for the content, not a default. + ### Animation Map After authoring animations, run the animation map to verify choreography: