Design tokens for small teams

A design token is a named value that represents a specific visual decision. Instead of writing color: #2563eb in your CSS, you write color: var(--color-primary). The hex value lives in one place. Every component that needs the primary color references the same token. Change the token, and every reference updates automatically.

That sounds simple, because it is simple. The concept of tokens is not complicated. What gets complicated is the structure around tokens: how many layers to create, what naming convention to use, where to store them, how to distribute them across platforms, and how to handle theming. Enterprise token systems solve all of those problems simultaneously, which is why they require dedicated teams and months of planning.

Small teams do not need to solve all of those problems. Most teams under 20 people are shipping a single web application, maybe with a marketing site alongside it. They do not need cross-platform token distribution. They do not need a dedicated token management tool. They need a flat file of CSS custom properties that everyone on the team agrees to use instead of hardcoding values. That is the starting point, and for many small teams, it is also the ending point.

The mistake is assuming that because large companies use complex token architectures, your team needs one too. You do not. You need the discipline of naming your values and putting them in one file. Everything else is optional until your team grows enough to need it.

The key insight for small teams is that token architecture should match team complexity, not industry best practice. A three-layer token system with global, semantic, and component layers is genuinely useful when you have multiple teams consuming the same tokens for different products. When you have one product and one team, two layers are usually enough: a global layer that defines the raw values and a semantic layer that maps those values to purposes.

The global layer holds your palette. It might define --blue-500: #2563eb, --gray-100: #f3f4f6, and --spacing-4: 1rem. These tokens describe what the value is, not what it is for. The semantic layer then assigns intent: --color-primary: var(--blue-500), --color-surface: var(--gray-100), --space-component-padding: var(--spacing-4). Developers use the semantic tokens in their components and never reference global tokens directly.

Why two layers instead of one? Because a single flat list of semantic tokens gets ambiguous quickly. If you only have --color-primary and need to change it, you need to know what the original value was. With a global layer, you can see the mapping: primary was blue-500, and now you want it to be blue-600. The global layer is your reference sheet. The semantic layer is your working vocabulary.

Component-level tokens, the third layer in enterprise systems, are rarely needed for small teams. They introduce indirection that makes debugging harder without delivering proportional value. If a button needs a unique padding that differs from the standard component padding, just override the semantic token inline or create a one-off CSS class. You can always introduce the component layer later if your system grows to the point where semantic tokens are not granular enough.

The Solid getting started guide demonstrates this layered approach in practice, showing how token values flow from definition through to component output without requiring enterprise tooling.

Color is where token discipline pays off fastest. Most codebases accumulate hex values like sediment. After a year of development, a typical project might contain 40 to 60 unique color values scattered across component files, half of which are slight variations that nobody intended to create. A color token file prevents this entirely.

Start with a constrained global palette. You need a primary hue, a neutral scale (grays), a success color, a warning color, a danger/error color, and possibly a secondary or accent hue. For each hue, define a scale of 5 to 9 stops. You do not need 50-shade palettes. A small team using 7 shades of a primary blue will cover backgrounds, borders, text, hover states, and active states without any gaps.

Then create semantic mappings for every color purpose you can identify. At minimum, you need tokens for primary action, secondary action, text on light backgrounds, text on dark backgrounds, surface/background, border/divider, success feedback, warning feedback, and error feedback. If you support dark mode, each semantic token gets a second value scoped to a dark mode selector. The global palette stays the same. The semantic mappings change.

One pattern that works well for small teams is a "color intent" comment block at the top of the token file. List every semantic token with a one-line explanation of where it should be used. This serves as a quick reference that prevents developers from choosing the wrong token because they could not figure out which one was appropriate. When the token names are clear and the intent comments are current, developers stop guessing and start referencing.

Spacing tokens are deceptively important. Inconsistent spacing is one of the first things that makes an interface feel unpolished, and it is one of the hardest problems to fix retroactively. If every developer picks their own padding and margin values, the result is an interface where nothing quite lines up and the visual rhythm shifts from page to page.

A spacing scale based on a consistent multiplier solves this. A 4px base unit is the most common choice: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64. Map these to named tokens like --space-1 through --space-10, or use t-shirt sizing like --space-xs through --space-2xl. The naming convention matters less than the constraint. When every spacing value in the system comes from this scale, components align naturally because they share the same underlying rhythm.

Typography tokens cover font family, font size, font weight, line height, and letter spacing. The minimum viable set for a small team is three to five font size tokens (small, body, large, heading, display), two to three weight tokens (normal, medium, bold), and corresponding line height tokens for each size. Resist the urge to create a token for every font size you might someday need. Start with what you use today and add tokens when a genuine new size requirement appears.

One common mistake is defining font size tokens without matching line height tokens. A 14px font and a 24px font need different line heights. If developers set font size from a token but pick their own line height values, the typography will look inconsistent even though the sizes are correct. Always pair size and line height tokens, either as individual tokens or as composite type scale tokens that set both values together.

Tokens are not universally beneficial. There are specific situations where introducing tokens adds overhead without delivering value, and recognizing those situations early saves time and frustration.

If your project is a prototype or proof of concept that will be discarded after stakeholder review, tokens are unnecessary. The purpose of tokens is long-term consistency. A project with a two-week lifespan does not benefit from architectural decisions designed for two-year lifespans. Hardcode your values, move fast, and throw it away when you are done.

If you are a solo developer and you will always be the only person touching the codebase, tokens provide less value because the consistency problem they solve is primarily a coordination problem. You can keep visual decisions consistent through personal discipline. That said, even solo developers benefit from a simple variable file for frequently changed values like brand colors, just not a full token architecture.

If your team has no agreement on using tokens, introducing them unilaterally creates a split codebase: half the components use tokens and half do not. This is worse than having no tokens at all because now developers have to check whether a given file uses tokens or raw values before making changes. Token adoption needs to be a team decision with a commitment to migrate existing code incrementally.

And if you are working within an existing design system that already defines its own token layer, do not create a parallel token system. Use the tokens the system provides. The Solid design system, for example, ships with a complete token set that covers color, spacing, typography, and elevation. Teams adopting Solid do not need to define their own tokens from scratch. They customize the existing token values to match their brand and the system handles propagation.

The fastest way to adopt tokens on a small team is to start with new components. Do not stop current work to tokenize the entire codebase. Instead, agree as a team that every new component from this point forward will use tokens for color, spacing, and typography values. Create the token file, populate it with the values your current design already uses, and reference those tokens in every new file.

Existing components get tokenized opportunistically. When a developer opens an older file to fix a bug or add a feature, they replace the hardcoded values with tokens as part of that change. This approach means the codebase converges on tokens gradually, without a dedicated migration sprint that pulls everyone off product work.

Keep the token file simple. One CSS file with custom properties, organized into sections for color, spacing, typography, and any other categories you need. No build tools. No transformation pipeline. No JSON-to-CSS conversion. You can add tooling later if the team grows or if you need to support multiple platforms. For now, a flat CSS file that every developer can read and edit is the right level of complexity.

Review token usage in pull requests the same way you review code quality. If a new component introduces a hardcoded color value, ask why. If there is a valid reason, add a new token. If there is not, update the code to use an existing token. This review practice is what actually prevents drift. The token file creates the possibility of consistency. The team practice enforces it.