brand-kit-playground

name	brand-kit-playground
description	Generate an interactive HTML brand playground that shows your brand rendered live — palette, typography, logo, voice — with a social card and OG image preview that updates as you tweak tokens. Opens in browser. The visual approval step for the /cmo flow: /visual-style writes the brand, this skill shows it. Use when the user says "show me my brand", "brand playground", "preview my brand", "what does our brand look like", "visual preview", "brand kit", "see my colors", "how does my brand look", or after /visual-style completes and the user needs to approve the visual identity before moving to content generation. Also use when someone says "I want to see it" during any brand-building conversation.
reads	["brand/creative-kit.md","brand/voice-profile.md","brand/positioning.md","brand/audience.md"]
writes	["brand/creative-kit.md","brand/assets.md"]
depends-on	["visual-style"]
triggers	["brand playground","show me my brand","preview my brand","what does our brand look like","visual preview","brand kit","see my colors","how does my brand look","brand kit playground","render my brand"]
allowed-tools	["Bash(open *)"]

/brand-kit-playground — Visual Brand Workbench

Your brand lives in markdown files. This skill renders it as a living, interactive HTML page the user opens in their browser — palette swatches, type specimens, logo lockups, and a real social card preview that updates as they tweak tokens. When they're happy, they copy the structured JSON and you write it back to brand/creative-kit.md.

This is the visual approval step in the /cmo flow. /visual-style writes the brand identity. This skill shows it.

---

On Activation

1. Read brand/creative-kit.md — extract the Colors, Typography, and Visual Brand Style sections.
   • If the file is template/empty: warn the user. "Your creative kit is empty — the playground will use placeholder values. Run /visual-style first for a real preview, or continue and I'll use defaults you can tweak."
   • If it has real content: proceed. Parse colors (hex values), fonts (family names), border radius, shadows, gradients.
2. Read brand/voice-profile.md — extract tone adjectives, vocabulary preferences, headline style.
3. Read brand/positioning.md — extract the primary positioning angle for the social card headline.
4. Read brand/audience.md if it exists — extract audience description for the voice snapshot panel.
5. If no brand files exist at all: proceed with sensible defaults. The playground works at L0. Show placeholder brand with a note: "These are defaults. Fill in your brand files and re-run for a real preview."

---

What You Build

A single self-contained HTML file with inline CSS and JS. Zero external dependencies except Google Fonts (loaded via <link>). No framework. No build step. No server.

The file is written to the project root as brand-playground.html and opened in the user's default browser via open brand-playground.html.

Layout

+-- BRAND BAR ------------------------------------------------+
|  [Logo] Project Name Brand Playground    [Light/Dark toggle] |
+--------------------------------------------------------------+
|                    |                                          |
|  CONTROLS          |  TAB: [Brand System] [Social Card] [OG] |
|  --------          |  ----------------------------------------|
|                    |                                          |
|  > Colors          |  (Brand System tab)                     |
|    Primary [pick]  |  COLOR PALETTE                          |
|    Secondary       |  ## ## ## ## ## (live swatches)          |
|    Accent          |                                         |
|                    |  TYPOGRAPHY                             |
|  > Typography      |  Display: Aa Space Grotesk              |
|    Display font    |  Body: Aa Inter Regular                 |
|    Body font       |  Mono: Aa JetBrains Mono               |
|    Scale ratio     |                                         |
|                    |  VOICE SNAPSHOT                         |
|  > Visual Style    |  Tone: confident, warm, technical       |
|    Border radius   |  Audience: indie developers             |
|    Shadow depth    |  Style: short-punchy headlines          |
|    Texture         |                                         |
|                    |  (Social Card tab)                      |
|  > Social Card     |  +---------------------------+          |
|    Headline        |  |                           |          |
|    Subhead         |  |  We just shipped          |          |
|    Badge text      |  |  dark mode                |          |
|    Layout [v]      |  |                           |          |
|    Background [v]  |  |  [logo]          [NEW]    |          |
|                    |  |                           |          |
|  > Presets         |  +---------------------------+          |
|    Launch          |  1200x675 - Twitter/X                   |
|    Blog Post       |                                         |
|    Feature         |  MULTI-PREVIEW:                         |
|                    |  [Tw] [Li] [IG] [St]                    |
+--------------------+-----------------------------------------+
|  TOKEN OUTPUT (structured JSON)              [Copy Tokens]   |
+--------------------------------------------------------------+

Three Tabs

Tab 1: Brand System — The identity overview. Color palette rendered as large swatches with hex values and contrast ratios. Typography specimens at the brand's modular scale. Logo lockups (primary, mark, on-dark) if logo paths exist in creative-kit.md. Voice snapshot showing tone, vocabulary, headline style from voice-profile.md.

Tab 2: Social Card — A live social card preview rendered with the brand tokens. The user types a headline, picks a layout variant (centered, split, overlay, minimal), chooses a background style (gradient, solid, dark, light). The card re-renders instantly. Below: a multi-preview strip showing the same card at Twitter (1200x675), LinkedIn (1200x627), Instagram (1080x1080), and Story (1080x1920) aspect ratios.

Tab 3: OG Image — Same pattern as social card but for OG images. Inputs: title, description, author, category tag. Layouts: editorial, minimal, bold. Target: 1200x630.

Controls Panel (Left Side)

Controls are grouped by concern. Each group is collapsible. Controls update the preview instantly — no "Apply" button.

Token	Control	Range
Colors (primary, secondary, accent, background, foreground)	Color picker (native <input type="color">)	Any hex
Display font	Dropdown	10 curated options + current brand font
Body font	Dropdown	10 curated options + current brand font
Scale ratio	Slider	1.125 (Major Second) to 1.5 (Perfect Fifth)
Border radius	Slider	0px to 24px
Shadow depth	Slider	none / sm / md / lg / xl
Social card headline	Text input	Max 60 chars
Social card layout	Segmented buttons	Centered / Split / Overlay / Minimal
Social card background	Dropdown	Gradient / Solid / Dark / Light

Token Output (Bottom)

A <pre> block showing the current token state as structured JSON:

{
  "colors": {
    "primary": "#6366F1",
    "primaryForeground": "#FFFFFF",
    "secondary": "#7C3AED",
    "accent": "#F59E0B",
    "background": "#FFFFFF",
    "foreground": "#0F172A"
  },
  "typography": {
    "display": { "family": "Space Grotesk", "weights": [700, 800] },
    "body": { "family": "Inter", "weights": [400, 500, 600] },
    "scale": { "base": 16, "ratio": 1.25 }
  },
  "visual": {
    "borderRadius": "8px",
    "shadowDepth": "md",
    "texture": "none"
  }
}

A "Copy Tokens" button copies this JSON to the clipboard. The user pastes it back into the conversation. The agent reads the JSON and updates brand/creative-kit.md accordingly.

Presets

Include 3-5 presets that snap all controls to a cohesive combination:

Preset	Vibe	Colors	Type	Visual
Tech Startup	Clean, modern, confident	Indigo + violet + amber	Space Grotesk + Inter	8px radius, md shadow
Indie Maker	Warm, approachable, fun	Coral + teal + gold	Instrument Serif + DM Sans	12px radius, lg shadow
Enterprise	Precise, authoritative, refined	Navy + slate + emerald	General Sans + IBM Plex	4px radius, sm shadow
Creative Studio	Bold, expressive, artistic	Hot pink + lime + black	Space Grotesk + Syne	0px radius, none shadow
From Brand	Current creative-kit.md values	(extracted)	(extracted)	(extracted)

The "From Brand" preset is always first and always selected on load. It represents the current brand state. Other presets are for exploration.

---

How You Generate It

Step 1: Extract Tokens

Parse brand/creative-kit.md into structured data. Look for:

• Colors section: hex values for primary, secondary, accent. If not found, derive from the first hex codes mentioned anywhere in the file.
• Typography section: font family names, weights. If Google Fonts, construct the <link> URL.
• Visual Brand Style section: aesthetic direction, lighting, composition notes. Use these to inform the playground's own aesthetic (dark mode vs light, gradient direction, texture).
• Logo paths: if mentioned, include as <img> tags in the brand system tab.

If parsing is ambiguous, use reasonable defaults and note what you assumed.

Step 2: Write the HTML

Use the template structure from references/html-architecture.md. The file should be 800-1500 lines depending on brand complexity. Key implementation details:

• All CSS as <style> in <head>. Brand tokens as CSS custom properties on :root.
• All JS as <script> before </body>. Single state object, single updateAll() function.
• Google Fonts loaded via <link rel="stylesheet"> — this is the ONE external dependency.
• Dark/light toggle switches :root variables. Both themes use the brand palette.
• Social card renderer uses absolute positioning within a fixed-aspect-ratio container.
• Multi-preview strip uses CSS transform: scale() to show all sizes simultaneously.
• Color pickers use native <input type="color"> — no library needed.
• Token output updates on every state change via JSON.stringify(state.tokens, null, 2).
• Copy button uses navigator.clipboard.writeText().

Step 3: Open It

open brand-playground.html

Tell the user: "Your brand playground is open in the browser. Play with the controls — every change updates the preview instantly. When you're happy with how it looks, click 'Copy Tokens' and paste the JSON here. I'll update your brand files."

Step 4: Process Feedback

When the user pastes the token JSON back:

1. Parse it.
2. Diff against current brand/creative-kit.md values.
3. Show the diff: "You changed primary from #6366F1 to #4F46E5 and increased border radius to 12px. Want me to update creative-kit.md?"
4. On confirmation, write the changes to the appropriate sections of creative-kit.md.
5. Log the update to brand/assets.md: "Brand playground session — updated colors and visual style."

---

Integration with /cmo Flow

This skill slots into the /cmo foundation-building workflow:

/cmo activation
  -> mktg init (if needed)
  -> 3 research agents in parallel (brand, audience, competitors)
  -> /visual-style (writes creative-kit.md)
  -> /brand-kit-playground (renders creative-kit.md as interactive HTML)
     -> User tweaks in browser
     -> User copies tokens
     -> Agent updates creative-kit.md
  -> Continue to /image-gen, /creative, etc.

The playground is the approval gate between brand definition and brand execution. Before this skill existed, the user approved their visual identity by reading markdown. Now they see it rendered.

---

Progressive Enhancement Levels

Level	Context	Behavior
L0	No brand files	Placeholder brand with defaults. Full functionality. Note: "These are defaults."
L1	creative-kit.md only	Tokens extracted. No voice or positioning in the snapshot panels.
L2	creative-kit + voice	Tokens + voice snapshot. Social card headlines informed by voice style.
L3	creative-kit + voice + positioning	Full context. Social card headline defaults to positioning angle.
L4	All 4 files	Complete playground with audience info in voice panel. Best experience.

---

Anti-Patterns

Anti-pattern	Instead	Why
Generating a Next.js app with npm install	Single HTML file, zero dependencies	The playground must be instant. npm install is a 30-second wall that kills the flow. /app-store-screenshots scaffolds Next.js because it needs html-to-image for PNG export. This skill only needs browser rendering.
Using a framework (React, Vue, etc.)	Vanilla JS with a state object	Frameworks add bundle size, build complexity, and failure modes. The /playground plugin proves vanilla JS works for interactive previews.
Making the HTML generic/template-looking	The playground LOOKS like the brand	If the brand is dark and moody, the playground chrome should be dark. If the brand is warm and organic, the playground should feel warm. The playground's own aesthetic is derived from the brand tokens — it's not neutral gray chrome.
Hardcoding Google Fonts URLs	Construct URLs from the font names in creative-kit.md	The user's brand may use any font. Read the font name, build the URL. If the font isn't on Google Fonts, fall back to the closest system font.
Skipping the multi-preview strip	Always show at least 3 aspect ratios	The whole point of the social card tab is to see how the brand renders at real platform dimensions. One size isn't enough — the user needs to see Twitter vs Instagram vs Story to catch layout problems.
Outputting raw CSS instead of JSON tokens	Structured JSON with semantic names	The agent needs to parse the output and write it to creative-kit.md. CSS variables are for the browser. JSON tokens are for the agent loop.
Asking the user to manually edit creative-kit.md after the playground	Read the pasted JSON and write the changes yourself	The playground exists to make brand editing visual. Making the user edit markdown afterward defeats the purpose.

---

Governance Checks (Built Into the HTML)

The playground includes a governance strip below the preview:

[checkmark] Contrast: AA   [checkmark] Heading readable   [warning] Accent on bg: 2.8:1 (needs 3:1)

Implementation: after each state change, run WCAG contrast ratio checks on all text-background combinations. Use the relative luminance formula inline — no library needed. Flag failures as warnings with the specific ratio.

---

Font Curation

For the font dropdowns, offer these curated options plus whatever the brand currently uses:

Display fonts: Space Grotesk, General Sans, Instrument Serif, Syne, Clash Display, Satoshi, Plus Jakarta Sans, Outfit, Bricolage Grotesque, Manrope

Body fonts: Inter, DM Sans, IBM Plex Sans, Source Sans 3, Nunito Sans, Geist, Work Sans, Rubik, Lato, Open Sans

These are all on Google Fonts. The dropdown should show the font name rendered in that font (via per-option font-family).

---

File Output

File	Path	Description
Playground HTML	brand-playground.html (project root)	The interactive playground
Asset log entry	brand/assets.md	"Brand playground generated — [date]"

The HTML file is gitignored by convention (it's a generated artifact). The user can regenerate it anytime by re-running the skill.

---

Error Recovery

Problem	Fix
creative-kit.md has no parseable colors	Use defaults. Note which values were assumed in the token output.
Font not found on Google Fonts	Use the closest system font. Show a warning: "Couldn't load [font]. Using [fallback]."
User doesn't paste tokens back	That's fine. The playground served its purpose as a visual check. No brand files need updating.
Logo path in creative-kit.md doesn't resolve	Skip logo rendering. Show placeholder text: "[Logo]".
User wants to re-run after brand changes	Just re-run the skill. It reads current brand files and generates a fresh HTML.