AI reads your repo, not your brand PDF

AI reads your repo, not your brand PDF

Brand New went on summer break in mid-August. They don't post again until Monday. Since the industry review of record was quiet this week, it was easier to see where the real identity news landed. It wasn't a logo launch. It was a file format on GitHub.

Google open-sourced DESIGN.md. It is the spec behind their Stitch design tool. Atlassian followed with field notes from testing what they call "portable design context" in their own workflow. 

Nobody rebranded. Yet this is the most consequential thing to happen to brand guidelines this year. It settles where they live. 

Your brand guidelines are becoming a file in the repo. If you haven't written that file, the model's defaults are your brand guidelines now.

The first part is tooling news. The second part is a positioning crisis.

The vacuum has a look (and you've seen it)

When a coding agent generates your pricing page or dashboard, it makes hundreds of visual decisions. It makes them whether you weigh in or not. 

Without an instruction file, the agent falls back on the center of its training data. This is the averaged output of every SaaS product ever screenshotted. You know the look: Inter, a blue gradient, rounded corners, and a bento grid. 

It is competent. It is also the most crowded position in software. It is what everyone gets when they don't ask for anything.

Six weeks ago, encoding your design rules into proprietary machinery was a job for massive companies. Today, the tooling is a plain text file. The excuse just expired. What Coke paid Adobe to build, you can now do in an afternoon with a text editor. 

The screens are getting made either way. The only question is whose taste is in them.

Tokens are the cheap half

A DESIGN.md file has two layers. 

The top is YAML. These are machine-readable tokens: hex values, type scale, and spacing. 

The bottom is prose. These are written rules: what the product should feel like, when to use which pattern, and what must never happen.

The token layer is mechanical. Any tool can scrape your site and find your colors. But if your guidelines are only tokens, an agent knows your values and none of your judgment. Judgment is where identity lives. 

The agent that knows your blue is #1B2A4A can still build a screen that looks like anyone else. The agent that has been told "this is enterprise security software, density over decoration, one accent per screen, no illustration near a compliance claim" produces screens that could only be yours. 

The dev world calls this documentation. It is actually governance. 

A brand book PDF is a request that a human might open. A repo file the agent reads before every generation is a rule. It gets enforced every single time without anyone having to police it. 

The so-what for founders

Open your repo. If there is a README but nothing describing how your product is supposed to look and feel, every AI-assisted screen your team ships is being art-directed by training data. 

The drift arrives one plausible component at a time. 

The fix takes a day. Pull your tokens into the YAML layer. Then write the prose layer like you are briefing a designer who can't ask follow-up questions. 

  1. What the product feels like in one sentence. 

  2. Five rules for choosing between patterns. 

  3. Five things that must never happen. 

If you can't write that page, the file isn't the problem. The positioning underneath it is. 

I build this layer as part of Guidelines now. A brand that can't brief an agent will spend 2027 being averaged. If your team is already shipping AI-generated screens and nobody has written the file, reply to this and I'll tell you what I'd put in yours.