Step 3 of 4. The input is the rough draft from brandkit-interview, the output is
a folder you can actually work with.
The actual problem
Almost every style guide fails not because of its content, but because of its length. Nobody reads nine hundred lines, not even a language model with a context window: it reads them, but weights the twentieth rule the same as the first and then still makes average decisions.
A kit works when three things are right:
- The binding rules are short enough that they are actually read.
- Colors and dimensions are executable , not just described.
- The rules apply by themselves, without anyone having to think about them.
Point 3 is the one everyone forgets. It is a CLAUDE.md in the folder.
What is created
Brand/
├── CLAUDE.md Arbeitsregeln, greifen automatisch in diesem Ordner
├── BRAND.md die verbindliche Kurzfassung, das Herzstück
├── REFERENCE.md die Rohfassung aus dem Interview, als Nachschlagewerk
├── README.md was wo liegt, plus Starter-Satz für außerhalb
├── brand-helmet.html Farb- und Schrift-Tokens als fertiger CSS-Block
├── brand-props.json Akzentfarbe im Design-Editor umschaltbar
├── wordmark.svg Schriftzug, Standardfall
├── mark.svg quadratische Bildmarke für kleine Flächen
└── beispiel/ lauffähige Referenz mit allen Bausteinen
Create the folder where it will stay permanently, and make it a Git repository. A brand kit without version history gets lost.
BRAND.md, the short version
This is the most important file. Target size: under 250 lines. If it gets longer,
material moves to REFERENCE.md.
Proven structure:
- Brand in one sentence plus personality in one line
- Tokens as a table: variable name, hex value, role. Plus the surface distribution in percent
- Typography: the two to three roles and a size scale per format
- Grid and spacing: number series, margins, radii, borders, shadows
- Wordmark: which file when, minimum size, clear space, prohibitions
- Building blocks: the recurring elements with concrete dimensions
- Formats: pixel dimensions per purpose
- Text: language, address, one good and one bad example, the prohibitions list
- Do not use: the hard prohibitions list, visual
- Checklist before handing off: ten questions that can be answered with yes or no
Two things make the difference between a kit that works and one that decorates:
Percentages instead of adjectives. "Use the accent color sparingly" is not verifiable. "Accent color under 10 percent of the surface, never as a section background, never as a gradient" is.
Concrete dimensions instead of principles. "Generous spacing" helps no one. "Section spacing 96 to 128 pixels on desktop, 56 to 72 on mobile" does.
Write the prohibitions lists in detail. They are the part that prevents average, and they are cheap to follow.
CLAUDE.md, the mechanism
Without this file, someone has to mention the kit manually in every session. With it, the rules apply as soon as work is done in the folder.
It is short and only governs how to handle the other files:
which file wins in case of conflict, that only defined tokens are used,
where the reference examples are located, and that changes to the kit itself must first
be agreed upon. A template is in assets/CLAUDE.md.template.
For work outside the folder, a starter sentence belongs in the README, which is copied to the beginning of a session, for example:
Lies zuerst <PFAD>\BRAND.md und halte dich exakt daran.
Referenz-Artboards: <PFAD>\beispiel\
The kit does not load itself. State that explicitly in the README, otherwise the person will be surprised the first time.
The executable parts
brand-helmet.html contains the Google Fonts link and a :rootblock with
all tokens as CSS variables, plus base styles and one or two
utility classes for recurring roles (for example .lbl for technical labels,
.val for numbers in mono). Template: assets/brand-helmet.html.template.
The point: after that, the layout contains only var(--...), no raw hex values.
A color change is then one line instead of a search across all files.
brand-props.json makes the accent color switchable in design editors. Be careful with the options: if you offer functional colors there (warning, error), someone can set the brand accent to the error color, and positive and negative collapse together. Either offer only brand colors, or explicitly write in BRAND.md that the switch is an inspection tool and not a second brand accent.
wordmark.svg and mark.svg you build from the wordmark, not from symbols. Do without robots, brains, circuit boards, and gradient spheres, unless the brand explicitly requires them.
A pitfall that hurts later: an SVG with <text> needs the font on
the displaying device. In the browser with a loaded Google Font that is true, in
print or in Illustrator the fallback font takes over. Write in the README that
the wordmark must be converted to paths as soon as it leaves the browser.
beispiel/, the reference
Build at least two runnable example surfaces that show all building blocks in the right dimensions, typically desktop and mobile. This is the part that takes the most work and saves the most: next time it gets copied instead of reinvented.
Clearly mark example data as such. Invented numbers from a reference artboard otherwise end up on a real page.
Condense, do not shorten
On the way from the raw draft to BRAND.md, the following applies:
- Keep every number, every hex value, every dimension, every prohibition list.
- Strike rationales, derivations, repetitions, and everything that appears twice. It is preserved in REFERENCE.md.
- Convert prose into tables. "The main heading is 52 pixels large and is set in the display font" becomes a table row.
What remained open in the raw draft remains open here too. Write down that it is open. Do not invent a plausible value to fill a gap: it will otherwise be treated like a decision that no one ever made.
Finally
Go through the checklist you just wrote once against the reference artboards. If your own example does not pass your own checklist, one of the two is wrong.
Then report briefly: what was created, where it is, how long BRAND.md has become, and what is still open. Refer to brandkit-publish for building with the kit.