Create brand guidelines for your product

Brand book

Goal: one HTML page that shows the whole brand, works offline, follows the product's real tokens, and links every file a designer, a partner, or an image model needs. It is a living document. Each change is a new edition.

Related kits

This kit plans and assembles. These do the specialist parts. Install them when you reach that step.

• @slashclone/two-theme-brand-colors: find a mark or accent color that keeps contrast in both themes.
• @slashclone/palette-export: turn the tokens into a swatch sheet, JSON, CSS variables, and a GIMP palette for the Downloads chapter.
• @slashclone/seeded-image-crops: many covers and headers from a few owned hero images.
• @slashclone/canvas-frame-capture: check any animated or WebGL chapter when screenshots do not work.

Where things go

• brand/brand.json: the spec. Tokens, contrast pairs, type, voice rules, and the asset list. Start from examples/brand.json.
• brand/brand-book.html: the book. Start from templates/brand-book.html.
• brand/logo/, brand/icons/, brand/share/, brand/palette/: the downloads.
• public/brand/: copies the live site serves. Root files such as favicon.ico or a web manifest sit outside this kit's write scope, so ask before writing them.

Steps

1. Find the source of truth. Read the product's design tokens (a tokens file, a theme, a Tailwind config, or CSS variables). The book mirrors them. Never pick colors from screenshots. If two sources disagree, ask which wins.
2. Write brand/brand.json. Light and dark tokens with the same names, the text and mark pairs that must pass contrast (4.5 to 1 for text, 3 to 1 for marks and icons), the type faces, the voice words, the banned strings, and every asset you will ship with its pixel size.
3. Settle open choices first. For a mark or color still in question, make a small studio page that shows the options side by side in both themes and at real sizes. Record the decision and who made it, then retire the losers. Do not put rejected options in the book.

4. Build the chapters. Copy the template and fill it in. Keep chapters short, one idea each:

   • Foundation: mission in one sentence, the line people repeat, three to five principles with a do and a don't each.
   • Logo: the mark, the wordmark, and any lockups. Show real sizes down to the smallest allowed. Name the clear space unit (for example, the width of one stroke). Show misuse by applying the wrong thing to the real mark: stretch, rotate, recolor, add effects, a busy background. Put the mark inline with currentColor so the theme recolors it.
   • Color: every token in both themes, with its use and its contrast. Label which colors are for text and which are only for marks. Show the proportions if the brand has a balance (how much of a frame the accent covers).
   • Type: each face, its role, its sizes, and a live sample. Use fonts the project has the license to ship, served from the project.
   • Imagery: what pictures show, the light, the crop, and what never appears. Give a day and a dusk version of a scene when the product has two themes.
   • Share images: one renderer with a preset per size, so the pack always matches what the site serves. Common sizes: link preview 1200x630, code host preview 1280x640, square post 1080x1080, story 1080x1920, profile header 1500x500, page banner 1584x396, channel art 2560x1440. Note any area a platform covers, such as an avatar over a header.
   • Icons: a flat favicon SVG (fine detail turns to noise at 16 pixels), app icons at 192 and 512, a maskable 512 with the mark inside the central safe zone (about 14 percent padding per side), and a 180 touch icon.
   • Voice: tone words, sample lines at every length (button, error, headline, email), and copy rules. Start with: no em dashes; use a period, a comma, or a colon.
   • Downloads: every file, linked and named by use and size.
   • Sources and changes: which script makes each file, and a short log per edition. Code paths go here, not in captions.
5. Generate, do not hand-make. Write one script that renders the icons and marks from the tokens and the mark geometry, and one that exports the share pack from the running renderer into brand/share/ with a README table of file, size, and use. Rerun both after any token or mark change. A PNG needs no image library: Node's zlib.deflateSync, a CRC32, and the IHDR, IDAT, and IEND chunks are enough.
6. Make it self-contained. Inline CSS and JS, link images by relative path, no CDN scripts. Default to the reader's color scheme, add a theme toggle, and render swatches from the CSS variables so the book cannot drift from itself.
7. Check it: node scripts/check-brand.mjs --dir brand --out brand/check.json It confirms light and dark share token names, every contrast pair passes in both themes, every listed asset exists at its declared size, SVGs have a viewBox, and no copy file uses a banned string. Fix every failure before you call an edition done.
8. Look at it. Open the book in both themes and at phone width. Check the smallest logo size, the favicon in a real tab, and a share image in a link preview tool if one is at hand.
9. Ship an edition. Bump edition in brand.json, add a line to Sources and changes, regenerate the downloads, rerun the check, and copy what the site serves into public/brand/.

Rules

• Every color, size, and font in the book comes from the tokens or the generators. No hand-typed duplicates.
• Only use images, fonts, and marks the project owns or has the rights to. If an image's source is unknown, leave it out.
• Mark colors pass 3 to 1 on every background they sit on, in both themes. Text colors pass 4.5 to 1. Report the worst case.
• Keep secrets, private paths, and internal names out of the book. It is meant to be shared.
• Do not commit large generated files unless the project already does; say where they are instead.