Brand guidelines your engineers will actually open

Brand guidelines for developers are a short page with the files, the hex values, and the type settings. An engineer opens that page in the middle of a sprint, copies what they need, and goes back to the component. They will not open a mood film, a brand story, or a forty-page PDF to find out which blue the button uses.

If the page answers in under a minute, the interface stays in the family. If it does not, the interface gets a reasonable guess. Reasonable guesses are how a product grows a second palette.

What the engineer is doing when they look

They are usually blocked on a specific question. Which file is the logo on a dark navigation bar? What is the text color on the default background? Which weight is the page title? What do we do for an error? They have a pull request open. The guidelines are a reference, in the same way a language's docs are a reference.

Write for that moment. Lead with a table or a tight list, not with a paragraph about the founding story. The story can live somewhere else for the people who are choosing the brand. The people applying it need values they can paste.

Assume they are competent and new to this company. Define a term once if you must use it. "Accent" means the color of the primary action. "Support" means hairlines and secondary labels. Skip the essay on why you rejected a different accent. The decision is what belongs on this page.

The page they will actually open

Give them these pieces, in this order:

• Logo files, named for the job: on light, on dark, single color, favicon. SVG first.
• Color values: use name, hex, and where it is allowed. Text on background. Accent as a fill for the primary button. Support for borders.
• Type: family, the weights you ship, the sizes for title, heading, and body, and the line height you intend.
• Space: a small set of gaps, if you have one. Even three steps, labeled, beat a free-for-all.
• Radius and shadow, only if you use them. One radius is a decision. Five radii are a mood.
• A single "do not" line for the mistakes that keep happening: stretching the logo, setting body text in the headline face, inventing a new blue.

Put the page in the repository or one click from it. A link in the README titled "Brand values" is enough of a map. A ZIP attached to an old email is a different brand by the time the next hire arrives.

The Web Content Accessibility Guidelines are the standard to cite beside the values, on the same page, rather than in a separate sermon. WCAG organizes requirements under four principles: perceivable, operable, understandable, and robust. Record the text and background pairs you checked, and the logo treatments that still read, so the perceivable principle is a value on the page and not a hope. Write a focus color next to the other colors so a keyboard user can see where they are. Engineers will implement what is written on the page they already have open.

What to leave out of their page

Leave out the workshop photos, the rejected sketches, and the film of ink moving through water. Those pieces help a team feel the brand while they are deciding it. They slow a person who is naming a CSS variable.

Leave out principles that cannot be implemented. "Be human" does not compile. "Body text uses the text color, at the body size, on the background color" does. If a principle matters, translate it into one of those lines or keep it on the writing page, with the sentences the company is willing to say.

Leave out every social-media size you might someday need. Link a folder of exports if marketing needs them. The engineering page stays about the product and the site. A page that tries to be the whole brand department will be bookmarked by no one in engineering.

Version the page. A date at the top, and a one-line note when a hex changes, tells a developer whether their branch is stale. Silent edits produce bugs that look like taste.

From hex values to tokens

The moment more than one person is implementing the page, name the decisions. A token is a named value: color, size, radius. The engineer should meet the name on the guidelines page and the same name in the code. --color-text and --color-accent are enough to start. A novel naming scheme that requires a legend will be bypassed for raw hex in the file.

Drift starts when someone pastes a one-off value into a single screen because the token felt close but not right. Treat that paste as a request. Either the token changes, with the guidelines updated in the same work, or the screen uses the token you already have. Both outcomes are fine. A third outcome, a private hex that lives only in one component, is the second brand.

Document the few components that repeat: button, text field, page title, the quiet link. Show the default, the hover, the focus, the disabled state, and the error. A picture of the happy path leaves the other states to invention. You do not need a full library on day one. You need the components this product already repeats.

The sprint test

Before you call the page done, ask someone who did not write it to style a button and a page title from the page alone. Watch where they hesitate. Hesitation is a missing value, a missing file, or a sentence that sounds like taste instead of an instruction. Add the missing line. Cut the sentence.

Ask a second question: can they tell which logo file to use on the dark footer without opening the files? If the names are doing their job, yes. If they open three images to compare, rename the files.

Review the page when you add a real surface, such as email or a logged-in home, and when a contrast problem shows up in the browser. Keep the edit small. The promise of this page is that it stays openable during a sprint. A rewrite that turns it back into a brand book breaks the promise.

When you want those values built into the site rather than maintained by memory, Hanabi's services are scoped as design and production code together. The next step after a short hex page is naming the decisions so they stop drifting, which is the subject of Tokens, type, and the decisions that stop visual drift.