If you've ever asked Claude or Cursor to "update the homepage tagline" and got back something that didn't sound like your brand at all, you've experienced the problem brand.json solves. The AI didn't know your brand. It guessed. And guessing produces drift.
This piece explains what a brand.json file is, why it became the standard pattern for AI-ready business websites in 2026, and how to design one for your own project. By the end you'll understand the schema, the voice-rule conventions, and how to migrate an existing website to use a canonical brand context.
The One-Sentence Definition
brand.json is a single JSON file at the root of your website's codebase that contains every brand-affecting input — name, tagline, voice rules, colours, pricing, contact details, social links — so that AI coding assistants always read the same canonical source instead of inferring brand identity from the rest of the code.
Why It Exists
AI coding assistants are pattern-matchers operating on a limited context window. When you ask Claude to write a new section for your pricing page, Claude reads whatever's in its context window — the file you're editing, maybe a few siblings, your conversation history — and guesses about everything else.
If your brand voice is "casual Aussie mate", and Claude is reading a component that happens to have formal corporate copy in it, Claude's next output will be formal. If your pricing is "buy-once, no subscription", and Claude is reading a component that mentions monthly billing, Claude's next output will say "starting at $99/month". Without a single source of truth, every component has to re-establish brand context, and any one of them can drift.
brand.json fixes this by being the file Claude always reads first. In a Claude Code setup, you can pin brand.json to the conversation, or reference it in CLAUDE.md as the canonical context, or simply mention "check brand.json for voice and pricing rules" in your first message. From that point on, every output respects the canonical brand.
The Schema
There's no formal standard for brand.json yet — it's a convention emerging from teams building AI-ready websites. Here's the schema that's working well in production, adapted from the Velocity X template:
{`{
"business": {
"name": "Aidxn Design",
"legalName": "Aidxn Design Pty Ltd",
"email": "hi@aidxn.com",
"phone": "+61 ...",
"address": "Gold Coast, QLD, Australia",
"founded": 2011
},
"product": {
"name": "Velocity X",
"category": "Buy-once route-planner CRM template",
"price": "$4,995",
"priceLabel": "one-off · digital download · lifetime updates",
"packages": [
{ "id": "small", "name": "Small", "price": "$4,995", ... },
{ "id": "medium", "name": "Medium", "price": "$9,995", ... },
{ "id": "large", "name": "Large", "price": "$24,995", ... }
]
},
"voice": {
"tone": "casual Aussie mate by default, professional for customer-facing",
"phrasesToAvoid": ["leverage", "synergy", "best-in-class"],
"phrasesToUse": ["just build it", "cheers mate", "no worries"],
"audience": "small to mid-size service businesses"
},
"colours": {
"primary": "#8B5CF6",
"accent": "#06B6D4",
"text": "#03071E",
"background": "#F8F9FC"
},
"social": {
"github": "https://github.com/aidenwood",
"instagram": "https://instagram.com/aidxn.design"
}
}`}The exact keys vary by business. A trades company needs service categories. A SaaS product needs feature lists. A creative agency needs case-study slugs. The shape is yours to define. The rule is: if a piece of brand information appears in more than one component on your site, it belongs in brand.json.
How AI Tools Consume It
Three integration patterns are emerging.
Pattern 1: Read at build time. Astro and Next.js can import the JSON file in components and use it as data. Your hero component reads brand.product.price; your contact form reads brand.business.email; your colour palette comes from brand.colours. This way, every change to brand.json propagates through the whole site on the next build. AI assistants can edit brand.json directly when you ask for "global" changes.
Pattern 2: Pin it in the AI conversation. When working with Claude Code, you reference brand.json in CLAUDE.md as a context anchor. Claude reads it at the start of every conversation and treats it as the authoritative source. When you ask for a new section, Claude already knows your voice, your prices, your audience.
Pattern 3: Reference it in JSON-driven pages. If your pages are defined as JSON (a separate file per page, listing the components to render and their content), each page JSON can omit brand fields and rely on the canonical brand.json for defaults. A pricing page JSON doesn't need to list the price — it just says "show the pricing table" and the template reads prices from brand.json.
Voice Rules: The Underrated Section
Most teams nail the data fields but skip the voice section. That's a mistake. The voice rules are where brand.json becomes most useful for AI workflows.
A good voice section answers four questions: How does the brand sound at default? When does the tone shift (e.g. customer-facing copy, support, technical documentation)? What words and phrases should AI never use? What words and phrases should AI lean on?
Here's a real example from a trades-services brand we worked with:
{`"voice": {
"default": "Direct, warm, no-nonsense. Speaks to the homeowner like a tradesman who knows his stuff.",
"shift": {
"insuranceAssessors": "Slightly more formal, technical detail emphasised",
"blogPosts": "Casual, problem-solution structure, first-person"
},
"avoid": ["solutions provider", "industry-leading", "premier"],
"lean": ["sort it out", "no worries", "we'll get it done"],
"exampleHeadlines": [
"Hail damage? Get it sorted today.",
"We deal with the insurer so you don't have to."
]
}`}With those rules in brand.json, Claude can write any new content for the site and stay on-voice. Without them, every output is a coin flip.
Migrating an Existing Site
If you've got an existing website that wasn't built with this pattern, migration is straightforward but methodical.
Step one: grep your codebase for hardcoded brand strings. Your business name, tagline, pricing numbers, contact details. Anywhere they appear inline in components, replace with a reference to brand.json. This is mechanical work — Claude can do most of it in a single pass if you give it the brand.json shape and ask it to refactor.
Step two: define your voice rules. Write them as if you were briefing a new copywriter who's never seen your business. What should they say? What should they never say? Add example headlines and example "no go" headlines.
Step three: pin brand.json in your AI conversation. In Claude Code, add it to CLAUDE.md. In Cursor, reference it in the rules file. From that point on, every AI-assisted edit will respect the canonical brand.
For a 30-page small business website, the whole migration takes a developer about half a day. For a 200-page site, allow a day or two. After that, the iteration speed of every future edit goes up dramatically.
The Network Effects
brand.json gets more valuable the more it's used. Once it's the canonical source, you can build tooling on top of it:
You can generate sitemap and OpenGraph metadata from it. You can auto-render schema.org JSON-LD for SEO. You can power email templates, social-media-card previews, and PDF brand guidelines from the same file. You can let AI tools run automated audits — "does any page on the site contradict brand.json?" — and flag drift before it ships.
At Aidxn we have a Claude Code agent that runs once a week and checks every page against brand.json. If a headline contradicts the voice rules, it surfaces a PR with the fix. If a pricing number is stale, same thing. Total maintenance overhead is roughly zero.
Frequently Asked Questions
Is brand.json an open standard?
Not formally. It's a convention that emerged from teams building AI-native websites in 2025-2026. The schema varies per project. There's discussion in the AI engineering community about formalising it, but for now treat it as a pattern, not a spec.
Can I use YAML or TOML instead of JSON?
Yes. The file format is incidental. JSON is the most common because every framework parses it natively and every AI model is well-trained on JSON syntax. YAML is fine if you prefer it. The point is a single, canonical, machine-readable file — not the specific encoding.
What if my brand information is in a CMS already?
Two options. You can sync the CMS to brand.json at build time (a build script that pulls the latest CMS state into the file). Or you can move the brand information out of the CMS entirely and let editors update brand.json directly via a PR or a simple admin page. The CMS-as-source approach works but adds a moving part; the file-as-source approach is simpler for small businesses.
How big should brand.json be?
For a small business, expect 100-300 lines. For a multi-product brand, 500-1000 lines. If it grows past that, split it into multiple files (brand.json + voice.json + products.json) but keep them all at the project root so the AI knows where to look.
Does brand.json work with non-Claude AI tools?
Yes. The pattern is model-agnostic. Cursor, Copilot, Aider, Codeium, and Replit all benefit from a single canonical brand-context file. The file doesn't depend on Claude specifically — it's just a JSON file that happens to be very useful for any AI working on your codebase.
What happens if I don't have a brand.json?
Your AI tools will guess. Sometimes they'll guess right. Often they'll drift. Over months of AI-assisted edits, the drift compounds. Eventually your homepage and your pricing page sound like they were written by two different companies. The cost of skipping brand.json is invisible at first and severe later.
The Bottom Line
If you're building a custom website in 2026 — or running one that you want to keep working on with AI for the next five years — brand.json is not optional. It's the canonical context pattern that turns "I asked Claude to edit my site and it guessed everything wrong" into "I asked Claude to edit my site and the output matched the rest of the site perfectly". The pattern is simple, the migration is short, and the leverage is permanent. Start your brand.json this week.