Brand System

Brand System

Scaffolds a brand book + design system that sits at the root of a web product's repo — long-form BRAND.md (the working reference, 20 sections) paired with BRAND.html (the printable stakeholder distillation, ~7 A4 pages, rendered to BRAND.pdf via Chrome headless) and a matched tokens.css for Tailwind v4 @theme.

This skill authors the document. Its sibling [brand-assets](../brand-assets/SKILL.md) produces the pixels (SVG favicons, PWA pack, apple-touch-icon). Call both in sequence for a complete brand rollout.

The five artifacts

| Artifact | What | How | |---|---|---| | BRAND.md | Long-form 20-section working reference | [templates/BRAND.md.tmpl](templates/BRAND.md.tmpl) via [scripts/new-brand-book.sh](scripts/new-brand-book.sh) | | BRAND.html | 7-page A4 printable distillation | [templates/BRAND.html.tmpl](templates/BRAND.html.tmpl) via same script | | BRAND.pdf | Rendered via Chrome headless | [scripts/render-pdf.sh](scripts/render-pdf.sh) | | tokens.css | Tailwind v4 @theme + :root + [data-theme="dark"] | [templates/tokens.css.tmpl](templates/tokens.css.tmpl) + [scripts/extract-tokens.py](scripts/extract-tokens.py) | | tokens.json | W3C DTCG format for Style Dictionary / Tokens Studio | scripts/extract-tokens.py --format dtcg |

Workflow (decision tree)

1. Starting fresh? — run the signature-moves interview first:

copy [templates/signature-interview.md.tmpl](templates/signature-interview.md.tmpl) into the repo and answer every question before scaffolding. See [reference/signature-moves.md](reference/signature-moves.md) for why each question matters. Without this, the output is a template; with it, it's a brand.

1. Scaffolding a new book? — run

[scripts/new-brand-book.sh](scripts/new-brand-book.sh) with the interview answers as flags. Emits BRAND.md, BRAND.html, tokens.css, signature-interview.md into the output dir.

1. Drafting a specific chapter? — load the matching reference:

• §0 the idea / §2 primitive / §3 signature moves → [reference/signature-moves.md](reference/signature-moves.md)
• §5 logo + favicon pack → [reference/favicon-pack.md](reference/favicon-pack.md)
• §6 colour → [reference/color.md](reference/color.md) + [reference/tokens.md](reference/tokens.md)
• §7 typography → [reference/typography.md](reference/typography.md)
• §10 surfaces & materials → [reference/surfaces.md](reference/surfaces.md)
• §11 motion → [reference/motion.md](reference/motion.md)
• §13 voice & tone → [reference/voice-and-tone.md](reference/voice-and-tone.md)
• §14 accessibility → [reference/accessibility.md](reference/accessibility.md)
• §17 Tailwind v4 @theme → [reference/tailwind-v4.md](reference/tailwind-v4.md)
• Hebrew / Arabic / RTL → [reference/rtl.md](reference/rtl.md)

1. Favicon + PWA pack? — do not generate assets in this skill.

[reference/favicon-pack.md](reference/favicon-pack.md) specs the requirements (system-aware SVG favicon, opaque apple-touch-icon, maskable PWA, OG light+dark pair). Hand the spec + a source SVG to the [brand-assets](../brand-assets/SKILL.md) skill's icon-pack.sh.

1. Contrast audit before shipping →

[scripts/audit-contrast.py](scripts/audit-contrast.py). WCAG 2.2 AA on body (4.5:1), 3:1 on large / UI / focus rings. Runs per theme (light + dark). Paste the matrix into §14.

1. Rendering the PDF →

[scripts/render-pdf.sh](scripts/render-pdf.sh). Chrome headless. Produces BRAND.pdf from BRAND.html.

1. Auditing an existing book →

[scripts/audit-outline.py](scripts/audit-outline.py). Validates the 20-section outline, flags missing decision log entries, warns if §2 signature primitive has …` answer lines. Strongly recommended.

House rules

1. Require the anti-template moves before scaffolding. The

interview is not optional. One invented proper noun, three falsifiable principles, three real don'ts from past mistakes, a 150-word voice sample in the brand's voice, and one signature move that deliberately breaks a best practice. Without these, the book is a template. See [reference/signature-moves.md](reference/signature-moves.md).

1. Accent constant across light/dark. Only surface and text

semantic tokens swap between themes. The one saturated brand colour is identical in both modes — that's what lets a signature primitive mean the same thing regardless of system preference. Encoded in [templates/tokens.css.tmpl](templates/tokens.css.tmpl).

1. Three-tier tokens per Nathan Curtis taxonomy. Primitive

(--color-cream: #F3EAD3) → semantic (--bg: var(--color-cream)) → component (--btn-bg: var(--bg-elevated)). Primitives go in @theme, semantics in :root, dark-mode overrides in [data-theme="dark"]. See [reference/tokens.md](reference/tokens.md).

1. WCAG 2.2 AA is the legal floor in 2026. Not APCA — APCA was

pulled from WCAG 3 in July 2023 and has not returned. AA means 4.5:1 body, 3:1 large/UI/focus, 24×24 target-size-minimum. Audited with [scripts/audit-contrast.py](scripts/audit-contrast.py); see [reference/accessibility.md](reference/accessibility.md).

1. RTL is a foundation, not an appendix. If the product ships in

Hebrew or Arabic, use CSS logical properties (margin-inline-start, not margin-left) from day one; the retrofit cost is 10–50× designing-for-it upfront. See [reference/rtl.md](reference/rtl.md).

1. The brand book is itself an instance of the brand. The

BRAND.html template uses the product's own palette + type — so the document looks like the brand on page 1. If the brand book's own styling doesn't pass the rules it preaches, it's wrong.

1. System-first, toggle-second for dark mode. Respect

prefers-color-scheme by default; persist explicit user overrides in localStorage. A visible dark-mode toggle in the nav is an anti-pattern. The system-aware SVG favicon rule in [reference/favicon-pack.md](reference/favicon-pack.md) follows the same logic.

Non-goals

• Generating logo artwork — that's [image-generation](../image-generation/SKILL.md).
• Mechanical asset pipelines (vectorize PNG → SVG, icon-pack

generation, rasterize at size) — that's [brand-assets](../brand-assets/SKILL.md).

• Building the actual components — §18 of BRAND.md documents the

specs; [react-components](../react-components/SKILL.md) and [frontend-design](../frontend-design/SKILL.md) implement them.

• Brand storytelling / marketing copywriting — §13 governs how to

write, not what.

• Translating copy — the skill scaffolds RTL-aware structure but

doesn't translate.

• Versioning the brand book as a product — update in place, commit

with a clear message, one source of truth at the repo root.

Canonical 20-section outline (what BRAND.md.tmpl emits)

| # | Section | Core must-have | |---|---|---| | 0 | The idea | One-sentence core idea + the "strip everything but X" test | | 1 | Reading the mark | 3–5 simultaneous readings of the logo | | 2 | Signature primitive | The semantic token that appears across every surface — 8+ use sites | | 3 | Signature moves | 5–7 things that identify the brand without the logo | | 4 | Brand essence | What we are / are not / tone / positioning sentence | | 5 | Logo system | Variants, clear space, min size, don'ts, favicon + PWA pack requirements | | 6 | Colour system | Core + extended + neutrals + semantic tokens, 62/30/8 ratio, light/dark parity | | 7 | Typography | Face, tabular nums, scale, measure, RTL moves, wordmark treatment | | 8 | Iconography | Style, colour rules (accent never used), size tokens, RTL flipping | | 9 | Spacing & layout | 8-point grid, containers, radii + concentric-radii rule | | 10 | Surfaces & materials | Default + floating material, grain overlay, hero backgrounds | | 11 | Motion | Principle, tokens, the signature animation, reduced-motion behaviour | | 12 | Imagery & illustration | Photography rules, illustration style, anti-patterns | | 13 | Voice & tone | Rules, tone matrix by emotional state, 3-levels-of-same-thought, RTL specifics | | 14 | Accessibility | WCAG 2.2 AA contrast matrix, focus rings, reduced motion, RTL equivalence | | 15 | Reference set | What shelf the brand sits on + what it's not | | 16 | Anti-patterns | Specific "don't do this" list — concrete bad habits banned | | 17 | Implementation — Tailwind v4 @theme | Full block, :root + [data-theme="dark"], body rules | | 18 | Components | Buttons, links, inputs, cards, badges, nav, alerts, dialogs, prose, landing primitives | | 19 | Migration plan | What's being retired; ✅/⚠️/❌ per token/pattern; dates | | 20 | What this is not + Decision log | Non-goals + dated table of decisions with rationale |

Quick invocation

# Scaffold a new brand book at the repo root
~/.claude/skills/brand-system/scripts/new-brand-book.sh \
  --product "Agentiko" \
  --positioning "A real worker who lives inside WhatsApp." \
  --palette-bg '#F3EAD3' \
  --palette-fg '#0E1320' \
  --palette-accent '#B85A3A' \
  --signature-primitive "voice dot" \
  --primary-font "Rubik" \
  --locale "he" \
  --output-dir .

# Audit contrast
~/.claude/skills/brand-system/scripts/audit-contrast.py \
  --bg '#F3EAD3' --fg '#0E1320' --accent '#B85A3A'

# Render the printable
~/.claude/skills/brand-system/scripts/render-pdf.sh BRAND.html BRAND.pdf

# Later: check an existing book against the outline
~/.claude/skills/brand-system/scripts/audit-outline.py BRAND.md

Related skills

• [brand-assets](../brand-assets/SKILL.md) — mechanical SVG/PNG pipelines; run after this skill to produce the favicon pack.
• [image-generation](../image-generation/SKILL.md) — design logo/hero imagery before this skill runs.
• [frontend-design](../frontend-design/SKILL.md) — implement §18 components in production code.
• [react-components](../react-components/SKILL.md) — build component primitives once §18 is authored.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shaharsha
• Source: shaharsha/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.