lucky-branding

A disciplined five-phase brand-identity skill for Claude Code. It builds a brand the way a real studio does — creative direction first, then logo, then guidelines, then a production package — and ends with a tokens.json that a website or app can consume mechanically, with zero interpretation. It enforces the order, because the most common way an AI ruins a brand build is doing Phase 5 first.

The problem

Ask any AI to "make me a brand" and it jumps straight to Tailwind tokens and a hex palette. It works in code and fails everywhere else: there's no record of why the brand looks the way it does, no two-alternative exploration anyone chose between, no version trail, nothing a freelance designer or a client can pick up and continue. And the tokens it ships are flat hex named by appearance (green-500), so whoever builds with them ends up making brand decisions that were never theirs to make.

This skill encodes the discipline that prevents all of that.

The five phases

Each phase's output is the next phase's input. No skipping.

  1. Creative Direction — positioning, audience, tone, and two genuine aesthetic directions to choose between (not one + a strawman, not four). Approved before anything is drawn.
  2. Logo Concept — with an explicit render-tool decision: precise SVG for typographic/geometric marks, AI image-gen for illustrative ones. Don't dress one as the other.
  3. Brand Guidelines — the canonical counts: 5 colors (HEX + RGB + CMYK + Pantone, so it's print-ready) and 3 fonts in 3 roles.
  4. Brand Package — production files, and a tokens.json that must pass a handoff gate before it ships.
  5. Text Extraction — machine-readable guidelines.md + voice.md that code consumes directly. This is last, never first.

What's in the box

SKILL.md                      the enforcement layer (Claude reads this)
workflow.md                   the full five-phase methodology — document structures, gates
tokens/
  schema.md                   three-tier token architecture (primitive → semantic → component)
  phase4-handoff-gate.md      the checklist a tokens.json must pass before it ships
  sd.config.mjs               working Style Dictionary v4 build → CSS + Tailwind + Figma
  _template/tokens.json       starter color/space/radius tokens, OKLCH + hex fallback, dark mode
  _template/typography.json   fluid type scale + variable-font axis → voice-register mapping
_template/CONTEXT.md          scaffold to copy when starting a new brand

The token layer is the part most brand workflows skip and the part that makes this one different. Tokens are authored in OKLCH with hex fallbacks, organized in three tiers that reference downhill only, with dark mode derived as a semantic re-mapping (not a hex flip) and contrast validated with APCA. One tokens.json compiles to CSS custom properties, a Tailwind theme, and Figma Variables. Typography ships as fluid clamp() scales plus a variable-font axis → emotional-register mapping, so "warm hero headline" and "precise legal fine print" are deterministic axis values, not vibes.

Install

# project-level
mkdir -p .claude/skills/lucky-branding
curl -sL https://github.com/LuckyCody/lucky-branding/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=1 -C .claude/skills/lucky-branding

# or user-level (every project)
mkdir -p ~/.claude/skills/lucky-branding
curl -sL https://github.com/LuckyCody/lucky-branding/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=1 -C ~/.claude/skills/lucky-branding

Then say "build a brand for X" or invoke it directly.

To build tokens for a brand:

npm install style-dictionary@^4
BRAND=_template npx style-dictionary build --config tokens/sd.config.mjs
# → build/css/variables.css, build/tailwind/theme.cjs, build/figma/variables.json

Where this comes from

Extracted from a production Claude Code workspace that runs brand identity for a portfolio of products. The five-phase structure follows standard brand-studio practice; the enforcement discipline and the token architecture are the parts worth sharing. The token gate exists because "flat hex with no semantic layer" was a real, recurring handoff failure — this is the fix.

License

MIT