I kept consulting LLMs while building my service. The conclusions became a YAML file that generates CSS, Tailwind, and Figma tokens.
Why I started brandspec
The spark
While building a new service, I was constantly consulting LLMs.
What should I name this thing? Any good ideas? The AI would ask about my target audience. When I asked about the landing page, it would insist we nail down the tagline first. The foundational brand decisions — name, audience, personality, story — I was working through all of them by bouncing ideas off Claude and ChatGPT. I suspect many people are doing the same.
For colors, I was building a ThemeProvider to try different Tailwind themes on the half-built service. "Green, like a forest." "Something cool-looking." The AI would generate a color palette, I'd swap it in and compare. After several rounds, I'd have multiple decent options. Then the hard part: choosing.
What I realized through this process is that what a service is and how it looks are deeply connected. I'd participated in a brand identity workshop at a previous company. As a solo developer, I obviously can't hire professionals for that — but I thought maybe AI could approximate something similar.
So I built it
I also realized that these brand decisions are essentially a single source of truth. If you commit to maintaining them in one place, you get reproducible output.
The conclusions from the brainstorming (name, target, personality, story) and the design tokens derived from them (colors, typography) — if they live in the same file, everything a team needs to know about the brand is right there.
In an AI-readable format, you can generate CSS, Tailwind themes, Figma tokens in one pass. When you need to make a brand judgment later — should we appear on this platform? what tone for this copy? — the full context is in one place.
That's what I wanted. So I started building brandspec, an open-source CLI. MIT license.
brand.yaml — brand decisions and design tokens in one file
The core of brandspec is a file called brand.yaml. Brand identity and design tokens live together.
The only required field is meta.name. Minimal valid file:
meta:
name: "My Brand"
Nothing gets generated from this alone, but it's a valid brandspec file.
In practice, it grows into something like this:
meta:
name: "Acme Corp"
version: "1.0.0"
description: "Modern productivity tools for teams"
core:
essence: "Making the impossible satisfyingly simple"
tagline: "Simplicity, delivered"
personality:
- innovative
- approachable
- confident
voice:
tone:
- friendly
- clear
principles:
- "Use active voice"
- "Keep sentences short"
tokens:
colors:
primary:
$value: "oklch(0.65 0.18 250)"
$type: color
$description: "Main brand color"
primary-foreground:
$value: "oklch(0.98 0.01 250)"
$type: color
background:
$value: "oklch(0.99 0.005 250)"
$type: color
foreground:
$value: "oklch(0.15 0.02 250)"
$type: color
muted:
$value: "oklch(0.95 0.01 250)"
$type: color
muted-foreground:
$value: "oklch(0.45 0.02 250)"
$type: color
destructive:
$value: "oklch(0.55 0.20 25)"
$type: color
destructive-foreground:
$value: "oklch(0.98 0.01 25)"
$type: color
typography:
heading:
$value: "Inter, system-ui, sans-serif"
$type: fontFamily
body:
$value: "Inter, system-ui, sans-serif"
$type: fontFamily
assets:
- file: assets/logo-primary.svg
id: logo-primary
role: logo
variant: primary
The top half (core) is the brand decisions made through AI brainstorming. The bottom half (tokens) is the design tokens derived from those decisions. Having both in one file is the point.
Color tokens follow the W3C Design Tokens Community Group (DTCG) spec. Colors use oklch1.
AI Workshop — build brand.yaml through conversation
brandspec includes an AI Workshop: a structured conversation flow for developing your brand, designed to run in Claude Code.
It progresses through 4 phases:
- Discovery — map the background, target audience, and competitive landscape
- Concept — develop the name, tagline, personality, and story
- Visual Identity — decide on color palette, typography, and logo direction
- Documentation — compile everything into brand.yaml
You can start from vague requests like "green, forest-like" and get oklch color palette proposals. Adjust until you're satisfied. Decisions accumulate in _workshop/decisions.yml, so context survives interruptions.
The workshop LLM isn't fixed. Claude, GPT, whatever model you prefer. Since brand.yaml and decisions.yml are passed as context, switching models doesn't lose the thread.
The end result is a brand.yaml. You can also hand-write the YAML directly — the workshop is optional.
Setup
Node.js 18+.
npx brandspec init
This creates a brandspec/ directory:
brandspec/
├── brand.yaml # Brand definition
├── assets/ # Logos, icons, etc.
└── _workshop/ # AI workshop state
├── position.yml
├── decisions.yml
├── memo.md
└── session.md
I'd recommend placing brandspec/ inside your frontend project and checking it into git. With brand.yaml in the repo, AI tools like Claude Code can read it directly and give you brand-aware advice.
Lint
npx brandspec lint validates brand.yaml against 15 rules, including WCAG contrast checking (oklch-aware), and gives a score out of 100. Use --json for CI integration.
Generate
npx brandspec generate --format all
Four formats come out:
dist/
├── tokens.css # CSS Custom Properties
├── theme.css # Tailwind v4 theme
├── figma-tokens.json # Figma tokens
└── style-dictionary/
├── tokens.json # DTCG format
└── config.json # Style Dictionary config
tokens.css — CSS Custom Properties
:root {
--primary: oklch(0.65 0.18 250);
--primary-foreground: oklch(0.98 0.01 250);
--background: oklch(0.99 0.005 250);
--foreground: oklch(0.15 0.02 250);
/* ... */
--font-heading: Inter, system-ui, sans-serif;
--font-body: Inter, system-ui, sans-serif;
}
theme.css — Tailwind v4
Same tokens in Tailwind v4's @theme format. Prefixed as --color-primary, so bg-primary and text-foreground work out of the box. shadcn/ui compatible.
figma-tokens.json
Tokens Studio format. Import directly into Figma Variables.
Style Dictionary
W3C DTCG JSON with config. Run npx style-dictionary build to expand into CSS, SCSS, iOS Swift, Android XML.
What this means
Build your brand with AI. The decisions land in brand.yaml. From there:
- Frontend → import
tokens.cssortheme.css - Designers → load
figma-tokens.jsoninto Figma - Multi-platform → Style Dictionary for iOS / Android
- CI →
brandspec lint --jsonfor automated brand validation - Next AI session → feed it brand.yaml and it responds with full brand context
Update one value in brand.yaml, re-run npx brandspec generate. Done.
Closing
A brand should be solid. But left unattended, it dissipates in practice — buried in chat logs, living only in someone's head.
I think we're past that now. A single file that holds the full definition, readable by both machines and humans.
If you're already using Claude Code or similar tools, you can start managing your brand locally today. Give brandspec.dev a look.
and
*There's also a SaaS version at brandspec.tools.
- Host your brandspec directory
- Run the workshop through a GUI
- Use AI without your own model subscription
- Have the AI write in your brand's tone via Consult
- Share colors, assets, and guidelines with your team
During the beta, free signups come with AI tokens included.
npx brandspec init
GitHub: brandspec/brandspec
-
oklch is a perceptually uniform color space. Operations like "increase saturation without changing lightness" work intuitively. It also supports wide gamut. You can write hex or hsl, but oklch is better for fine-tuning brand colors. It's standardized in CSS Color Level 4 and supported by all major browsers. ↩
Top comments (0)