By Mehdi HassanWhat are brand design tokens?
Brand design tokens are the smallest named decisions of your visual identity, stored as data. Instead of a guideline saying 'use our blue', a token says color-action is a specific value, and every button in Figma and every button in code points at that name. Change the token, and every place that uses it updates.
Tokens are the bridge most brand projects skip. A brand book defines who you are and what your colors are; it rarely settles which color a hover state uses or how large a section heading is on mobile. That gap is where brands drift once a website and product are built. Tokens start from the decisions in your color framework, covered in our guide on how to choose brand colors, and make them executable.
For the general theory of token types beyond branding, see our explainer on design tokens: primitive, semantic and component. This piece focuses on the brand side: getting colors and type out of a guideline and into a working Next.js site.
Why turn brand colors and fonts into design tokens at all?
Because a brand that exists only in a PDF gets reinterpreted by every person who builds with it. One developer picks a slightly different hex value, another uses a different gray for body text, a third sets headings a size larger. None of it is a big mistake, and together it makes the brand look off.
- Consistency without policing. The right value is the easiest one to use, so people use it.
- Faster changes. A palette refresh becomes an edit to a handful of primitives instead of a search through hundreds of files.
- Theming. Dark mode, a high-contrast mode or a sub-brand becomes a second set of values for the same semantic names.
- Shared language. Designers and developers talk about text-muted or surface-raised, not 'that grayish one'.
This is the part of branding where being a team that writes, designs and codes matters most. When the person defining the palette also defines the token names and the Tailwind theme, nothing gets lost in translation.
How do you structure color tokens in three layers?
Structure color tokens in three layers: primitives hold the raw palette, semantic tokens assign roles, and component tokens handle the rare exceptions. Most of your codebase should only ever touch the semantic layer.
Layer | Example names | What it holds | Who uses it |
|---|---|---|---|
Primitives | blue-50 to blue-950, sand-100, gray-900 | Every swatch in the palette, as raw values | Only the semantic layer |
Semantic | color-action, color-text, color-text-muted, color-surface, color-border, color-danger | Roles mapped to primitives | Designers and developers, everywhere |
Component | button-primary-bg, chart-series-1, nav-link-active | Exceptions for specific components | Component code only |
The palette structure from your brand guidelines, primary, secondary, accent and neutrals, maps to primitives; our explainer on brand color palette structure covers that step. Semantic naming is where accessibility gets locked in: if color-text on color-surface passes contrast, every component built with them passes too. Our guide to accessible brand colors shows how to pick those pairings.
How do you turn brand fonts into typography tokens?
Typography tokens bundle font family, size, line height, weight and letter spacing into named text styles such as display-xl, heading-md, body and label-sm. Defining whole styles, rather than separate size and weight values, prevents mismatched combinations like a heading size with body line height.
Set the families as tokens
Create font-display, font-text and, if needed, font-mono, each with the brand font and a sized fallback. Swapping a typeface later then means changing one value.
Define a type scale
Choose a limited set of sizes for display, headings, body and labels. Fewer steps make pages look calmer and make choices obvious.
Bundle each step into a style
Pair every size with its line height, weight and tracking. Large display styles usually want tighter tracking and line height than body text.
Make it responsive
Decide how display and heading styles scale between mobile and desktop, either with breakpoints or fluid sizing, and record it in the token.
Mirror it in Figma
Create matching Figma text styles and variables with the same names, so a designer's heading-md and a developer's heading-md are the same thing.
Before you tokenize type, the font choices themselves need to be settled. Our guides on how to choose brand fonts and font pairing cover that decision, and font licensing covers the rights you need to ship them.
How do brand tokens work in Tailwind and Next.js?
In Tailwind CSS v4, theme values are defined in CSS with the @theme directive, and each one becomes a CSS custom property and a set of utility classes. That makes Tailwind a natural home for brand tokens: primitives and semantic roles become variables, and classes like bg-action or text-muted follow automatically.
A practical setup looks like this. Primitives are declared as color variables in the theme. Semantic tokens reference those primitives, and a dark-mode block redefines only the semantic layer. Typography tokens become font families and text sizes with paired line heights. In Next.js, fonts load through next/font and expose a CSS variable, which the font-display and font-text tokens point at.
The rule that keeps it clean: components never use primitives or raw hex values. A code review that bans raw values in components is the cheapest brand-consistency tool you'll ever have. MDN's guide to using CSS custom properties explains the browser mechanism underneath.
Hypothetical example: tokenizing a brand refresh for a B2B SaaS site
For example, suppose a B2B SaaS company refreshes its brand: a deeper primary, a new warm accent, a serif display face and Inter for UI. The old site has dozens of hard-coded hex values and three slightly different body grays.
The team defines primitives for the new palette, then a semantic layer: color-action, color-accent, color-text, color-text-muted, color-surface, color-surface-raised and color-border, each checked for contrast. Typography becomes six named styles. The same names are created as Figma variables and text styles.
Developers replace hard-coded values with semantic utilities, page by page. When marketing later asks for a slightly warmer background, it's a one-line change. This is an illustration of the process, not a client result.
How do you keep Figma variables and code tokens in sync?
Pick one source of truth and make the other follow it. For most startups, Figma variables are the source during design, and the codebase becomes the source once the site ships. What matters is that the same names exist in both and someone owns keeping them aligned.
Smaller teams can sync by hand with a short checklist at each release. Larger teams export tokens as JSON, often in the format proposed by the W3C Design Tokens Community Group, and transform them into CSS automatically. Our walkthrough on syncing Figma variables to Tailwind covers that workflow step by step.
What should brand design tokens include at minimum?
A minimum viable token set covers color roles, typography styles, spacing, radius and a couple of motion values. That's enough to build a consistent marketing site and product UI, and you can add component tokens when real exceptions appear.
- Color: action, accent, text, text-muted, surface, surface-raised, border, and status colors for success, warning and danger.
- Typography: display, three heading levels, body, small body, label and mono, each as a complete style.
- Spacing and layout: a short spacing scale, section spacing and container widths.
- Shape and depth: a few radius values and one or two shadows.
- Motion: a couple of durations and easing curves, so interactions feel like the same brand.
Add tokens to the deliverables you ask for in any identity project, alongside everything in our brand identity checklist. Developer-focused companies should also read our guide to developer tool branding, because that audience notices inconsistency quickly.
