A brand guidelines PDF is a beautiful, dead document. It tells a human what the brand looks like in prose and swatches, and then it sits in a shared drive while every team that needs a color re-eyedrops it from a screenshot and gets it slightly wrong. The single highest-leverage move a brand or visual designer can make in 2026 is to stop maintaining the PDF as the source of truth and start maintaining a machine-readable token file that the PDF, the Figma library, the codebase, and now the AI agents all read from. This lesson walks the real translation: from a thirty-page guidelines doc to a structured tokens.json with a primitive, semantic, and component layer, committed to an actual repo, with a one-page README a developer can use without asking you a single question. The artifact is not a course exercise. It is the file your design system runs on for the next three years.

Why the PDF Was Always Going to Lose

Walk into any company with a brand guidelines PDF and ask three people what the primary brand color is. You will frequently get three answers: the hex from the print spec, the hex someone eyedropped off the website last spring, and the hex a developer hardcoded because the PDF gave them a Pantone and they had to guess the screen equivalent. The PDF is not wrong, exactly. It is just not a source anything can read. It is a description of the brand, formatted for a human eye, and the moment that description has to become a value in a stylesheet or a Figma variable, a human re-types it, and humans re-type things slightly wrong.

The token file solves this by making the brand a set of named values that every consumer reads from the same place. When the color lives in tokens.json as color.brand.primary with a value of #0B5FFF, the website reads that value, the Figma library reads that value through Figma Variables, the component library reads it, and an AI agent generating a prototype reads it. There is exactly one place the color is defined and exactly one value it can be. Drift stops being a thing that happens, because there is nothing left to re-type. The PDF can still exist as a narrative artifact for the marketing team and the brand story, but it stops being the thing engineering builds from. The token file is.

This matters more in 2026 than it did even two years ago, because the number of things reading your brand has multiplied. It used to be just developers. Now it is developers, Figma through Variables, Storybook through the MCP server, and a growing population of AI agents that will happily generate a screen using your brand color if they can read it and will hallucinate a plausible blue if they cannot. A token file is how you make your brand legible to the machines that now do a real share of the production work. The alternative is watching an agent ship something in #0066FF because that is the blue it averaged from its training data, and yours was never written down anywhere it could find.

The Three-Layer Architecture: Primitive, Semantic, Component

The single most common mistake in a first token file is flatness: one giant list of colors named after what they look like. blue, dark-blue, light-blue-2. This is the token equivalent of naming your Figma layers "Rectangle 47." It works until the brand changes, and then you are find-and-replacing a hundred references because the name described the appearance instead of the role. The fix, which every mature design system converges on, is three layers, each referencing the one below it.

Layer One: Primitives (The Raw Palette)

Primitives are the raw, context-free values. This is the full ramp of every color the brand owns, the complete type scale, the spacing scale, the radius scale. They are named by what they are, not what they do: color.blue.500, color.blue.600, space.4, font.size.300. A primitive never gets used directly in a component. It is the paint on the shelf, not the paint on the wall. The discipline here is completeness and neutrality: capture every value the guidelines define, name it by its objective properties, and resist the urge to assign meaning. color.red.500 is just a red. It is not "error" yet. That decision belongs to the next layer.

Layer Two: Semantics (The Brand's Decisions)

Semantic tokens are where the brand's actual decisions live, and they are the layer that makes the whole system worth building. A semantic token references a primitive and gives it a role: color.text.primary references color.gray.900, color.action.primary references color.blue.500, color.feedback.error references color.red.500. The name describes the job, not the appearance. This is the layer a component should consume, because it is the layer that survives a rebrand. When the brand changes its primary from blue to teal, you re-point color.action.primary from color.blue.500 to color.teal.500 in one place, and every button, link, and focus ring that referenced the semantic token updates at once. Nothing referenced the raw blue, so nothing has to be hunted down. This indirection is the entire point of tokens, and a file without it is just a color list with extra steps.

Layer Three: Component Tokens (The Last Mile)

Component tokens are optional but powerful: they bind a semantic token to a specific component property. button.primary.background references color.action.primary; card.border.color references color.border.default. You reach for this layer when a component needs to vary independently of the semantic it usually follows, or when you want the component's contract to be explicit and self-documenting for an AI agent reading the file. Not every system needs a full component layer on day one, and over-building it early creates maintenance you do not need. The honest rule: start with primitive and semantic, add component tokens only where a real component needs to break from the default, and let the layer grow with demonstrated need rather than speculation.

Reading the PDF With AI as an Extractor, Not an Author

Here is where AI earns its place in this workflow, and where it is tempting to let it overstep. The guidelines PDF is thirty pages of prose, tables, and swatches, and pulling every hex, every type size, every spacing value out by hand is exactly the kind of tedious, error-prone extraction a model does well and you do badly. So you use it: feed the PDF to Claude with a structured prompt that asks it to extract every color with its name and value, every type style with its size and weight and line height, and every named spacing or radius value, and to return them as a flat list grouped by category. This is genuine acceleration. A task that takes ninety minutes of squinting takes ten.

The trap is letting the model do the architecture. The model will, if you let it, cheerfully invent the semantic layer for you, deciding that color.blue.500 should be "primary" and color.gray.600 should be "secondary text." It is guessing, based on conventions in its training data, and it does not know your brand's intent. Maybe your primary action color is deliberately the teal, not the blue, because the blue is reserved for informational states. The model cannot know that, because that decision lives in your head and the brand strategist's head and nowhere in the PDF. So the division of labor is strict: the model extracts the primitives, which are objective and tedious, and you author the semantics, which are decisions and judgment. Let it pull the paint off the shelf; you decide what goes on the wall.

The model extracts the primitives because they are tedious and objective. You author the semantics because they are decisions and judgment. The brand's intent lives in your head, not in the PDF, so the model cannot read it - and the day you let it guess, you have shipped its average instead of your brand.

The DTCG Shape of a Token, Without the Full Spec Yet

The next lesson goes deep on the W3C Design Tokens Community Group format and its governance. For now you need just enough of the shape to write a file that is on the right path rather than one you will have to rewrite. The DTCG format gives each token two reserved keys: $value for the value and $type for what kind of token it is. A color token looks like this in shape: a name, a $value of the hex, and a $type of "color". Groups nest by object structure, so color.brand.primary is the primary token inside the brand group inside the color group. And references between tokens use a curly-brace alias: a semantic token's $value can be "{color.blue.500}", which resolves to whatever that primitive holds.

That alias syntax is the mechanism that makes the three-layer architecture real in the file. Your primitive color.blue.500 holds a literal hex. Your semantic color.action.primary holds the alias "{color.blue.500}". Your component button.primary.background holds the alias "{color.action.primary}". A tool resolving the chain follows it down to the hex, and a rebrand at the primitive level flows all the way up. Writing your tokens in this shape from the start means the file is immediately consumable by the broad ecosystem of DTCG-aware tools - Style Dictionary, Tokens Studio, the Figma Variables import path, and the validators you will meet next lesson - instead of being a bespoke JSON shape only your team understands.

A Worked Translation: Three Pages of PDF to Three Tokens

Make this concrete. Your guidelines PDF says, in prose: "Our primary brand color is Horizon Blue, used for primary actions and links. Body text is set in near-black for maximum legibility. Error and destructive states use Signal Red." It gives you the hexes in a table: Horizon Blue #0B5FFF, Near Black #111317, Signal Red #D7263D. Three sentences and a table. Here is how that becomes structured tokens across the three layers.

In the primitive layer, you record the raw values neutrally, as part of their full ramps: color.blue.500 holds #0B5FFF, color.gray.950 holds #111317, color.red.500 holds #D7263D. No meaning yet, just the paint. In the semantic layer, you encode the decisions the prose described: color.action.primary aliases {color.blue.500}, color.text.primary aliases {color.gray.950}, color.feedback.error aliases {color.red.500}. Notice the PDF told you the roles in plain English - "primary actions," "body text," "error states" - and your job was to turn those English roles into named semantic tokens. In the component layer, if your button component needs it, button.primary.background aliases {color.action.primary}. Three sentences of prose became a small, legible chain that any tool or agent can resolve, and that survives the day Horizon Blue becomes Horizon Teal.

Run this across the whole document and you have your file. The colors become the color group, the type styles become a typography group with $type of "typography" or broken into fontSize, fontWeight, and lineHeight primitives, the spacing scale becomes a dimension group, and the radii become another. The PDF's narrative chapters - "Color," "Typography," "Spacing and Layout" - map almost one to one onto your token groups, which is a useful tell that you are structuring it sensibly. If your token groups do not roughly mirror the chapters a brand designer would recognize, you have probably either invented structure the brand does not have or flattened structure it does.

Committing It to a Real Repo

A token file in your Downloads folder is a draft. A token file in a repo is a source of truth. The difference is not ceremony; it is that a repo gives the file the three things that make it trustworthy: version history, so every change to the brand is a reviewable commit with an author and a date; a single canonical URL, so there is one place the website CI, the Figma sync, and the agents all point at; and pull-request review, so a change to color.action.primary goes through a human before it ships to every surface that consumes it. This is the moment the brand stops being a document and becomes infrastructure.

The practical setup is modest. Create a repository - design-tokens is a fine name - put tokens.json at its root, write the README, and commit. If you have never opened a terminal, this is a completely legitimate place to pair with an engineer or to use a desktop Git client; the point is not to prove you can use the command line, it is to get the file under version control where it belongs. Once it is there, the workflows that matter become possible: a CI step that validates the file on every change (next lesson), a sync that pushes the tokens into Figma Variables, and a build step that transforms the tokens into CSS custom properties or platform-specific formats with a tool like Style Dictionary. None of those can hang off a file in your Downloads. All of them hang naturally off a file in a repo.

The README a Developer Can Actually Use

The token file is half the artifact. The other half is a one-page README that turns the file from "some JSON Sarah committed" into something a developer who has never met you can pick up and use correctly. A good token README is short and answers exactly the questions a consumer has, in the order they have them. It is the difference between a file people trust and a file people work around because they could not figure out how it was meant to be used.

The README should cover, briefly: what this is (the single source of truth for the brand's visual values; do not hardcode colors, use these tokens); the three layers and the one rule (consume semantic and component tokens, never reference a primitive directly in a product, because primitives can change); how to read a token (the alias syntax, so a developer understands that {color.blue.500} is a reference to be resolved, not a literal); how to consume it (the build command or import path that turns the tokens into whatever the developer's platform needs); how to propose a change (open a PR, who reviews it, that a change to a semantic token affects every surface); and who owns it (your name, so questions have an address). That is one page. It is the difference between a token system and a token file nobody adopted.

Write the README for the developer who arrives on the team a year from now, when you are not in the room. If that person can read it once and correctly use a token without messaging anyone, the artifact is done. If they have to ask "wait, which blue do I use," the README failed and the system will quietly fragment back into eyedropped hexes, which is exactly the disease the token file was supposed to cure.

What You Shipped, and Why It Is Senior Work

Step back and look at what this artifact actually is. You took a brand that lived as prose in a PDF and made it a structured, versioned, machine-readable source of truth with a clean three-layer architecture, committed to a repo, documented well enough that a stranger can consume it correctly. That is not a visual-design deliverable in the old sense. It is design infrastructure, and it is precisely the kind of leverage-positive work that separates a senior IC from a designer who ships beautiful frames that drift the moment they leave Figma.

It is also the foundation everything in this chapter builds on. The DTCG governance you will design next lesson governs this file. The three brand variants you will generate come from this file. The Storybook connection that lets agents read your system reads these tokens. The drift audit that catches off-system color hunts for values that should have been in this file and were not. You did not just make a tokens file. You made the spine of a brand-system-as-code, and you did it with AI doing the tedious extraction and you doing the judgment, which is the exact division of labor the rest of this program is teaching you to run on everything.

Key Takeaways

• A brand guidelines PDF is a human-readable description, not a machine-readable source. Every team that re-types a hex from it introduces drift. A tokens.json file makes the brand a set of named values that the website, Figma, Storybook, and AI agents all read from one place, so there is nothing left to re-type wrong.
• Use the three-layer architecture: primitives (raw, context-free values named by what they are), semantics (roles that reference primitives and survive a rebrand), and component tokens (the optional last mile that binds a semantic to a specific component property). Components consume semantic tokens, never primitives directly.
• Let AI extract the primitives - pulling every hex, type size, and spacing value out of the PDF is tedious and objective, exactly the model's strength. Author the semantic layer yourself, because the brand's intent (which blue is "primary action") lives in your head, not in the PDF, and the model can only guess its average.
• Write tokens in DTCG shape from the start: $value and $type keys, groups by object nesting, and curly-brace aliases like {color.blue.500} for references. This makes the file immediately consumable by Style Dictionary, Tokens Studio, Figma Variables, and the validators you meet next.
• Commit the file to a real repo, not a Downloads folder. The repo gives it version history, one canonical URL, and pull-request review - turning the brand from a document into infrastructure that CI, Figma sync, and build steps can hang off.
• The README is half the artifact. One page covering what it is, the three layers and the consume-semantic rule, the alias syntax, how to build it, how to propose a change, and who owns it - written for the stranger who joins the team a year from now and must use a token correctly without asking anyone.