brand-guide-kit: how I check that a brand arrives intact to whoever uses it

A good-looking brand guide proves nothing. The guide says which logo to use, which colors and which typeface; the files that circulate afterwards can say something else, and nobody compares them. The PDF gets approved once. The files change every time someone touches them.

brand-guide-kit is what I put together for that. It is the second of the two repos the agency keeps open on GitHub. In the public repos post it got one section. Here is the whole thing: what it produces, the rules it uses to say «this is ready», how to run it, what a result looks like and what it still cannot check.

The problem it solves

A brand passes through many hands: designers, print shops, whoever builds the website. The problem is almost never the guide. It goes like this: someone exports the logo again from an old file, someone puts a «close enough» color in the CSS, someone uses a typeface that was never approved. Each change is small and nobody sees it until it is already printed or published.

The product brief in the repo says it in one line: guide pages can disagree with the actual assets. The kit's promise is to put evidence where there used to be trust: which file is the approved one, how you check it and what could not be checked. I created it on October 19, and on the 20th I chose the MIT license so anyone can use it.

What it produces

The kit does not make logos. It produces documents and a review of files:

Everything is Markdown and Python with no external dependencies. There is no service, no account and nothing that updates itself.

The 9 gates before a handoff

The heart of the kit is docs/brand-system-standard.md: nine gates a brand has to pass before you call it ready. I wrote them drawing principles from the public guides of five large brands (Dropbox, IBM, Atlassian, Spotify and Slack), but the criteria are ours and the file says so: their measurements, colors and icons are not copied.

Every gate ends in one of three words. VERIFIED: I checked it and here is the evidence. MISSING: it is absent, and this is how I looked. UNKNOWN: not checked yet. The third one matters most: an approval nobody confirmed stays UNKNOWN, it is not assumed.

The contract: brand.json

For the part a script can check, each brand carries a brand.json file next to its assets. This is the one for the test brand that ships with the repo, made up on purpose:

{
  "schema_version": 1,
  "name": "Sample Frame (fictional test fixture)",
  "colors": { "accent": "#F5C518", "ink": "#0A0A0A" },
  "assets": [
    {
      "path": "mark.svg",
      "approval": "approved",
      "sha256": "bd607e14873f6170e6dd4fb22ae52348c77908ee9ee32db6b84bc9a9dadba62b",
      "expected_fills": ["#F5C518", "#0A0A0A"]
    }
  ],
  "css_files": ["site.css"]
}

What it declares: two colors, one logo (mark.svg) marked as approved, its SHA-256 fingerprint (a number that changes if a single byte of the file changes), the two fill colors that SVG must have and the stylesheet checked against the palette. You declare the approval; the script cannot prove it, and the documentation says so.

How to run it

You only need Python 3. From the repo folder:

1. Clone the repo: git clone https://github.com/svdiginet/brand-guide-kit ~/brand-guide-kit.
2. Audit the test brand: python3 scripts/brand.py audit demos/sample-brand/brand.json. If you will use it in an automation, add --json.
3. Run the tests: python3 -m unittest discover -s tests.
4. For your brand, copy that brand.jsoninto your assets folder, change the name, colors and paths, and compute your logo's fingerprint with shasum -a 256 your-logo.svg. That file does not go inside the public repo.
5. When everything passes, export the approved SVGs to a new folder: python3 scripts/brand.py export path/brand.json new-folder. It copies the original bytes; if the folder already exists, it refuses.

What a result looks like

This is how the test brand came out on October 22:

VERIFIED: mark.svg: File exists
VERIFIED: mark.svg: SHA256 matches declared baseline
VERIFIED: mark.svg: Explicit fill attributes match
VERIFIED: site.css: Hex literals use declared palette (not a computed-style audit)
UNKNOWN: visual: No visual fidelity, small-size, contrast, 3D or physical production certification
exit=2

Ran 14 tests in 0.150s

OK

Four verified lines and one that is not. The last one always shows up: a script cannot tell you whether the logo looks right at 16 pixels, whether the contrast holds or how it comes out on fabric. That is why the exit code is 2 and not 0. The codes are written in docs/brand-contract.md: 0 if nothing is pending, 1 if something is missing or does not match, 2 if only unchecked items remain, 3 if the contract or the path is wrong.

A detail I noticed reading the code: the visual line is always added, so an audit never returns 0. The best you can get is a 2. If you put it in an automation, you have to accept 2 on purpose and fail on 1 or 3, not hide the error.

What happens when something changes? The repo's tests cover it. This table comes from tests/test_brand.pyand the auditor's rules:

What it does not do, and the README says so: it does not compare images, compute a page's final style, check accessibility, generate logos, prove trademark clearance or replace a printed proof.

With Claude Code or Codex

The skill is the same for both tools. You install it with two symbolic links to the repo folder, as the README says. If the skill folder already exists in either place, check it first: do not overwrite an installation you already have.

mkdir -p ~/.claude/skills ~/.codex/skills
ln -s ~/brand-guide-kit/skills/brand-guide-kit ~/.claude/skills/brand-guide-kit
ln -s ~/brand-guide-kit/skills/brand-guide-kit ~/.codex/skills/brand-guide-kit

With that, when you ask the agent to review or build a guide, it follows a fixed order: first it reviews what already exists and marks each finding VERIFIED, MISSING or UNKNOWN; then it proposes small changes; it does not alter a logo to make it easier to trace; and it does not publish or change a live brand without your permission. If a reference is missing, it asks instead of inventing it.

That last rule matters most to me. An agent without written rules fills the gaps with what it thinks it remembers. With the skill, the gap stays UNKNOWN and it tells you.

Who it is for, and who it is not

It works for agencies, independent designers and teams that hand a brand to someone else and need it to arrive intact. Also for anyone using an AI agent to make brand pieces who wants it to check against written rules.

It is not for you if you want a logo generator, a platform with user accounts or a stamp that says «brand approved». The kit certifies nothing. It tells you what is checked, what is missing and what nobody has reviewed yet.

What I do not know yet

• How it behaves with a real published brand. The roadmap keeps that item open: document an approved, rights-cleared example before advertising production results. That is why you only see the test brand here.
• Whether image comparison and computed-style checks are worth adding. The roadmap leaves them out of version 0.2 on purpose.
• How many people use it. It has one star as of October 22 and I have no other metric.

If you try it on your brand and something does not add up, open an issue on the repo. No brand data: describe the case and the auditor's message.

github.com/svdiginet/brand-guide-kit →

Read also: SVDIGINET's two public repos and what I check before opening one.

If you want this in your business

brand-guide-kit comes out of the work at SVDIGINET, my local marketing agency in Central Florida: Google profiles, reviews, websites and automations for local businesses. If you would rather have us review your brand, the details are at svdiginet.com.

Sources: github.com/svdiginet/brand-guide-kit, read Oct 22, 2026; docs/brand-system-standard.md; docs/brand-contract.md