Brand voice guidebooks are PDFs nobody reads. They sit in Slack pins, get forwarded to new hires, and collect dust. Meanwhile, your copywriter is writing "unlock your potential" while your AI assistant is drafting headlines in corporate jargon, and nobody's on the same page. The fix isn't a thicker PDF. It's encoding tone-of-voice rules in code.
Velocity X stores voice rules in brand.json — a canonical source of truth that humans read AND AI tools consume. Default tone, shift conditions, avoid-list, lean-list, real-world headline examples, explicit NO-GO phrases. Every writer (human or AI) reads this first. Copy stays on-brand automatically. No more tone drift. No more "can you make this sound like us?".
Why Voice Docs Fail, and Why Code Wins
A traditional brand voice guide is a document: "Our tone is confident, direct, warm." Then 50 writers interpret this 50 different ways. One thinks "confident" means aspirational; another reads it as confrontational. Without examples, without enforcement, without a machine that reads the rules and flags violations, every piece of copy is a gamble.
Brand voice encoded in brand.json is different. It's atomic. It's checkable. When a writer (or Claude, or Cursor) drafts copy, the voice rules are already pinned in the conversation context. When you update copy, the AI re-reads the rules first. When a new team member joins, they don't ask "what's our voice?"; they read brand.json and see tone, avoid-list, lean-list, and 10 example headlines in one place. It's version-controlled. It's executable.
The JSON Schema — What It Looks Like
Here's the real pattern from a Velocity X site:
{`"voice": {
"default": "Direct, warm, uncluttered. No corporate hedging. Speak like you're explaining to someone who's nervous about the decision.",
"tone": "Confident without arrogance. Helpful without condescension.",
"shiftConditions": [
{
"context": "Talking to insurance assessors (internal audience)",
"tone": "Formal, technical, numbers-first. Lose the warmth. Add the jargon."
},
{
"context": "Talking to homeowners after a claim (emotional moment)",
"tone": "Warm, reassuring. Less jargon. Emphasise speed and simplicity."
}
],
"avoid": [
"leverage",
"synergy",
"solutions provider",
"premier",
"industry-leading",
"unlock potential",
"best-in-class",
"proprietary methodology"
],
"lean": [
"get it sorted",
"no worries",
"we'll handle it",
"takes one day",
"here's the real cost",
"no hidden fees"
],
"exampleHeadlines": [
"Hail damage? We handle the lot.",
"Get paid. We deal with the insurer.",
"One day onsite. Rest of the week paid."
],
"noGoHeadlines": [
"Leverage Our Premium Claims Solutions",
"Industry-Leading Assessment Excellence",
"Synergised Stakeholder Optimisation"
]
}`}Notice what's here: not just vibes, but rules. The avoid-list is scannable. The lean-list is actionable. The shift-conditions give explicit permission to change tone for specific audiences. The example headlines and NO-GO headlines are real text, not abstract principles. When Claude drafts a headline and it reads like the NO-GO list, the writer (or the AI) can see the mismatch instantly.
How AI Tools Consume Voice Rules
You drop brand.json into your Claude conversation or pin it in CLAUDE.md (the project context file). When you ask Claude to "write a homepage headline", Claude reads brand.json first, sees the avoid-list and lean-list, and structures the output to respect them. When you say "this doesn't sound like us", you don't re-explain the voice; you say "read brand.json again" and the AI knows exactly what went wrong.
Same with Cursor. Pin brand.json in your project's CLAUDE.md, and every code completion that touches marketing copy gets the voice rules in context. Your IDE becomes voice-aware.
This is not about forcing robots to write like humans. It's about giving robots (and humans) a single, machine-readable spec so they all drift in the same direction. Without brand.json, you're coaching the same lesson 50 times. With it, you write once and every writer (biological or digital) reads it first.
Real Velocity X Example
A Sydney roofing company's brand.json voice section lives alongside category-pages/services.json and item-pages/hail-claim-assessment.json. When the copywriter updates the hail assessment page, they open brand.json first. When they work with Claude to rewrite the pricing section, Claude reads brand.json and avoids phrases like "premium assessment solutions" automatically. When the onboarding flow gets rebuilt, the tone rules move with it. The voice is not a separate artifact; it's infrastructure.
Frequently Asked Questions
Do I really need JSON for this? Isn't a Markdown doc enough?
Markdown is human-friendly but not tool-friendly. JSON is both. When Claude or Cursor parses brand.json, they extract structured data (avoid-list as array, tone-shifts as objects, examples as strings). Markdown requires a lot more parsing. Code tools work with JSON natively.
What if my voice is complex and has lots of exceptions?
That's what shiftConditions is for. Define each audience (homeowner, assessor, competitor, internal team) with its own tone rules. You can have 5 different voices in the same brand.json, each mapped to a specific context. The system scales.
How do I enforce this when my copywriter doesn't use Claude?
Manual review against brand.json. Before approving any marketing copy, check it against the avoid-list and lean-list. It takes 30 seconds. Over time, the writer internalises the rules because they're in one place, not scattered across emails and feedback.
Should I include brand.json in my public repo?
Yes. It's not a secret. It's brand infrastructure. Developers, designers, writers, and AI tools all need access. Keep it public. Version-control it. Update it when your voice evolves.
How often should I update brand.json?
When your voice actually shifts. Don't touch it every quarter out of habit. But if you notice your team consistently using new phrases or avoiding old ones, update the lists. Every 6-12 months, audit the avoid-list and lean-list against what you've shipped in the past quarter. Sync the file to reality.
Can I use brand.json without Velocity X?
Absolutely. brand.json is just a JSON file. It doesn't care what framework you're using. Drop it in any project, reference it in your CLAUDE.md, and share it with your team and AI tools. The pattern works everywhere — Astro, Next, Django, whatever.
The Bottom Line
Brand voice guidebooks are cargo-cult marketing. They sit on shelves and nobody reads them. brand.json is infrastructure. It's version-controlled, machine-readable, pinned in every AI conversation, and checked during every review. One file. All writers. All tools. Same tone. Check out the full brand.json schema reference post for the complete pattern, or hit the pricing page to see how Velocity X scaffolds voice rules for a new brand.