CSS Custom Properties and Design Tokens for Maintainable Styles

Every website starts with a neat stylesheet. A few months and many feature requests later, the same brand blue appears in fourteen slightly different shades, spacing values are random and nobody dares to change anything. Sound familiar?

CSS custom properties, often called CSS variables, and the idea of design tokens help prevent this. They give your styles a single source of truth, making sites easier to maintain, theme and hand over.

What CSS Custom Properties Are

A custom property is a value you define once and reuse throughout your CSS. You declare it with two dashes, for example a property named brand colour on the root element, and use it with the var function wherever needed.

Unlike variables in preprocessors such as Sass, custom properties live in the browser. They follow the cascade, can be changed at runtime with JavaScript, and can be overridden inside specific components or media queries. This makes them powerful for themes, dark mode and responsive adjustments.

What Design Tokens Are

Design tokens are named decisions about your visual design. Instead of saying "this button is #1a73e8", you say "this button uses the primary colour token". Tokens usually cover:

• Colours: primary, secondary, text, background, border, success, warning, error
• Typography: font families, sizes, weights and line heights
• Spacing: a consistent scale used for margins, padding and gaps
• Radius: corner rounding values for cards, buttons and inputs
• Shadows and elevation levels
• Breakpoints and animation durations

Tokens can be stored in a design tool, a JSON file or directly as CSS custom properties. For small teams, CSS variables are often enough.

Larger teams sometimes split tokens into two layers. Base tokens hold raw values, such as a specific shade of blue. Semantic tokens point to base tokens and describe usage, such as button background or link colour. This extra layer makes rebrands and themes even easier, but small projects can start with semantic tokens only and add structure later.

Building a Simple Token System

You do not need a huge design system to benefit. Start small:

1. List every colour currently used in your CSS and group near-duplicates.
2. Choose a small palette and name colours by purpose, such as text-muted, not by appearance, such as light-grey.
3. Define a spacing scale, for example based on a 4 or 8 pixel step, and stick to it.
4. Set font sizes as a scale rather than random values.
5. Declare everything on the root element and replace hard-coded values gradually.

Tip: name tokens by role, not by value. A token called colour-primary can change from blue to green without renaming anything. A token called blue becomes a lie the day the brand changes.

Theming and Dark Mode Made Easier

Because custom properties cascade, you can redefine them for a theme. A dark theme might override background and text tokens inside a class or a prefers-color-scheme media query. Every component that uses those tokens updates automatically, with no duplicate CSS.

The same idea works for white-label projects. If an agency builds similar sites for different clients, a shared component library can use tokens, and each client gets their own token values for colours and fonts. This is a practical way to reuse code without every site looking identical.

Working With Designers

Tokens create a shared language between designers and developers. When a designer specifies "spacing-4" or "colour-surface", the developer knows exactly what to use. Modern design tools support variables or styles that map neatly to CSS tokens.

Agree on token names early in a project and document them in one place. A simple page in your project wiki listing each token, its value and its purpose prevents confusion and helps new team members. For broader handoff habits, see our post on code review habits for small dev teams.

Common Mistakes to Avoid

Tokens only help if people use them consistently. Watch for these traps:

• Creating too many tokens, so nobody knows which to choose
• Mixing hard-coded values with tokens, defeating the purpose
• Naming tokens after specific components too early, which limits reuse
• Forgetting fallback values for older browsers where they matter
• Changing token values without checking colour contrast for accessibility

Add a simple lint rule or code review checklist item that flags new hard-coded colours and spacing values. Small guardrails keep the system clean over time.

FAQ

Do CSS variables work in all modern browsers?

Yes, custom properties are supported in all current major browsers. Very old browsers may need fallbacks if you still support them.

Should I still use Sass if I use CSS variables?

You can use both. Sass helps with nesting and build-time logic, while custom properties handle runtime theming. Native CSS nesting is also increasingly available.

How do tokens work with utility frameworks like Tailwind?

Utility frameworks have their own configuration for colours and spacing, which acts like a token system. Keep that configuration as your single source of truth.

A small set of well-named tokens turns chaotic stylesheets into a consistent system. Start with colours and spacing, use them everywhere, and future changes become quick edits instead of risky hunts.