Visual Style

Visual Style

Create, extract, and apply portable visual design systems. A visual-style.md file defines colors, typography, layout, motion, and mood in one file that any AI tool can consume.

Quick Reference

Default Workflow

Create

1. Gather vibe — Ask about mood, era, references, inspiration 2. Define colors — Primary (2+), accent, neutrals with hex values and roles 3. Set typography — Display, body, caption families + weight/style rules 4. Layout & motion — Grid system, transitions, pacing 5. Generate — Output complete visual-style.md using references/templates/minimal.visual-style.md or references/templates/full.visual-style.md 6. Preview — Show a small HTML swatch or describe the visual result 7. Optionally apply — Ask if user wants to use it with a connector

Questions to batch: 1. What's the vibe? (mood keywords, era, references) 2. Any specific colors? (or derive from the vibe?) 3. Typography preference? (clean, editorial, technical, playful?) 4. What tool will you use this with? (HeyGen, slides, paper.design, Figma?)

Extract

1. Receive source — URL, image, video, or PDF 2. Load extractor — Read the appropriate extractor reference file 3. Analyze — Identify colors, typography, layout, motion, mood 4. Generate — Output complete visual-style.md with source_url set 5. Validate — Ensure all required fields are present

Apply

1. Read the style — Load the visual-style.md file 2. Ask which connector — Or detect from context 3. Load connector — Read the appropriate connector reference file 4. Transform — Map style fields to tool-specific format 5. Generate output — Produce tool-ready instructions or code

Gallery

1. List styles — Show available styles from references/gallery/ 2. Preview — Describe the selected style's visual character 3. Load — Read the full visual-style.md 4. Apply — Use with a connector

Format Quick Reference

Required fields

name: "Style Name"
version: "1.0"
style_prompt_short: "1-2 sentence elevator pitch"
style_prompt_full: "Detailed generation prompt — THE most important field"
colors:
  primary:
    - name: "Color Name"
      hex: "#000000"
      role: "how this color is used"

`style_prompt_full` is king. If a tool can only read one field, it reads this one. Everything else is structured data for tools that want finer control.

Full spec: references/spec.md

Reference Files

Connectors (Apply mode)

Extractors (Extract mode)

Gallery (pre-built styles)

Templates & Spec

• references/templates/minimal.visual-style.md — Bare minimum template
• references/templates/full.visual-style.md — Complete template with all fields
• references/spec.md — Full format specification

Best Practices

1. `style_prompt_full` is king — Always usable as a standalone generation prompt 2. One style, one file — No multi-style bundling 3. Assets are URLs — Never embed binary data 4. Show, don't tell — Generate previews when creating styles 5. Opinionated defaults, flexible extensions — Core schema is fixed; x_* for tool-specific config

Figma Connector

Apply a visual-style.md to generate Figma styles and components.

Overview

This connector maps visual-style.md fields to Figma's style system: color styles, text styles, effect styles, and layout grids.

Field Mapping

Color Styles

Generate Figma color styles from the colors object:

Folder: brand/
  - brand/black         → colors.primary[0].hex
  - brand/white         → colors.primary[1].hex

Folder: accent/
  - accent/primary      → colors.accent[0].hex
  - accent/secondary    → colors.accent[1].hex (if exists)

Folder: neutral/
  - neutral/light       → colors.neutral[0].hex
  - neutral/dark        → colors.neutral[1].hex

Naming convention: Use the role field for style descriptions.

Text Styles

Generate Figma text styles from typography:

Folder: heading/
  - heading/display
    Font: typography.display.family
    Weight: typography.display.weight
    Size: 48px (or derive from style)

Folder: body/
  - body/default
    Font: typography.body.family
    Weight: typography.body.weight
    Size: 16px

Folder: label/
  - label/default
    Font: typography.caption.family
    Weight: typography.caption.weight
    Size: 12px

Layout Grids

Generate layout grid presets from layout.grid:

"12 columns" →
  Columns: 12
  Type: Stretch
  Margin: 64px
  Gutter: 24px

"8-point grid" →
  Rows: Count
  Height: 8px

"Strict modular grid" →
  Both columns AND rows enabled

Style Guide Frame

Create a style guide frame that documents the system:

┌─────────────────────────────────────────────────────┐
│  [name]                                             │
│  [style_prompt_short]                               │
├─────────────────────────────────────────────────────┤
│  COLORS                                             │
│  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐                │
│  │████│ │████│ │████│ │████│ │████│                │
│  └────┘ └────┘ └────┘ └────┘ └────┘                │
│  Primary  Secondary  Accent   Neutral              │
├─────────────────────────────────────────────────────┤
│  TYPOGRAPHY                                         │
│                                                     │
│  Display Heading                                    │
│  [typography.display.family] [weight]               │
│                                                     │
│  Body text paragraph                                │
│  [typography.body.family] [weight]                  │
│                                                     │
│  CAPTION / LABEL                                    │
│  [typography.caption.family] [weight]               │
├─────────────────────────────────────────────────────┤
│  RULES                                              │
│  ✓ [typography.rules[0]]                           │
│  ✓ [typography.rules[1]]                           │
│                                                     │
│  AVOID                                              │
│  ✗ [mood.avoid[0]]                                 │
│  ✗ [mood.avoid[1]]                                 │
└─────────────────────────────────────────────────────┘

Workflow

1. Read the style — Load the visual-style.md file 2. Create color styles — One style per color in the palette 3. Create text styles — Display, body, and caption styles 4. Set up layout grid — Create grid presets 5. Build style guide frame — Document the system 6. Add reference images — Import assets.reference_images if available

Figma Plugin Integration

If building a Figma plugin that reads visual-style.md:

interface VisualStyle {
  name: string;
  version: string;
  style_prompt_short: string;
  style_prompt_full: string;
  colors: {
    primary: Color[];
    accent?: Color[];
    neutral?: Color[];
  };
  typography: {
    display: TypographyStyle;
    body: TypographyStyle;
    caption: TypographyStyle;
    rules?: string[];
  };
  // ... other fields
}

interface Color {
  name: string;
  hex: string;
  role: string;
}

interface TypographyStyle {
  family: string;
  weight: string;
  style?: string;
}

Tips

• Font availability — Check that typography.*.family fonts are available in Figma (Google Fonts or locally installed)
• Color organization — Use folders to group color styles by purpose
• Style descriptions — Use the role field as the style description
• Design review — Create a checklist from typography.rules and mood.avoid

HeyGen Video Agent Connector

Apply a visual-style.md to HeyGen Video Agent for AI-generated videos.

Overview

HeyGen Video Agent accepts a text prompt that can include visual style instructions. The style_prompt_full field maps directly to this.

Field Mapping

Prompt Template

Create a video about [TOPIC].

Script:
[USER'S SCRIPT]

Visual style:
[PASTE style_prompt_full HERE]

Additional constraints:
- [ITEMS FROM mood.avoid]

Motion:
- Transitions: [motion.transitions]
- Pacing: [motion.pacing]
- Animation: [motion.animation_style]

Format: [layout.aspect_ratio OR x_heygen.orientation]

Example: No-Avatar Motion Graphics

For pure motion graphics without an avatar:

Create a video about our Q4 results.

Script:
Revenue grew 40% year over year. We shipped 12 new features.
Customer satisfaction hit an all-time high of 94%.

Visual style:
Josef Müller-Brockmann Swiss International Style. Grid-locked layouts
with mathematical precision. Black and white base with ONE accent color
(electric blue #0066FF). Strong diagonal compositions. Helvetica
typography only. Data visualizations are the hero — animated charts,
counters, grids. Every frame snaps to a grid. Transitions are horizontal
grid wipes. No organic shapes. No gradients. No stock photography.
Everything is geometric, systematic, precise.

Additional constraints:
- No avatar
- No b-roll footage
- No stock photography
- Pure motion graphics only

Motion:
- Transitions: horizontal grid wipes, clean hard cuts
- Pacing: Measured, confident, unhurried
- Animation: Elements snap to grid positions, charts animate systematically

Format: landscape (16:9)

Workflow

1. Load the style — Read the visual-style.md file 2. Extract key fields:

• style_prompt_full (required)
• motion.* fields (recommended)
• mood.avoid (recommended)
• layout.aspect_ratio or x_heygen.orientation

3. Build the prompt — Use the template above 4. Call HeyGen Video Agent — Use the HeyGen MCP tool or API 5. Store reference — Save the video ID to x_heygen.video_id if desired

Tips

• Be explicit about what you don't want — HeyGen responds well to negative constraints
• Motion graphics mode — Add "No avatar. No b-roll. Pure motion graphics." for abstract styles
• Data visualization — Mention "animated charts, counters, data viz" for number-heavy content
• Transitions matter — Specify transition style explicitly; defaults may not match your style

Supported Styles

These gallery styles work especially well with HeyGen Video Agent:

• mueller-brockmann-swiss.visual-style.md — Data-driven, grid-locked
• neville-brody-industrial.visual-style.md — Bold typography, industrial
• saul-bass-cinematic.visual-style.md — Cinematic titles, bold shapes
• game-boy-color.visual-style.md — Pixel art, retro gaming
• heygen-ai-video.visual-style.md — Modern AI/SaaS aesthetic

HTML Slides Connector (frontend-slides)

Apply a visual-style.md to HTML slide presentations.

Overview

This connector maps visual-style.md fields to CSS variables and styling rules for use with frontend-slides or similar HTML presentation frameworks.

Field Mapping

CSS Variables Template

:root {
  /* Colors */
  --color-bg: [colors.primary[0].hex];
  --color-text: [colors.primary[1].hex];
  --color-accent: [colors.accent[0].hex];
  --color-muted: [colors.neutral[0].hex];

  /* Typography */
  --font-display: "[typography.display.family]", system-ui, sans-serif;
  --font-body: "[typography.body.family]", system-ui, sans-serif;

  /* Spacing (derive from style) */
  --space-sm: clamp(0.5rem, 1vw, 1rem);
  --space-md: clamp(1rem, 2vw, 2rem);
  --space-lg: clamp(2rem, 4vw, 4rem);
}

body {
  font-family: var(--font-body);
  background: var(--color-bg);
  color: var(--color-text);
}

h1, h2, h3 {
  font-family: var(--font-display);
  font-weight: [typography.display.weight];
  /* Apply typography.display.style rules */
}

.accent {
  color: var(--color-accent);
}

.muted {
  color: var(--color-muted);
}

frontend-slides Constraints

When generating HTML slides, follow these rules:

1. Single HTML file — Zero dependencies, inline CSS/JS 2. Viewport units — All sizes use clamp(), never fixed px/rem 3. No scrolling — height: 100vh; overflow: hidden; per slide 4. Content overflow — If content doesn't fit, split into multiple slides 5. Google Fonts — Load via <link> tag in <head>

Example: Swiss Style Slides

Given mueller-brockmann-swiss.visual-style.md:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Presentation</title>
  <link href="https://fonts.googleapis.com/css2?family=Helvetica+Neue:wght@300;400;700&display=swap" rel="stylesheet">
  <style>
    :root {
      --color-bg: #000000;
      --color-text: #FFFFFF;
      --color-accent: #0066FF;
      --color-muted: #CCCCCC;
      --font-display: "Helvetica Neue", Helvetica, Arial, sans-serif;
      --font-body: "Helvetica Neue", Helvetica, Arial, sans-serif;
    }

    * { box-sizing: border-box; margin: 0; padding: 0; }

    body {
      font-family: var(--font-body);
      background: var(--color-bg);
      color: var(--color-text);
    }

    .slide {
      height: 100vh;
      overflow: hidden;
      display: flex;
      flex-direction: column;
      justify-content: center;
      padding: clamp(2rem, 5vw, 6rem);
    }

    h1 {
      font-family: var(--font-display);
      font-weight: 700;
      font-size: clamp(3rem, 8vw, 8rem);
      text-transform: uppercase;
      letter-spacing: -0.02em;
      line-height: 0.9;
      text-align: left;
    }

    .accent { color: var(--color-accent); }

    /* Grid overlay for Swiss style */
    .slide::before {
      content: '';
      position: absolute;
      inset: 0;
      background: repeating-linear-gradient(
        90deg,
        transparent,
        transparent calc(100% / 12 - 1px),
        var(--color-muted) calc(100% / 12 - 1px),
        var(--color-muted) calc(100% / 12)
      );
      opacity: 0.1;
      pointer-events: none;
    }
  </style>
</head>
<body>
  <section class="slide">
    <h1>Grid-locked<br><span class="accent">precision</span></h1>
  </section>
</body>
</html>

Workflow

1. Load the style — Read the visual-style.md file 2. Generate CSS variables — Map colors and typography 3. Apply typography rules — Follow typography.rules constraints 4. Check constraints — Verify against mood.avoid list 5. Generate slides — One <section class="slide"> per slide 6. Validate — Ensure no scrolling, all sizes responsive

Tips

• Typography drives hierarchy — Use typography.display for headlines, typography.body for content
• Honor the avoid list — Check mood.avoid before adding decorative elements
• Transitions — Map motion.transitions to CSS transitions between slides
• Font loading — Always include fallback fonts in the stack

paper.design Connector

Apply a visual-style.md to paper.design documents.

Overview

paper.design is a professional design tool for creating user interfaces. This connector maps visual-style.md fields to paper.design document defaults and AI layout guidance.

Field Mapping

Applying the Style

1. Set up the color palette

When creating new artboards, apply the colors from the style:

Background: colors.primary[0].hex
Text: colors.primary[1].hex
Accent elements: colors.accent[0].hex
Secondary elements: colors.neutral[0].hex

2. Configure typography

Load the specified fonts and set defaults:

Display/Headlines: typography.display.family, typography.display.weight
Body text: typography.body.family, typography.body.weight
Labels/Captions: typography.caption.family, typography.caption.weight

3. Apply layout rules

Follow layout.grid for artboard structure:

• "12 columns" → Set up 12-column grid
• "Strict modular grid" → Enable grid snapping
• "Flush left" → Left-align all text blocks

4. Use style_prompt_full for AI guidance

When using AI features in paper.design, include the style_prompt_full in your prompt:

Create a landing page hero section.

Visual style:
[PASTE style_prompt_full HERE]

Constraints:
[ITEMS FROM mood.avoid]

Example: Applying Swiss Style

Given mueller-brockmann-swiss.visual-style.md:

Color setup:

• Background: #000000 (Pure Black)
• Text: #FFFFFF (Pure White)
• Accent: #0066FF (Electric Blue)
• Grid lines: #CCCCCC (Grid Gray)

Typography:

• All text: Helvetica family
• Headlines: Helvetica Bold, uppercase
• Body: Helvetica Regular, flush left
• Captions: Helvetica Light, small, uppercase

Layout:

• 12-column modular grid
• All elements snap to grid
• No centered text
• Strong diagonal compositions within orthogonal structure

Design constraints (from mood.avoid):

• No organic or curved shapes
• No gradients
• No stock photography
• No rounded corners
• No decorative elements

Workflow

1. Read the style — Load the visual-style.md file 2. Create artboard — Set dimensions from layout.aspect_ratio 3. Apply background — Use colors.primary[0].hex 4. Set up grid — Follow layout.grid specification 5. Configure fonts — Load typography.* families 6. Build content — Follow mood.keywords for direction 7. Review — Check against mood.avoid constraints

Design Brief Format

When starting a new design in paper.design, generate a brief from the style:

## Design Brief

**Style:** [name]

**Color Palette:**
- [colors.primary[0].name]: [hex] — [role]
- [colors.primary[1].name]: [hex] — [role]
- [colors.accent[0].name]: [hex] — [role]

**Typography:**
- Display: [typography.display.family] [weight]
- Body: [typography.body.family] [weight]

**Layout:** [layout.grid], [layout.alignment]

**Mood:** [mood.keywords joined]

**Avoid:** [mood.avoid joined]

Tips

• Start with the grid — Set up layout.grid before placing elements
• Typography first — Let typography.rules guide hierarchy decisions
• Check constraints regularly — Reference mood.avoid while designing
• Use reference images — If assets.reference_images has URLs, import them as a style board

Extract from PDF / Brand Guide

Generate a visual-style.md from a PDF brand guide or style document.

Workflow

1. Receive PDF — User uploads a brand guide, style guide, or design document 2. Parse sections — Identify color, typography, layout, and guidelines sections 3. Map to fields — Translate brand guide specifications to visual-style.md fields 4. Fill gaps — Generate style_prompt_full from the structured data 5. Output — Complete visual-style.md 6. Validate — Ensure all required fields are present

Common Brand Guide Sections

Extraction Prompt

Use this prompt when parsing a brand guide PDF:

Parse this brand guide PDF and generate a visual-style.md.

Map the brand guide sections to visual-style.md fields:

REQUIRED:
- name: Brand name + "Brand Style"
- version: "1.0"
- style_prompt_short: Synthesize from brand overview/mission
- style_prompt_full: Combine ALL visual specifications into a coherent
  generation prompt. Include specific hex codes, font names, spacing
  values, and design principles.
- colors.primary: From "Primary Colors" section

FROM COLOR SECTIONS:
- colors.primary: Primary palette (convert all color specs to hex)
- colors.accent: Secondary/accent colors
- colors.neutral: Grays, backgrounds, supporting colors

FROM TYPOGRAPHY SECTIONS:
- typography.display: Headline font specs
- typography.body: Body copy font specs
- typography.caption: Caption/label specs (if defined)
- typography.rules: Any typography guidelines or restrictions

FROM LAYOUT SECTIONS:
- layout.grid: Grid system specifications
- layout.alignment: Alignment rules
- layout.notes: Spacing, margins, padding guidelines

FROM GUIDELINES SECTIONS:
- mood.keywords: Extract from voice/tone/personality sections
- mood.avoid: Extract from "Don't" lists, incorrect usage examples

Be precise:
- Convert all color specifications to hex (RGB, CMYK, Pantone → hex)
- Use exact font family names as specified
- Include specific measurements where given
- Preserve the brand's stated values in style_prompt_full

Output format:
Complete YAML frontmatter between --- delimiters
Plus Markdown body sections (## Design Principles from brand philosophy)

Color Conversion Reference

Brand guides often specify colors in multiple formats:

For Pantone colors, use the official Pantone-to-hex mapping or note the Pantone code in the role field.

Example Output

Given a corporate brand guide PDF:

---
name: "Acme Corp Brand Style"
version: "1.0"
tags:
  - corporate
  - technology
author: "Extracted from Acme Brand Guidelines v2.3"
source_url: ""
created: "2026-03-12"

style_prompt_short: >
  Professional tech brand with bold blue accents.
  Clean, trustworthy, forward-thinking.

style_prompt_full: >
  Acme Corp brand style. Professional technology company aesthetic.
  Primary blue (#0052CC) for brand elements, CTAs, and emphasis.
  Navy (#172B4D) for headings and high-contrast text. Clean white
  (#FFFFFF) backgrounds with generous whitespace. Neutral grays
  for supporting content. Typography uses Roboto for digital
  and Avenir for print — clean, geometric sans-serifs that convey
  precision. 8-point spacing grid. Rounded corners (4px) on
  interactive elements. Photography should be authentic, diverse,
  and optimistic — no stock photo clichés. Iconography is outlined,
  2px stroke, rounded caps. Professional but approachable. Never
  corporate-stuffy or overly playful.

colors:
  primary:
    - name: "Acme Blue"
      hex: "#0052CC"
      role: "primary brand color, CTAs, links"
    - name: "Navy"
      hex: "#172B4D"
      role: "headings, high-contrast text"
  accent:
    - name: "Success Green"
      hex: "#36B37E"
      role: "positive states, confirmations"
    - name: "Warning Yellow"
      hex: "#FFAB00"
      role: "warnings, attention"
    - name: "Error Red"
      hex: "#DE350B"
      role: "errors, destructive actions"
  neutral:
    - name: "White"
      hex: "#FFFFFF"
      role: "primary background"
    - name: "Light Gray"
      hex: "#F4F5F7"
      role: "secondary backgrounds, cards"
    - name: "Mid Gray"
      hex: "#6B778C"
      role: "secondary text, placeholders"
    - name: "Dark Gray"
      hex: "#42526E"
      role: "body text"

typography:
  display:
    family: "Roboto"
    weight: "700"
    style: "sentence case, -0.02em tracking"
  body:
    family: "Roboto"
    weight: "400"
    style: "16px base, 1.5 line height"
  caption:
    family: "Roboto"
    weight: "500"
    style: "12px, uppercase for labels"
  rules:
    - "Roboto for all digital applications"
    - "Avenir for print materials"
    - "Minimum body text size: 14px"
    - "Maximum line length: 75 characters"
    - "Use Medium (500) weight for emphasis, not bold"

layout:
  grid: "8-point grid, 12 columns"
  alignment: "Left-aligned text, center-aligned hero content"
  aspect_ratio: "16:9 for presentations"
  notes:
    - "Minimum margin: 24px (mobile), 48px (desktop)"
    - "Standard spacing: 8, 16, 24, 32, 48, 64px"
    - "Card border-radius: 4px"
    - "Button border-radius: 4px"

motion:
  transitions:
    - "ease-out, 200ms for micro-interactions"
    - "ease-in-out, 300ms for page transitions"
  animation_style: "Subtle, purposeful. Animation should clarify, not decorate."
  pacing: "Quick, responsive feedback"

mood:
  keywords:
    - "professional"
    - "trustworthy"
    - "innovative"
    - "approachable"
    - "precise"
  era: "Contemporary tech (2020s)"
  cultural_reference: "Enterprise SaaS, developer tools"
  avoid:
    - "overly playful or casual tone"
    - "generic stock photography"
    - "gradients on brand elements"
    - "more than 3 colors in one composition"
    - "centered body text"
    - "all-caps body text"
    - "drop shadows deeper than 2px"

assets:
  reference_images: []
  color_palette_image:
    url: ""
---

## Design Principles

From Acme Brand Guidelines:

1. **Clarity over cleverness** — Communication should be immediately understood
2. **Consistency builds trust** — Every touchpoint reinforces the brand
3. **Purposeful restraint** — Add only what adds value
4. **Accessible by default** — Design for everyone

## Extraction Notes

Extracted from "Acme Brand Guidelines v2.3" (PDF, 48 pages).
Color values converted from Pantone specifications.
Typography mapped from "Digital Standards" section.
Do's and Don'ts synthesized into mood.avoid list.

Tips

• Prioritize specificity — Brand guides are precise; preserve exact values
• Don't invent — If a section isn't in the PDF, leave the field empty
• Synthesize style_prompt_full — This should read like a brief you'd give a designer
• Capture the don'ts — mood.avoid is often explicitly stated in brand guides
• Note the source — Include page numbers or section names in Extraction Notes

Extract from Video

Generate a visual-style.md from video keyframes.

Workflow

1. Receive video — User provides a video URL or file 2. Sample keyframes — Capture 4-6 screenshots at different points 3. Analyze frames — Identify consistent visual patterns across all frames 4. Focus on motion — Pay special attention to transitions and animation 5. Generate — Output complete visual-style.md 6. Validate — Ensure all required fields are present

Keyframe Sampling Strategy

Sample frames at these intervals:

• 0:00-0:02 — Opening/title frame
• 0:05-0:10 — Early content frame
• 0:15-0:20 — Middle content frame
• Near end — Closing frame
• Transitions — Capture mid-transition if possible

Look for consistency across frames — the style is what stays the same.

Extraction Prompt

Use this prompt template when analyzing video frames:

Analyze these video keyframes and extract a visual-style.md.

These are [N] frames from a single video. Identify the CONSISTENT visual
system across all frames, not the unique content of each frame.

Identify and output:

REQUIRED:
- name: A descriptive name for this style
- version: "1.0"
- style_prompt_short: 1-2 sentence hook
- style_prompt_full: Detailed generation prompt covering:
  - Color palette (consistent colors across frames)
  - Typography style (font appearance, text treatment)
  - Motion patterns (transitions, animation style)
  - Layout approach (composition, spacing)
  - Overall mood
- colors.primary: At least 2 consistent colors

CRITICAL FOR VIDEO:
- motion.transitions: How do scenes change?
- motion.animation_style: How do elements move?
- motion.pacing: Fast cuts vs. slow fades?
- mood.keywords: What feeling does the motion create?

Be specific about MOTION patterns:
- Do elements snap or ease?
- Are transitions hard cuts or smooth fades?
- Do things bounce, slide, or appear suddenly?
- What's the rhythm? Quick and energetic, or slow and measured?

Output format:
Complete YAML frontmatter between --- delimiters
Plus Markdown body sections

Analysis Checklist

When extracting from video, look for:

Colors

• [ ] Background colors (do they change between scenes?)
• [ ] Primary text/graphic colors
• [ ] Accent colors for emphasis
• [ ] Color transitions (do colors shift?)

Typography

• [ ] Title treatment (size, weight, animation)
• [ ] Body text style (if present)
• [ ] Caption/subtitle style
• [ ] Text animation (fade, slide, type-on)

Motion (Critical)

• [ ] Scene transitions (cut, wipe, dissolve, morph)
• [ ] Element entrances (fade, slide, pop, scale)
• [ ] Element exits (how do things leave?)
• [ ] Easing style (linear, ease-out, bounce, snap)
• [ ] Timing/rhythm (quick cuts, slow reveals)
• [ ] Looping patterns (if any)

Layout

• [ ] Composition style (centered, asymmetric, grid-locked)
• [ ] Framing (full-bleed, contained, letterboxed)
• [ ] Text placement (bottom third, centered, dynamic)
• [ ] Aspect ratio (16:9, 9:16, 1:1)

Mood

• [ ] Energy level (calm, energetic, intense)
• [ ] Tone (serious, playful, dramatic)
• [ ] Era/genre references
• [ ] Sound-visual relationship (if audio present)

Example Output

Given frames from a retro arcade-style video:

---
name: "Pac-Man Arcade Style"
version: "1.0"
tags:
  - pixel retro
  - gaming
author: "Extracted"
source_url: ""
created: "2026-03-12"

style_prompt_short: >
  8-bit arcade nostalgia. Pixel graphics, neon on black,
  classic Pac-Man yellow with ghost accents.

style_prompt_full: >
  Retro 8-bit arcade aesthetic inspired by Pac-Man. Pure black
  backgrounds with neon pixel graphics. Classic Pac-Man yellow
  (#FFFF00) as the hero color. Ghost colors for accents: Blinky
  red (#FF0000), Pinky pink (#FFB8FF), Inky cyan (#00FFFF),
  Clyde orange (#FFB852). Chunky pixel fonts. Elements move in
  discrete pixel steps, not smooth curves. Maze-like compositions.
  Screen flicker and CRT scanline effects. 8-bit sound design
  aesthetic applied visually. Hard cuts between scenes. No
  gradients, no anti-aliasing, no rounded corners.

colors:
  primary:
    - name: "Arcade Black"
      hex: "#000000"
      role: "background, the void"
    - name: "Pac-Man Yellow"
      hex: "#FFFF00"
      role: "hero element, primary accent"
  accent:
    - name: "Blinky Red"
      hex: "#FF0000"
      role: "danger, emphasis"
    - name: "Inky Cyan"
      hex: "#00FFFF"
      role: "secondary accent"
    - name: "Pinky Pink"
      hex: "#FFB8FF"
      role: "tertiary accent"
    - name: "Clyde Orange"
      hex: "#FFB852"
      role: "warm accent"
  neutral:
    - name: "Maze Blue"
      hex: "#2121DE"
      role: "structure, maze walls"

typography:
  display:
    family: "Press Start 2P, monospace"
    weight: "400"
    style: "uppercase, pixel-perfect"
  body:
    family: "VT323, monospace"
    weight: "400"
    style: "8-bit rendering"
  caption:
    family: "Press Start 2P, monospace"
    weight: "400"
    style: "small, all caps"
  rules:
    - "All text must appear pixel-perfect"
    - "No anti-aliasing on fonts"
    - "Text animates character by character"

layout:
  grid: "Pixel grid, 8px base unit"
  alignment: "Centered compositions"
  aspect_ratio: "4:3 or 16:9"
  notes:
    - "Maze-like structures as compositional elements"
    - "Frame content like an arcade cabinet"
    - "Leave scanline space at edges"

motion:
  transitions:
    - "hard cuts (no dissolves)"
    - "screen wipe from Pac-Man eating across"
    - "pixel dissolve / scatter"
  animation_style: >
    Discrete pixel movement — elements jump from position to position,
    never smooth tweening. Characters animate at 12fps max. Screen
    flicker for emphasis. Chomping animation on any moving element.
  pacing: "Energetic, game-loop rhythm"
  audio_cues:
    - "wakka-wakka sound on transitions"
    - "8-bit beeps and boops"

mood:
  keywords:
    - "nostalgic"
    - "playful"
    - "arcade"
    - "8-bit"
    - "energetic"
  era: "1980s arcade golden age"
  cultural_reference: "Pac-Man, Space Invaders, Galaga, arcade cabinets"
  avoid:
    - "smooth gradients"
    - "anti-aliased edges"
    - "photorealistic elements"
    - "modern UI patterns"
    - "slow, smooth animations"
    - "muted or desaturated colors"

assets:
  reference_images: []
  color_palette_image:
    url: ""
---

## Design Principles

Everything is a pixel. Movement is discrete, never continuous.
Colors are pure and saturated. The arcade cabinet is the frame.

## Extraction Notes

Extracted from video keyframes.
Color palette based on original Pac-Man game (1980).
Motion patterns reflect 8-bit hardware limitations as aesthetic choice.

Tips

• Focus on what's consistent — Ignore unique content, find the system
• Motion is primary — Video styles are defined by how things move
• Describe the rhythm — Is it quick cuts or slow fades?
• Note the easing — Does it snap, bounce, or glide?
• Reference the era — Many video styles reference specific decades or genres

Extract from Website

Generate a visual-style.md from a website URL.

Workflow

1. Receive URL — User provides a website URL 2. Fetch the page — Use web fetch to get the HTML/CSS 3. Take screenshots — Capture the page visually if possible 4. Analyze — Identify colors, typography, layout, motion, mood 5. Generate — Output complete visual-style.md 6. Validate — Ensure all required fields are present

Extraction Prompt

Use this prompt template when analyzing a website:

Analyze this website and extract a visual-style.md following the spec.

URL: [URL]

Identify and output these fields:

REQUIRED:
- name: A descriptive name for this style (e.g., "[Brand] Web Style")
- version: "1.0"
- style_prompt_short: 1-2 sentence hook capturing the visual essence
- style_prompt_full: Detailed generation prompt with specific:
  - Hex color codes (use exact values, don't guess)
  - Font family names (check the CSS)
  - Layout structure (grid system, spacing patterns)
  - Motion patterns (animations, transitions)
  - Overall mood and feel
- colors.primary: At least 2 colors with name, hex, role

RECOMMENDED:
- colors.accent: Accent colors with name, hex, role
- colors.neutral: Neutral/gray colors with name, hex, role
- typography.display: Heading font family, weight, style
- typography.body: Body font family, weight, style
- typography.caption: Caption/label font family, weight, style
- typography.rules: Typography constraints and patterns
- layout.grid: Grid system description
- layout.alignment: Alignment patterns
- layout.notes: Additional layout observations
- motion.transitions: Transition types used
- motion.animation_style: Overall animation approach
- mood.keywords: 4-6 mood/feeling words
- mood.era: Design era reference
- mood.avoid: Anti-patterns to avoid

Be specific:
- Use exact hex values from the CSS, not approximations
- Name every color descriptively (not "Blue 1", but "Ocean Blue")
- Describe the role of each color in the system
- Note any custom fonts and their fallbacks

Output format:
Complete YAML frontmatter between --- delimiters
Plus Markdown body sections (## Design Principles, ## Extraction Notes)

Analysis Checklist

When extracting, look for:

Colors

• [ ] Background colors (primary surfaces)
• [ ] Text colors (headings vs body)
• [ ] Accent/CTA button colors
• [ ] Link colors (default, hover, visited)
• [ ] Border/divider colors
• [ ] Gradient usage (if any)

Typography

• [ ] Heading font family
• [ ] Body font family
• [ ] Font weights used (light, regular, bold, etc.)
• [ ] Text sizes (heading scale)
• [ ] Line heights
• [ ] Letter spacing patterns
• [ ] Text transform (uppercase, lowercase)

Layout

• [ ] Max content width
• [ ] Grid columns (if visible)
• [ ] Spacing rhythm (consistent gaps)
• [ ] Alignment patterns (left, center, mixed)
• [ ] Card/component patterns
• [ ] Negative space usage

Motion

• [ ] Page transitions
• [ ] Hover effects
• [ ] Scroll animations
• [ ] Loading states
• [ ] Micro-interactions

Mood

• [ ] Overall feeling (professional, playful, minimal, bold)
• [ ] Design era (modern, retro, timeless)
• [ ] Brand personality (serious, friendly, technical)
• [ ] What they explicitly avoid

Example Output

Given URL https://stripe.com:

---
name: "Stripe Web Style"
version: "1.0"
tags:
  - fintech
  - sleek minimal
author: "Extracted"
source_url: "https://stripe.com"
created: "2026-03-12"

style_prompt_short: >
  Clean fintech minimalism with deep purple accents on white.
  Generous whitespace, clear typography, subtle gradients.

style_prompt_full: >
  Modern fintech design inspired by Stripe. Clean white backgrounds
  with generous whitespace. Deep purple (#635BFF) as the primary
  accent color. Typography uses a custom geometric sans-serif
  (similar to Inter or Söhne) with clear hierarchy. Subtle mesh
  gradients in backgrounds. Rounded corners on cards and buttons.
  Smooth, subtle animations on scroll. Professional, trustworthy,
  approachable. No harsh colors, no busy patterns, no stock photos.

colors:
  primary:
    - name: "Pure White"
      hex: "#FFFFFF"
      role: "primary background, negative space"
    - name: "Slate Dark"
      hex: "#0A2540"
      role: "primary text, headings"
  accent:
    - name: "Stripe Purple"
      hex: "#635BFF"
      role: "CTAs, links, brand accent"
    - name: "Cyan Accent"
      hex: "#00D4FF"
      role: "secondary accent, gradients"
  neutral:
    - name: "Slate Gray"
      hex: "#425466"
      role: "body text, secondary content"
    - name: "Light Gray"
      hex: "#F6F9FC"
      role: "section backgrounds, cards"

typography:
  display:
    family: "Söhne, Inter, system-ui"
    weight: "600"
    style: "sentence case, tight tracking"
  body:
    family: "Söhne, Inter, system-ui"
    weight: "400"
    style: "generous line height, comfortable reading"
  caption:
    family: "Söhne Mono, monospace"
    weight: "400"
    style: "code blocks, technical details"
  rules:
    - "Clear size hierarchy: 64px → 48px → 32px → 24px → 16px"
    - "Generous line heights for readability"
    - "Monospace for code and technical content"

layout:
  grid: "12 columns, max-width 1200px"
  alignment: "Center-aligned sections, left-aligned text"
  aspect_ratio: "16:9 for hero, varied for content"
  notes:
    - "Generous vertical spacing between sections"
    - "Cards with subtle shadows and rounded corners"
    - "Alternating section backgrounds"

motion:
  transitions:
    - "subtle fade-in on scroll"
    - "smooth hover state transitions (0.2s)"
    - "parallax on hero backgrounds"
  animation_style: "Subtle, smooth, professional. Nothing bouncy or playful."
  pacing: "Measured, confident transitions"

mood:
  keywords:
    - "professional"
    - "trustworthy"
    - "clean"
    - "modern"
    - "approachable"
  era: "2020s fintech"
  cultural_reference: "Modern SaaS, developer-focused design"
  avoid:
    - "harsh or neon colors"
    - "busy patterns or textures"
    - "stock photography"
    - "overly playful animations"
    - "dark mode (unless requested)"

assets:
  reference_images: []
  color_palette_image:
    url: ""
---

## Design Principles

Trust through clarity. Every element earns its place. Typography and whitespace
do the heavy lifting. Color is used sparingly and intentionally.

## Extraction Notes

Extracted from https://stripe.com on 2026-03-12.
Primary purple sampled from CTA buttons.
Typography stack identified via browser dev tools.
Mesh gradient patterns noted in hero sections.

Tips

• Use dev tools — Inspect element to get exact hex values and font stacks
• Check CSS variables — Many sites define their palette in :root
• Note responsive patterns — How does the design adapt?
• Capture the feel — The style_prompt_full should evoke the same feeling
• Be specific about avoids — What does this brand clearly NOT do?

Design Principles

Constraints breed creativity. Every pixel counts when you only have 160x144. Color is precious — use it intentionally. Charm comes from character, not complexity.

Connectors

HeyGen Video Agent

Use style_prompt_full verbatim. Emphasize: chunky pixels, limited colors, low frame rate animations. Screen wipe transitions. Chiptune audio aesthetic. No smooth movements — everything is discrete pixel steps.

HTML Slides

Use pixel fonts (Press Start 2P, VT323). Scale graphics at integer multiples only (2x, 3x, 4x) to maintain pixel crispness. GBC green palette as default, shell colors for accents. Dialogue box borders.

paper.design

Design at low resolution, scale up. Use GBC color palette. Dithering patterns for shading. Sprite-based compositions. 8-pixel grid for all elements.

Figma

Color styles: gbc/dark-green, gbc/mid-green, gbc/pale-green, gbc/light-green, plus shell color variants. 8x8 pixel grid. Use pixel fonts or design custom pixel type. No anti-aliasing on exports.

Design Principles

AI should feel accessible, not intimidating. White space communicates premium quality. The cyan-pink gradient is the hero — use it sparingly but boldly. Every interaction should feel smooth and responsive.

Extraction Notes

Extracted from https://heygen.com on 2026-03-12. Primary colors sampled from CSS variables and brand guidelines. Typography identified via computed styles (ABC Solar, TT Norms Pro). Gradient extracted from hero sections and brand elements. Spacing system follows 4px base unit pattern.

Connectors

HeyGen Video Agent

Use the signature gradient as background or overlay element. Hey Blue for text emphasis and CTAs. Clean white backgrounds. Modern, confident pacing. Approachable AI energy.

HTML Slides

White backgrounds with gradient accent strips or hero elements. Large rounded corners on cards. Generous whitespace. Hey Blue for interactive elements, Prism Pink for highlights.

paper.design

Clean layouts with the gradient as a bold accent element. Large typography with clear hierarchy. Rounded card patterns. Avoid heavy shadows — use subtle borders instead.

Figma

Color styles: brand/hey-blue, brand/prism-pink, brand/gradient. Text styles following the 80-60-44-32-24-18-14px scale. Component variants with large border-radius (12-48px).

Design Principles

Typography and the grid are the only design elements needed. Mathematical relationships create visual harmony. Restraint is the ultimate sophistication. The grid is not a limitation — it is liberation through structure.

Connectors

HeyGen Video Agent

Use style_prompt_full verbatim. Specify: No avatar, no b-roll — pure motion graphics. Hard cuts between scenes. Data visualizations should animate systematically.

HTML Slides

CSS variables: --color-bg: #000, --color-text: #FFF, --color-accent: #0066FF. All text flush left. 12-column grid. Helvetica or system sans-serif fallback.

paper.design

Set up 12-column grid. Background black, text white. Single accent color. Every element should snap to grid intersections.

Figma

Color styles: brand/black, brand/white, accent/electric-blue, neutral/grid-gray. Text styles: heading/display (Helvetica Bold), body/default (Helvetica Regular). Layout grid: 12 columns, strict alignment.

Design Principles

Typography is not decoration — it is the architecture. Tension creates attention. Break the grid with intention. Every collision is choreographed.

Connectors

HeyGen Video Agent

Use style_prompt_full verbatim. Emphasize: harsh cuts, static textures, type that slams into frame. No smooth transitions. Broadcast control room aesthetic.

HTML Slides

Dark backgrounds (#1A1A1A). Condensed type that bleeds off edges. Asymmetric layouts. Red accents for emphasis. Dense information display.

paper.design

Break the grid deliberately. Let type collide with edges. Use image fragments, not full photos. Control room overlay aesthetic.

Figma

Color styles: brand/charcoal, brand/dirty-white, accent/signal-red, accent/electric-blue. Text styles: Condensed black weights for display. Allow type to extend beyond frames.

Design Principles

The title sequence is cinema itself, not a preamble. Every frame could be a poster. Silhouette reveals character without showing it. Geometry creates emotion.

Connectors

HeyGen Video Agent

Use style_prompt_full verbatim. Emphasize: silhouettes, bold shapes, dramatic reveals. Paper cut-out aesthetic. Jazz-influenced timing. No avatars — pure graphic cinema.

HTML Slides

Black backgrounds with stark white and single accent. Full-bleed silhouettes. Dramatic type that integrates with imagery. Strong diagonal compositions.

paper.design

Bold shapes over photorealism. Silhouettes as primary elements. Type and image as unified composition. Torn paper edge effects.

Figma

Color styles: brand/deep-black, brand/stark-white, accent/bass-orange. Create silhouette shapes as reusable components. Custom type treatments over standard text styles.

visual-style.md Format Specification

Version: 1.0 Status: Draft

Overview

A visual-style.md file is a Markdown document with YAML frontmatter that defines a complete visual design system. The format is designed to be:

• Human-readable — Understandable in any text editor
• AI-consumable — Every field directly usable by AI models
• Portable — Works across any tool that reads the format

File Structure

---
[YAML frontmatter]
---

[Markdown body sections]

Required Fields

Optional Fields

Metadata

Colors

Color object schema:

- name: "Descriptive Name"
  hex: "#RRGGBB"
  role: "how this color is used in the system"

Typography

Typography object schema:

display:
  family: "Font Family Name"
  weight: "bold"
  style: "uppercase, tight tracking"

Layout

Motion

Mood

Assets

Important: Assets are always URLs, never embedded binary data.

Extensions

Example:

x_heygen:
  video_id: "abc123"
  orientation: "landscape"

x_figma:
  library_id: "xyz789"

Markdown Body Sections

After the YAML frontmatter, include these optional Markdown sections:

## Connectors

Tool-specific translation notes:

## Connectors

### HeyGen Video Agent
Feed `style_prompt_full` as the visual style block. Use `motion.transitions`
for scene cuts. Orientation: landscape.

### HTML Slides
Map colors to CSS variables. Use `typography.display` for h1-h3.

## Design Principles

Freeform design philosophy:

## Design Principles

Typography drives hierarchy. Color is used sparingly and intentionally.
Every element snaps to a baseline grid. White space is a feature.

## Extraction Notes

Source documentation (when extracted):

## Extraction Notes

Extracted from https://example.com on 2026-03-12.
Primary colors sampled from hero section.
Typography identified via browser dev tools.

Complete Example

---
name: "Josef Müller-Brockmann Swiss International Style"
version: "1.0"
tags:
  - iconic design
  - sleek minimal
author: "Bin"
source_url: ""
created: "2026-03-12"

style_prompt_short: >
  Grid-locked Swiss precision. Black and white base with electric blue
  accent. Helvetica only. Data visualizations as hero elements.

style_prompt_full: >
  Josef Müller-Brockmann Swiss International Style. Grid-locked layouts
  with mathematical precision. Black and white base with ONE accent color
  (electric blue #0066FF). Strong diagonal compositions. Helvetica
  typography only. Data visualizations are the hero — animated charts,
  counters, grids. Every frame snaps to a grid. Transitions are horizontal
  grid wipes. No organic shapes. No gradients. No stock photography.
  Everything is geometric, systematic, precise.

colors:
  primary:
    - name: "Pure Black"
      hex: "#000000"
      role: "dominant ground, text, structural elements"
    - name: "Pure White"
      hex: "#FFFFFF"
      role: "background fields, negative space"
  accent:
    - name: "Electric Blue"
      hex: "#0066FF"
      role: "the ONE accent — data highlights, key emphasis"
  neutral:
    - name: "Grid Gray"
      hex: "#CCCCCC"
      role: "grid lines, secondary structure"

typography:
  display:
    family: "Helvetica"
    weight: "bold"
    style: "uppercase or sentence case, tight tracking"
  body:
    family: "Helvetica"
    weight: "regular"
    style: "flush left, ragged right, generous leading"
  caption:
    family: "Helvetica"
    weight: "light"
    style: "small, uppercase, wide tracking"
  rules:
    - "Helvetica ONLY — no other typeface"
    - "Type sizes follow a mathematical scale"
    - "Always flush left — never centered"

layout:
  grid: "Strict modular grid — 12 columns"
  alignment: "Flush left, grid-snapped"
  aspect_ratio: "16:9"
  notes:
    - "Every element locked to the grid"
    - "Data visualizations are the hero elements"

motion:
  transitions:
    - "horizontal grid wipes"
    - "elements snapping to grid positions"
    - "clean hard cuts"
  animation_style: >
    Geometric precision. Elements snap to grid positions.
    Charts animate systematically. Nothing bounces.
  pacing: "Measured, confident, unhurried"

mood:
  keywords:
    - "precise"
    - "systematic"
    - "authoritative"
    - "geometric"
  era: "1950s–1970s (timeless)"
  cultural_reference: "Müller-Brockmann, Grid Systems in Graphic Design"
  avoid:
    - "organic or curved shapes"
    - "gradients"
    - "stock photography"
    - "centered text"
    - "decorative elements"

assets:
  reference_images: []
  gsep_elements: []
  html_snippets: []
  color_palette_image:
    url: ""
---

## Design Principles

Typography and the grid are the only design elements needed.
Mathematical relationships create visual harmony.
Restraint is the ultimate sophistication.

## Connectors

### HeyGen Video Agent
Use `style_prompt_full` verbatim. No avatar, no b-roll — pure motion graphics.
Hard cuts between scenes.

### HTML Slides
Map to CSS: `--color-bg: #000`, `--color-text: #FFF`, `--color-accent: #0066FF`.
Use Helvetica via system fonts or Google Fonts equivalent.

Validation

A valid visual-style.md must have:

1. Valid YAML frontmatter between --- delimiters 2. All required fields present 3. colors.primary with at least 2 color objects 4. Each color object with name, hex, and role 5. version set to 1.0

Versioning

The version field refers to the spec version, not the style version. When the spec changes:

• Minor changes (new optional fields): Version stays 1.0
• Breaking changes (required field changes): Version increments to 2.0

Design Decisions

Why style_prompt_full is required

Many AI tools only accept a text prompt. By requiring a complete, natural language description of the style, we ensure every visual-style.md file is immediately usable by any tool — even ones that don't parse the structured fields.

Why no embedded binary data

URLs keep files small, versionable, and portable. Binary assets should be hosted externally and referenced by URL.

Why x_* namespacing

Different tools have different capabilities. The x_ prefix allows tool-specific configuration without polluting the core schema. Examples: x_heygen, x_figma, x_paper.

Why mood.avoid

Negative constraints are as important as positive ones. Telling an AI what NOT to do is often more effective than telling it what to do.

Design Principles

Freeform section for design philosophy and guiding principles. What beliefs drive this visual system? What trade-offs does it make intentionally?

Connectors

HeyGen Video Agent

Notes on how to apply this style to HeyGen Video Agent. What to emphasize in the prompt, what motion patterns to use.

HTML Slides

Notes on CSS mapping, layout approach, font loading.

paper.design

Notes on document setup, grid configuration, AI guidance.

Figma

Notes on style generation, component patterns, design tokens.

Extraction Notes

If this style was extracted from a source, document it here. Include the source URL, extraction date, and any notable decisions.