The 60-page brand guide PDF is a relic of a print-era brand practice. It made sense when brands existed primarily on television, billboards, and magazine inserts, and a single reference document had to live on a shelf for five years. It stopped making sense about a decade ago, when brands started living on websites and ads and apps that change every month. Nobody updated the memo.
I have watched three DTC teams in the last year spend $30-80K on a polished PDF brand guide that nobody on their team had opened in six months. The guide was approved, PDF'd, and filed. Meanwhile the actual brand was drifting in Shopify, Klaviyo, and the Meta ad library, because the people shipping on those surfaces did not read PDFs.
The fix is a living doc. Two pages. In the repo. Linked from every relevant surface. Here is the version I ship.
Why the PDF fails
Three reasons.
Reason one: PDFs decay. The moment a brand guide PDF is signed off, it starts rotting. The logo updates, the color shifts, a new type style gets added, a guideline gets amended. The PDF does not update because it is not in anyone's daily workflow. By quarter's end, the PDF disagrees with the actual shipped brand on roughly a dozen points.
Reason two: PDFs are unsearchable in practice. A marketer trying to find "how do we format our sale banner" in a 60-page PDF has to scroll through a table of contents, open a section, and scan. In a markdown file in the repo, they cmd+F for "sale banner" and find the rule in three seconds.
Reason three: PDFs accept no corrections. When the engineer ships a new component variant or the designer updates a spacing rule, there is no version-controlled way to update the PDF. Eventually someone opens InDesign, finds the file, makes the change, re-exports. That person does not exist at most small teams. The change does not happen.
What a living doc looks like
Two pages of markdown in the repo at docs/brand.md. That is the entire brand guide.
Page one covers the three things a collaborator needs in the first fifteen seconds: the name, the logo set, and the color tokens. Every other decision is a link to code.
# Acme brand
## Name
Acme. One word. Capitalized. Never "ACME" or "acme" or "Acme Inc" except in legal contexts.
## Logo
Four marks in `/brand-assets/`:
- primary/lockup-horizontal.svg
- secondary/lockup-vertical.svg
- wordmark/wordmark.svg
- bug/bug.svg
Use the horizontal on wide contexts, vertical on narrow, wordmark on
email, bug on app icons and social avatars.
## Color
See `src/app/globals.css` for the token file. Primary: --signal.
Never use raw hex in code or Figma; always reference the token.
Page two covers the operational decisions: type scale, voice rules, component index, and whom to ask when something is unclear.
## Typography
Six-step scale in `src/app/globals.css` from --t-display to --t-small.
Hero uses --t-display with clamp; all others fixed.
## Voice
- Practitioner, not columnist. Ship claims, not theory.
- No em dashes. Use periods, commas, colons, or hyphens with spaces.
- Claim-only stats; flag anything uncertain.
- See `docs/voice.md` for the full set.
## Components
See `docs/components/README.md` for the component index.
## When in doubt
Ask Michael. Issues welcome at [repo].
Total length: about 60 lines of markdown. About 2 pages of rendered reading. Under 10 minutes of skim time for a new collaborator.
What moves from the PDF
The PDF content either migrates to code or gets deleted. Here is how each section translates.
Logo usage rules. Moved to the brand-assets folder README. "Use the horizontal on wide contexts" is a one-line rule. The five-page examples of "correct and incorrect logo usage" from the PDF are deleted; the team shows the correct use on live pages, not in an asset library.
Color palette. Moved to the token file in code. The PDF version had a dozen swatches with hex values. The code version is the source of truth with comments explaining which tokens are for body, headings, backgrounds, and accents.
Typography. Moved to the token file and to the typography-scale article in the writing section (or to docs/type.md). The specific rules ("body is 16px, line-height 1.5") are one line each.
Voice and tone. Moved to docs/voice.md. This is the biggest survivor from the PDF because voice rules do not change often and are genuinely useful reference material. The PDF version was usually 10-15 pages. The living-doc version is 2-3 pages because we delete the aspirational framing and keep the operative rules.
Component usage. Moved to the component index in docs/components/README.md. The PDF version was aspirational ("here is how the card might look"). The code version is real ("here are the four card variants, here are real production pages using each").
Brand story. Deleted or moved to an "about" page on the site. Nobody needs the founding narrative in their brand implementation reference.
What earns its own longer doc
Three things are long enough to earn their own file, not a section in the main brand doc.
Voice doc. A 2-3 page standalone file. This is the document writers reference when producing copy, and it is the most-referenced doc on my practice's actual workflow. I link to it from the brand doc but keep it separate.
Component index. One line per component with a link to each component's README. Easily searchable, browsable, and kept fresh by the commit log.
Token file. In code. The token file comments are the documentation for the color, type, spacing, and motion decisions.
Everything else fits in two pages or is deleted.
The review rhythm
A living doc stays alive by being updated. A PDF dies by being final. The review rhythm for a living doc is cheap: every quarterly design review, I open docs/brand.md and ask "does anything in here disagree with what we ship now?" If yes, update. If no, move on.
The review takes about ten minutes, because two pages of content are fast to scan. Compared to a PDF audit (which is usually a two-day project and gets deferred indefinitely), the maintenance burden is an order of magnitude smaller. That is why the doc actually stays current.
“A doc that updates with the code updates honestly. A doc that requires a separate cycle to update drifts the moment the code moves.
”
The client conversation
The question I get from clients the first time I propose this is "but we need a polished brand guide to hand to agencies and partners." My answer has evolved.
Early on I built the polished PDF as a second artifact, which defeated the point. Now I hand agencies and partners the markdown file and the link to the token code. Most of them prefer it. Engineers obviously. Designers, once they see the token file, stop wanting a PDF because the token file has the actual source of truth.
The rare case where a polished document is genuinely needed is for legal or trademark documentation (registering a trademark requires a static PDF of the mark usage, for instance). I produce the PDF for that specific purpose from the same source (the markdown and the token file) using Reportlab or Pandoc, and it takes an afternoon. The PDF is a rendered artifact of the living doc, not a separate truth.
On the brand asset hub engagement I worked on last year (see the brand asset hub case), the printed brand artifacts were auto-generated from the same tokens and markdown files the website consumed. Brand coherence came from the single source, not from a printed reference.
Frequently asked questions
What about external brand agencies who expect a PDF?
Give them the markdown file and the token-file link. If they insist on a PDF, render one from the markdown via Pandoc in about 20 minutes. The rendered PDF will be accurate because it comes from the live source. You never maintain a separate PDF.
Is this approach appropriate for a Fortune 500 brand?
The principle (documentation in the same workflow as the work) holds at any scale. The implementation gets more formalized: larger brands need Git-based review workflows, code owners per section, and automated linting against the rules. But the core idea of killing the standalone PDF in favor of a living repo-based doc is right at all scales.
How do you onboard a non-technical marketer to a markdown doc?
Host it as a rendered page on a staff wiki or internal website (GitHub Pages, Notion, Confluence, or a small Next.js page). The marketer reads the rendered version. Edits can be filed as issues or pull requests with screenshots, or a technical ally accepts the proposal and commits it. The markdown source lives in the repo; the reading experience is wherever is comfortable.
What if the rules differ for different markets or sub-brands?
Split the doc. docs/brand.md covers shared rules; docs/brand-us.md or docs/brand-acme-recovery.md covers the variants. Keep the variants short and reference the shared doc for everything that does not differ. Same markdown, same workflow.
How do I convince leadership this is not a downgrade from a "real" brand guide?
Two arguments. First, a PDF nobody updates is not a real brand guide; it is an expensive screenshot. Second, the cost of building the living doc is a fraction of the PDF (I usually propose $2-5K vs $30-80K for equivalent content), and the resulting doc is actually accurate six months later. The math is straightforward.
Sources and specifics
- Pattern running on this site and on four DTC brand builds across 2024-2026, including the brand asset hub engagement where the same pattern served a 5-person marketing team.
- The "$50K PDF, 17 points of disagreement in 9 months" is from an audit I ran on a DTC wellness client in Q4 2024; the specific count varies by brand but the shape (10-20 points of drift within a year) is consistent across the three PDF audits I have run.
- The $2-5K vs $30-80K cost comparison reflects my own pricing for living-doc builds vs. quoted pricing I have seen from agencies for polished PDF brand guides.
- See also: the brand architecture hub, design tokens that survive a rebrand, and component library handoff when designer also codes.
- Full productized methodology is the Operator's Stack.