Skip to content

Is CSS the future of design data?

On this page

I've been turning over a question I never expected to ask: where do design tokens belong as CSS expands?

I want to be clear: tokens solve real problems. Design decisions used to get re-typed by hand into Sass variables, iOS asset catalogs and Android XML, drifting a little with every copy. A design token gave each decision a name and a single source of truth; and build tools carried it forward into every platform.

The Design Tokens Community Group shipped the first stable version1 in October 2025, after years of careful work by people I know and respect. It's vendor-neutral, handles modern color spaces, and design and translation tools have already adopted it.

I learned a lot of what I know about tokens from Garth Braithwaite at Adobe, who looks after Spectrum's design data. If you want to hear how tokens work at that scale, his conversation on the Design Systems Podcast2 about governance and scaling Spectrum is well worth your time.

For a system to support all the surfaces, design logic quickly becomes combinatorial and multi-dimensional. A single color responds to a user's settings, device, the context a component sits in and the component's own state. As the web expands to meet these needs, so too has CSS, the web's own design language; it has developed relationships, conditions and functions for every conceivable combination. I think CSS has become a better home for design decisions, and I wish more design languages and tools leaned into it. CSS should be the source of truth, and the places that can't read it yet should add support for it, because there exists no stronger, more expressive language for describing design intent.

This post is about the future. Today, tokens are still the only practical way to carry design decisions beyond the browser, into native apps and design tools, and to author the things CSS can't express in every browser yet: scale formulas, composite values, and grouped, documented decisions. On the web, nearly everything a decisions layer needs is already Baseline, including two of its biggest pieces, contrast-color() and style queries, which only got there this year. The rest is close behind (the list is near the end). Without those last pieces, CSS can't fully replace a token file. With them, it can describe design decisions more expressively and accurately than JSON.

The limits of JSON #

None of this is a knock on the people writing the spec. These are hard problems, and most of them come from the shape of the data rather than the choices anyone made.

Values are easy, relationships are hard #

A token file is very good at saying "this blue." It has a much harder time saying "this blue, 10% darker on hover" or "whichever of these text colors that passes contrast on this background." The format has aliases3, so one token can point at another, but a pointer says "same as." It doesn't say "derived from."

So derived values usually get computed once and stored as a static value, one token per state:

tokens.jsonJSON
{	"color": {		"brand": {			"$type": "color",			"$value": { "colorSpace": "oklch", "components": [0.62, 0.19, 259] }		},		"action": {			"background": { "$type": "color", "$value": "{color.brand}" },			"background-hover": {				"$type": "color",				"$value": { "colorSpace": "oklch", "components": [0.54, 0.19, 259] }			},			"text": {				"$type": "color",				"$value": { "colorSpace": "oklch", "components": [1, 0, 0] }			}		}	}}

background-hover is "eight points darker than the brand," but all we can store is the result. Change the brand color and the hover state stays where it was. Same with text: white was the right answer for this blue, but the accessibility considerations occur outside the file.

The community group has been working on exactly this. There's been an open discussion about color modifications4 since 2021, and it's a hard problem: every modifier you add to a JSON format is a small piece of a programming language that every tool then has to implement the same way.

Here's the same intent in modern CSS:

theme.cssCSS
:root {	--brand: oklch(62% 0.19 259);	--action-bg: var(--brand);	--action-bg-hover: oklch(from var(--action-bg) calc(l - 0.08) c h);	--action-text: contrast-color(var(--action-bg));}

Relative color syntax (from the CSS Color Module Level 5 specification) keeps the "darker on hover" relationship alive, and contrast-color() picks black or white text against whatever the background ends up being. Swap --brand and everything downstream recalculates. The decision stays in the file, along with its output.

Accessibility: A static value can't encode "must pass contrast against its surface," so that rule typically sits in a test suite, a linter, a wiki page, someone's head, or often, nowhere at all. Through CSS, it is recorded and can lean into the platform's own calculations, no assumptions required.

The web multiplies #

Light and dark. Brands and sub-brands. Comfortable and compact density. Those are the axes a design systems team chooses, and each adds new dimension to the others.

The spec handles those thoughtfully. Its resolver module5 (the part that handles themes) introduces modifiers, calls each resolved combination a permutation, and recommends keeping modifiers orthogonal so they don't fight over the same token. It's a clear model for resolving themes ahead of time. It answers the question of the environments and states you consider ahead of time.

What remains is everything we couldn't imagine or enumerate in advance. The web thrives in that gap; it runs on every kind of device, for every kind of person, and the browser tells your styles about a lot of it through user preference media features and more:

Count just contrast, forced colors, motion, pointer and text direction as two states each, add the team's three axes, and one button already has 256 possible combinations. Then add a button's own states (rest, hover, focus, pressed, disabled) and whether it sits on a default or an inverse surface, and its background color alone has 2,560 possible values. Font size, viewport and container size aren't on/off switches either, so the real number has no finite ceiling. A build step can't enumerate that, and I don't think it should try.

CSS doesn't enumerate it either. It resolves each condition as part of a range of conditions at runtime, on the element, against the context it's actually in:

button.cssCSS
.button {	background: var(--action-bg);	color: contrast-color(var(--action-bg));	min-block-size: 2.25rem;	transition: background-color 150ms;	@media (pointer: coarse) {		min-block-size: 2.75rem;	}	@media (prefers-contrast: more) {		--action-bg: oklch(from var(--brand) calc(l - 0.15) c h);	}	@media (prefers-reduced-motion: reduce) {		transition: none;	}	@media (forced-colors: active) {		border: 1px solid ButtonText;	}}

Each condition written once, wrapping the thing(s) it changes, and the browser combines whichever ones apply. The team's own axes work the same way: light-dark() for the color scheme, a [data-brand] selector for the brand, and a container query for density based on the space the component actually has.

Scales as functions #

A spacing or type scale is a formula: a base and a ratio. A JSON value holds the outputs, space-1 through space-8, and the formula usually lives in a spreadsheet or a script somewhere.

CSS can now hold the formula. Custom functions6 are newer and only in Chromium for now (Safari has them in Technology Preview), so treat this as a preview of where things are going:

scale.cssCSS
@function --space(--step <number>) returns <length> {	result: calc(var(--space-base) * pow(1.5, var(--step)));}.card {	padding: --space(2);}

And if()7 (Chrome 137 and later) lets a single value branch on a style, media or support query:

scale.cssCSS
.card {	padding: if(		style(--density: compact): --space(1);		media(width < 40rem): --space(2);		else: --space(3)	);}

The first condition that matches wins, so the order of the branches is part of the design decision.

Names end up carrying the logic #

Custom properties still need names, and naming is still (and will likely always be) hard. But when a format can't express a relationship, the name tends to carry it instead.

The tokens.json example above already does it: background-hover is a name doing a value's job, recording "the hover version of the background" because the value can't. Every condition from the web multiplies that a team chooses to support becomes one more segment:

SegmentWhat it records
colorThe type of the value
actionThe component
backgroundThe property it defines
hover, pressedThe component's state
inverseThe surface it sits on
dark, high-contrastThe user settings

color-action-background-hover-pressed-inverse is describing a relationship in the only place it can, and the list of names grows the same way the combinations did. Enforcing this structure in a tool is a lot of work and as a team scales, this kind of naming becomes harder to enforce.

Once the relationship lives in the value, the name only has to say what the thing is: --action-bg. The state and the surface move into the selectors and queries around it, which the style query and state sections below walk through. Short, stable names also make a better contract between designers and engineers.

Every new CSS feature introduces a new data model question #

This worries me most, for the spec and for everyone who builds tools on it. CSS keeps adding expressive features: relative colors, contrast-color(), container queries, if(), custom functions. For a JSON format to describe them, it needs expressions, conditions, functions and some notion of context, and every translation tool needs to evaluate them identically. Then every condition multiplies with every other one.

That's a lot to ask of a data format whose great strength is being simple, stable and easy for any tool to read. I don't think the answer is for JSON to keep growing until it can model all of CSS. That path ends with a second, harder-to-read CSS.

CSS as a design language #

None of this works if designers can't use CSS. Proposing it as an alternative to tokens only makes sense if the design part of the language is something a designer can read and write, and if there's a clear line between that and the engineering work. I think both are true.

Different kinds of hard #

Before a brand color ships, someone has tuned it to hold up in light and dark themes, stepped a palette around it so the lightness reads evenly, and pulled colors that were never chosen with contrast in mind into something accessible. Each one is a calculation, usually done in its own tool, outside the file where the product ultimately ships.

Light and darkAaAaL 52%5.2:1L 74%7.4:1today: a plugin Even lightness steps928068564432oklch lightness, 12 points aparttoday: a spreadsheet Accessible contrastAaAa2.4:1 fails5.0:1 passestoday: a contrast checker
Lightness in oklch; contrast as WCAG 2 ratios.

The parts of CSS with a reputation for being hard are its mechanics: which selector wins, what an element inherits, which layout algorithm applies, what a box is measured against. Those are engineering problems, and owning a design decision no longer means solving them.

The concern I hear most is designers being asked to take on more and more of the engineering work. Moving from crafting tokens to tracking decisions in CSS doesn't have to equate to more work or more effort. Designers and engineers solve different problems, and the split below suggests a way to keep each side in the part of CSS that fits their existing mindsets.

Luckily, CSS is built for exactly the kind of design calculations designers do today. oklch() describes color by perceptual lightness, chroma and hue, so a palette can step evenly. Relative color keeps a derived color tied to its source. contrast-color() puts a contrast decision in the value itself. That math can live next to the decision it serves:

decisions.cssCSS
@layer decisions {	:root {		color-scheme: light dark;		/* Color */		--brand: oklch(62% 0.19 259);		--brand-hover: oklch(from var(--brand) calc(l - 0.08) c h);		--surface: light-dark(oklch(98% 0.01 90), oklch(22% 0.02 260));		/* Type */		--text-body: clamp(1rem, 0.9rem + 0.4vw, 1.125rem);		/* Space */		--space: 0.5rem;		--space-inset: calc(var(--space) * 3);		/* Motion */		--duration-quick: 150ms;		--ease-out: cubic-bezier(0.2, 0, 0, 1);		@media (prefers-contrast: more) {			--brand: oklch(48% 0.19 259);		}	}}

There's no selector logic beyond :root, no layout and no specificity. clamp() says "this size, within these limits," and light-dark() pairs the two schemes in one line. Every line is a decision a designer already makes in a design tool, written in a form the browser can run. A design tool that stores "#3B5BDB" knows a value; a stylesheet that stores oklch(from var(--brand) calc(l - 0.08) c h) knows a decision.

A clear separation of concerns #

Cascade layers turn that split into a real boundary. Designers own the decisions layer: custom properties (plus container names, which I'll come back to), set on the root, a theme or component hook, wrapped in whatever media or container conditions the decision depends on. Engineers own the components layer, which reads those properties and never hard-codes a design value.a Pick a side:

Designer

decisions.css

@layer decisions {	:root {		--brand: oklch(62% 0.19 259);		--brand-hover: oklch(from var(--brand) calc(l - 0.08) c h);		--space-inset: 1.5rem;		--duration-quick: 150ms;		--ease-out: cubic-bezier(0.2, 0, 0, 1);	}}

Engineer

button.css

@layer components {	.button {		background: var(--brand);		padding: var(--space-inset);		transition: background-color var(--duration-quick) var(--ease-out);		&:hover {			background: var(--brand-hover);		}	}}

Designers own the palette and how colors relate, the type, space and radius scales, motion, every theme's values (light, dark, each brand, high contrast), and responsive intent ("below 30rem, the card goes compact"). Engineers own selectors, specificity and scoping, component structure, layout implementation, browser support and performance, and the accessibility mechanics behind focus and semantics.

A few things sit on the seam. Designers decide what a pressed button looks like; engineers decide where that state lives. A grid's proportions are a design decision, but they're written in code and meet real content. And the custom property names are the contract between both roles, so neither side should rename them alone. A file-ownership rule and a lint rule (no raw colors or lengths in components, nothing but custom properties in decisions) can hold that line. It's the same handoff tokens give you today, with one difference: the designer's side can now express relationships and conditions.

Conditions belong with the decision #

This is the part of the split I care about most. In the decisions layer, a designer defines so much more than a value; they choose when it applies, in the same place, in the browser's own terms.

Here's a responsive type and spacing decision. Reading it, you know exactly what changes and at what point:

decisions.cssCSS
@layer decisions {	:root {		--space-inset: 1.5rem;		--text-title: 1.5rem;		@media (width < 40rem) {			--space-inset: 1rem;			--text-title: 1.25rem;		}	}}

User preferences work the same way. Each condition sits right next to the values it changes, so the intent is in the code rather than in a handoff note:

decisions.cssCSS
@layer decisions {	:root {		@media (prefers-contrast: more) {			--brand: oklch(48% 0.19 259);			--border-width: 2px;		}		@media (prefers-reduced-motion: reduce) {			--duration-quick: 0ms;		}		@media (pointer: coarse) {			--target-size: 2.75rem;		}	}}

Container queries let a designer make the decision at the component level, based on the space the component actually gets rather than the size of the screen. This one shows the seam nicely: the engineer names the container, and the designer decides what changes inside it.

Engineer

components.css

@layer components {	.card-slot {		container: card / inline-size;	}	.card {		padding: var(--space-inset);	}}

Designer

decisions.css

@layer decisions {	.card {		@container card (inline-size < 30rem) {			--space-inset: 0.75rem;			--text-title: 1.125rem;		}	}}

That snippet also shows where the seam gets uncomfortable. The container query only works because an engineer named the container, and that name is the only thing tying the layers together. Rename it in components.css and the designer's decision silently falls away.

Designers, with their familiarity with the topology of the system—what nests inside what, which regions stretch and which stay fixed—should own container names. Naming is already design-side work on most teams; it's part of the vocabulary they use to talk about the system. CSS even splits this cleanly, because a container's name and its containment are separate properties. container-name is just a label. container-type changes how the element sizes, which is layout mechanics.

Designer

decisions.css

@layer decisions {	.card-slot {		container-name: card;	}	.card {		@container card (inline-size < 30rem) {			--space-inset: 0.75rem;		}	}}

Engineer

components.css

@layer components {	.card-slot {		container-type: inline-size;	}}

A few other habits ease the seam:

  • Name containers by role (card, sidebar, media) rather than structure, so the names survive a refactor. An element can carry more than one name, too.
  • Treat container names like custom property names: part of the component's contract, documented with it, and never renamed by one side alone.
  • When a decision depends on context rather than size, skip containers entirely and use a style query, which deserves its own section.

Style queries: inherited context #

If there's one new feature I'd put in front of every designer, it's this one. Style queries let a design decision respond to context, not only to the size of the screen or the container.

A style query asks about the context an element inherits: the value of a custom property set somewhere above it. Every element can answer one, so there's no containment to set up, and all three browser engines support them for custom properties as of May 2026. That means a designer can describe a context once, on a region, and let everything inside it respond.

And because a context is a custom property, its values are entirely open-ended. CSS doesn't decide what the contexts are; the design system does. A designer can invent --surface: inverse, --density: compact, --tone: celebratory or --season: holiday, add one to a region to express a variation, and remove it to go back. Variations come from adding and removing contexts, rather than from new component variants or props.

Density is the simplest example. Mark the sidebar as compact, and every card inside it tightens up:

decisions.cssCSS
@layer decisions {	.sidebar {		--density: compact;	}	.card {		@container style(--density: compact) {			--space-inset: 0.5rem;		}	}}
mainsidebar--density: compactinset: 1.5reminset: 1.5reminset: 0.5rem
The same card in both regions. Only the inset, tinted here, changes.

Surfaces are where it really pays off. Brand and marketing pages are full of dark bands, image heroes and saturated panels, and every component placed on them needs an inverse treatment. Today that usually means an inverse variant on every button, link and badge, and someone remembering to apply it. With a style query, the surface says what it is, and the components follow:

decisions.cssCSS
@layer decisions {	.hero {		--surface: inverse;	}	.card {		--surface: default;	}	.button {		@container style(--surface: inverse) {			--action-bg: oklch(98% 0.01 90);		}	}	a {		@container style(--surface: inverse) {			--link-color: oklch(92% 0.04 259);		}	}}

Tone works the same. A designer can mark a region as critical or celebratory and let icons, borders and emphasis adjust inside it, without inventing a new class for every combination.

Real design systems already run into this, and they've solved it with the tools they had: props copied onto children in JavaScript, or a framework's context API. Two examples, with respect for the teams behind them, since both were built before style queries existed.

Spectrum groups buttons into toolbars, and the group sets a treatment for everything inside it. In Spectrum Web Components, <sp-action-group> copies its quiet and size values onto each child button in JavaScript whenever they change. In the newer React Spectrum, ActionButtonGroup passes isQuiet, size and density down through React context. Its Button also has premium and genai variants, so a promotional panel full of buttons sets that variant on each one. As inherited context, the group or the panel says it once:

decisions.cssCSS
@layer decisions {	.toolbar {		--treatment: quiet;		--size: small;	}	.upsell {		--tone: premium;	}	.action-button {		@container style(--treatment: quiet) {			--action-bg: transparent;		}		@container style(--size: small) {			--target-size: 1.5rem;		}	}	.button {		@container style(--tone: premium) {			--action-bg: var(--premium-gradient);		}	}}

(The custom property names here are mine, not Spectrum's. The point is the shape: the context lives on the container, and nothing has to copy it onto the children.)

Carbon's <Layer> steps background colors up one level each time layers nest, from one to three. Today, a React context counts the depth and each layer adds a class like cds--layer-two, and the CSS re-emits the layer tokens for each class. The cascade is already doing half the work; JavaScript is only counting.b A style query can do the counting too, because each layer reads the level it inherits and sets the next one:

decisions.cssCSS
@layer decisions {	.layer {		--layer: 1;		--layer-background: var(--layer-01);		@container style(--layer: 1) {			--layer: 2;			--layer-background: var(--layer-02);		}		@container style(--layer: 2) {			--layer: 3;			--layer-background: var(--layer-03);		}	}}

There's one rule to keep in mind: the value has to be set on an ancestor, because an element can't query itself. And there's more coming. Range syntax for style queries (style(--elevation > 2)) is in Chromium and Firefox.

A token can hold every value in these examples. button-background-inverse and layer-02 are perfectly good token names. What it can't hold is the rule that picks between them: "one layer up from wherever you are," or "follow the nearest surface above you," so a light card inside a dark hero turns its buttons back to the default without anyone passing a prop. That rule depends on where a component lands on the page, so today it lives in a prop, a context provider or a class someone has to remember. With style queries, designers can write the rule down themselves, and it runs exactly as written.

States: decisions that depend on a component's state #

The other half of context is state. A component's own state (checked, expanded, loading, invalid) changes how it should look just as much as where it sits.

Built-in elements already report most of these. A checkbox matches :checked and :indeterminate, a <details> or <dialog> matches :open (Baseline since May 2026), a field matches :user-invalid once someone has actually interacted with it, and anything interactive matches :hover, :focus-visible and :disabled. ARIA states are selectors too: [aria-expanded="true"], [aria-current="page"], [aria-pressed="true"]. Styling the ARIA attribute, rather than a class that mirrors it, means the way a state looks can't drift from what assistive technology announces.

Each of those is a hook a designer can hang a decision on, and there's no engineering step at all, because the browser sets these states itself:

decisions.cssCSS
@layer decisions {	input {		--field-border: var(--border);		&:focus-visible {			--field-border: var(--brand);		}		&:user-invalid {			--field-border: var(--critical);		}	}	nav [aria-current="page"] {		--nav-indicator: var(--brand);	}	details:open {		--summary-weight: 600;	}}

Custom elements are where the platform runs out of states. A switch can be loading, a card can be selected, a row can be dragging, and no built-in pseudo-class knows that. The custom state pseudo-class started as a working group proposal to fill that gap and is now :state(), Baseline since May 2024. A custom element sets its states through ElementInternals.states, and any stylesheet can match them. That makes state part of a component's public contract, alongside its custom properties and container names. Which states a component has is often a design decision, and on teams with a deep bench of experienced designers, it usually is. Who writes the code that sets them depends on the team. Either way, that part is small, and what each state looks like lives in the decisions layer, without touching the component's internals:

Designer

decisions.css

@layer decisions {	x-switch {		--track-color: var(--surface-muted);		--thumb-color: var(--surface);		&:state(checked) {			--track-color: var(--brand);		}		&:state(loading) {			--thumb-color: var(--surface-muted);		}	}}

Engineer

x-switch.js

class XSwitch extends HTMLElement {	#internals = this.attachInternals();	set checked(value) {		if (value) {			this.#internals.states.add("checked");		} else {			this.#internals.states.delete("checked");		}	}}

Compare that with how a token file carries state: in the name. switch-track-color-checked, then switch-track-color-checked-hover, then switch-track-color-checked-hover-inverse, multiplying with every variant and theme. In CSS, each state is a selector the designer writes once, and it combines with contexts and conditions on its own.

There are limits. :state() only works on custom elements, and a descendant can't directly ask about an ancestor's state; today that takes :has(), a descendant selector, or a custom property flag read with a style query.

Now compare how a token pipeline describes the same kind of decision. This is adapted from the resolver module's own example:

tokens.resolver.jsonJSON
{	"modifiers": {		"size": {			"contexts": {				"small": [{ "$ref": "typography/mobile.json" }],				"large": [{ "$ref": "typography/base.json" }]			}		}	}}

That's a clean way to name the contexts, and it's what a file format can do. But small is only a name. When small applies (a viewport width, a container width, a pointer type, a user's font size) isn't in the file. Someone decides it later, usually an engineer, in code the designer never sees. The value and the condition that gives it meaning end up in two places, owned by two people. That's the relationship I don't want to lose, and it's what keeps designers close to how the web actually behaves.

Indirection is closer to the user's reality #

Design tools work by direct manipulation: select the thing, change the thing. CSS is indirect, a rule that applies wherever it matches. That sounds like a step backward until you remember that users never see "the button." They see every instance of it, in their own color scheme, font size and screen. A design file shows one moment of the design. CSS describes the experience.

Designers already work this way, too. Components, instances, variants and variables exist in design tools to bring back exactly that indirection: edit the main component and every instance follows.

What I'd like tools and design languages to do #

Right now, most design tools store values and export code, and most design languages publish their decisions as token files first. I wish both leaned the other way: design tools that read a stylesheet's decisions layer as their source, let you edit it visually, show each decision across many contexts at once, and write CSS back, with the browser as the reference renderer; and design languages that publish their CSS as the reference, relationships and conditions included, rather than as one more export.

This is the hardest part of the argument. It asks design tools to build a lot, and it asks designers to learn the design half of a language engineers have spent decades complaining about. I think it's worth it anyway, because the alternative is teaching a second format everything CSS already knows.

Is the token format easier to learn? #

In a lot of ways, yes, and that deserves a real answer before I ask designers to write CSS.

Here's why a token file reads more easily:

  • It has a small, closed vocabulary. The format defines a handful of types (color, dimension, font family, font weight, duration, cubic Bézier, number) and a few composite types like typography, shadow and border. CSS has hundreds of properties.
  • It groups by design concept. A typography token is one object: family, size, weight, line height and letter spacing together. In CSS those are separate properties, and the font shorthand leaves out letter spacing while resetting things you didn't mention.
  • There's no cascade to reason about. A token's value is its value. A custom property's value depends on where it's read, what it inherited and which rule won.
  • It's typed and documented. $type says what a value is, and $description and $deprecated travel with it. An unregistered custom property is an untyped string, a typo fails quietly, and documentation lives in comments no tool reads.
  • You can browse it. Groups nest, so color.action.background reads like a table of contents. Custom properties are one flat list of names.

Some of that ease comes from what the format leaves out. A token file doesn't have to handle context, so it never has to explain inheritance or conditions. Once it does (themes in the resolver, aliases across files, JSON Pointer references), it starts picking up a learning curve of its own.

What CSS could borrow #

The good news is that CSS can close some of that gap, and part of it already has:

  • Types already exist. @property gives a custom property a type, an inheritance rule and an initial value, and it's been in every major browser since mid-2024. Registering design values catches mistakes and documents intent in the same place:
tokens.cssCSS
@property --brand {	syntax: "<color>";	inherits: true;	initial-value: oklch(62% 0.19 259);}
Deep dive: what @property is missing for design systems

@property is the closest thing CSS has to a token, and it does what it was built for well: it types a single value so the browser can animate it and catch bad input. For design systems, it stops short in six places.

Registration is global. Every @property rule, including one inside a shadow root, lands in one registry for the whole document. If two libraries register the same name differently, the last one in document order wins, and a registration from JavaScript beats both. For a component library dropped into a page you don't control, that's a real collision risk.

collision.cssCSS
/* From a design system */@property --space {	syntax: "<length>";	inherits: true;	initial-value: 8px;}/* From a third-party widget, loaded later */@property --space {	syntax: "<number>";	inherits: true;	initial-value: 1;}

A default can't reference another value. initial-value has to be computationally independent: no var(), no em. So the most basic token relationship, an alias, can't be expressed at registration.

alias.cssCSS
@property --action-bg {	syntax: "<color>";	inherits: true;	initial-value: var(--brand); /* invalid, so the whole rule is ignored */}

Types are coarse. The syntax descriptor8 knows <color>, <length>, keyword lists and repetition, but it can't say "a number between 0 and 1" or "a length no larger than 4rem," and it has no composite type like a typography token.

It's verbose. One block per property, with all three descriptors, and no way to register a group at once. A modest system with 200 values means 200 blocks.

There's no metadata. A registration can't carry a description, a deprecation notice or a group, so it documents the type and nothing else.

Failure is still quiet. An invalid value falls back to the initial value. That's better than an untyped string, but nothing tells you it happened.

To be fair, some of this is deliberate. The spec explains why registration is global: styles from inside and outside a shadow root meet on the same elements through :host and ::part(), so scoped registrations would contradict each other. The no-var() rule follows from the same choice, since a global registration has no element to resolve a reference against. Those are coherent trade-offs; they just weren't made with design systems in mind.

What would turn it into a design system tool: registrations that can be scoped or namespaced per library, defaults that can reference other properties and resolve where they're used, range and enumeration constraints, a way to register a whole group at once, and description and deprecated descriptors. Several of these already have open discussions in the working group, collected in the References.

  • Groups are being discussed. There's an open proposal for CSS variable groups, written with design system pain points in mind, so a whole color scale could live under one name.
  • Composites are specified, not shipped. Mixins (@mixin and @apply, in the same draft as custom functions) could bundle a typography decision into one reusable block, the way a composite token does. No browser has shipped them yet, and the idea goes back to higher-level custom properties that set several declarations at once.
  • Metadata is my wish. There's no standard way to attach a description or a deprecation notice to a custom property, the way $description and $deprecated do. A description descriptor on @property would go a long way, and tools could show it the way design tools show token descriptions today.

None of these make the cascade disappear. They would make the design half of CSS (named, typed, grouped, documented decisions) feel a lot closer to what a token file offers, without giving up what only CSS can do.

"But iOS and Android don't speak CSS" #

This is the strongest objection, and it's where tokens earn their keep today. The token spec announcement leads with it: one file can generate code for iOS, Android, web and Flutter.

My first instinct was to say those platforms should just learn CSS. Then I tried arguing with myself, and the argument got more interesting.

Which parts of CSS need a tree? #

Two. The cascade itself (origins, layers, specificity, source order) only decides which declaration wins for a single element. The tree matters for selectors with combinators (descendant, child, sibling, :has()), and for inheritance, which is how a custom property set on one element reaches everything inside it.

Native platforms already have trees #

UIKit, Android Views, SwiftUI, Jetpack Compose and Flutter all build view hierarchies, and none of them adopted selectors. Here's what they adopted instead:

  • SwiftUI's Environment passes values down the view hierarchy.
  • Compose's CompositionLocal does the same for a composition, which is how MaterialTheme reaches every component under it.
  • Flutter's InheritedWidget is the mechanism behind Theme.of(context).

Each of those is custom property inheritance under another name: a scoped design value, set once, read by anything below it.

CSS

checkout.css

.checkout {	--brand: oklch(68% 0.17 145);	button {		background: var(--brand);	}}

SwiftUI

CheckoutView.swift

extension EnvironmentValues {	@Entry var brand: Color = .blue}CheckoutView()	.environment(\.brand, .green)// Inside any view below it:@Environment(\.brand) var brand

Compose

CheckoutScreen.kt

val LocalBrand = compositionLocalOf { Color.Blue }CompositionLocalProvider(LocalBrand provides Color.Green) {	CheckoutScreen()}// Inside any composable below it:val brand = LocalBrand.current

Instead of selectors, styles attach directly to the view in code, the compiler checks them, and nothing silently stops matching because a class name changed. (The web drifted the same way with CSS-in-JS and utility classes, so this isn't only a native preference.) Even React Native, which kept CSS's property names, dropped the cascade and nearly all inheritance. The toolkits that kept selectors, GTK and Qt Style Sheets, come from an older desktop model, and selector matching is expensive: :has() took years to ship largely because of it.

On native, CSS won the vocabulary and lost the selector model.

The half that travels #

That turns out to be fine for this argument, because the half of CSS that matters for design decisions is the half every platform already has. Set selectors aside and two things are left:

  1. The value language: color spaces, calc(), relative color, color-mix(), contrast-color().
  2. Inheritance: scoped values that flow down a tree.

Native platforms already built the second one, and the first one is exactly what token files are missing. So iOS and Android don't need to adopt CSS wholesale. They need to read the value language, and each platform can keep its own way of attaching values to views. A build step can translate CSS for them in the meantime, but that's a stopgap: CSS stays the only source, and the goal is for those platforms to read it directly.

Where CSS is today #

Here's the set of features this approach depends on, and where each one stands as I write this, using Baseline status. "Widely available" means a feature has worked in every major browser for at least two and a half years; "newly available" means it works in the current version of every major browser.

Baseline widely available:

Baseline newly available:

Not Baseline yet: custom functions, if(), mixins, variable groups, and the @property gaps from the deep dive. Each one, and why this argument needs it, is in Table 1.

So for a web project starting this week, a decisions layer is practical now, as long as anything that has to work in older browsers gets a fallback for the newest pieces. What it can't do yet is hold a scale's formula everywhere, bundle a composite decision, or document and group decisions the way a token file can. And anything that leaves the browser still needs tokens.

So, is there a future? #

Yes, though I think it's a different one than tokens were first designed for.

Tokens are still the best answer we have for moving design decisions between tools and platforms, and a neutral, stable interchange format is valuable. The community group built a good one.

But as the source of truth for design decisions, I think CSS is the better solution. It's the standard every browser already implements, it can express how values relate, and it resolves every combination of user, device, context and state at runtime instead of asking a build step to predict them. I'd rather write a decision once, in the language that can express it fully, and have every platform read it from there.

A token file holds wellCSS can also express
Named valuesHow values relate and derive
Aliases between valuesContrast-aware pairs
Themes resolved ahead of timeEvery combination of user, device, context and state, resolved on the element
A scale's stepsThe scale's formula
Values every platform can readValues that adapt to their context

None of this retires tokens tomorrow. They're still the only way to carry design decisions beyond the browser and to cover the gaps in that list, and they'll stay essential while those gaps close. The case I'm making is for where we're headed: as those features reach every browser, we can replace JSON data with a description that's more expressive and more accurate, written in modern CSS.

So my wish list is short. Design tools that treat CSS as a design language, not an export format. Design languages that publish their CSS as the source of truth. And the platforms that don't read CSS yet adding support for it, because it's a better language for describing design.

I'd love to hear from the people working on the token specs most of all, since they've thought about these trade-offs longer than almost anyone. If your token pipeline does something CSS can't, or you see it differently, tag me on Mastodon at @castastrophe@front-end.social.

Sources & further reading

References

Notes

  1. "Designer" and "Engineer" on these examples are my opinion of a sensible default, not a rule. Teams split this work differently depending on the skills and preferences of their own people, and on plenty of teams designers own states, container names and more of what I've put on the engineering side. The layer is the boundary; who works in it is up to the team.

  2. Carbon isn't alone. Atlassian frames the same idea as elevation15 rather than layers, with tokens like elevation.surface, elevation.surface.sunken, elevation.surface.raised and elevation.surface.overlay. Its Box component passes the surface it paints down through React context, and Text reads it to pick a readable color, switching to inverse text on bold backgrounds. The difference is that Atlassian's surface follows the background you choose, while Carbon's steps up with nesting. React Spectrum's Spectrum 2 components carry a layer down through CSS instead: Provider16 takes a background of base, layer-1 or layer-2, and both it and Card17 set a --s2-container-bg custom property that their descendants inherit, which a card uses to match its inner outlines to its own background. That's already inherited context in CSS; it just carries a color rather than a keyword a style query could branch on.

Sources

  1. Design Tokens specification reaches first stable version, Design Tokens Community Group

    Post W3C w3.org Accessed

    The community group's announcement.

  2. DSP 133. Garth Braithwaite on Design Tokens, Governance, and Scaling Spectrum at Adobe

    Post Design Systems Podcast patterns.buzzsprout.com Accessed

  3. Design Tokens Format Module 2025.10, Design Tokens Community Group

    Spec designtokens.org Accessed

  4. Pre-defined composite type for referring color modifications

    Issue design-tokens/community-group github.com Accessed

    The community group's discussion of derived colors.

  5. Design Tokens Resolver Module 2025.10, Design Tokens Community Group

    Spec designtokens.org Accessed

  6. CSS Custom Functions and Mixins Module Level 1: custom functions, CSS Working Group

    Spec W3C drafts.csswg.org Accessed

  7. CSS Values and Units Module Level 5: the if() notation, CSS Working Group

    Spec W3C drafts.csswg.org Accessed

  8. CSS Properties and Values API Level 1: the syntax descriptor, CSS Working Group

    Spec W3C drafts.css-houdini.org Accessed

  9. CSS Custom Functions and Mixins Module Level 1: defining mixins, CSS Working Group

    Spec W3C drafts.csswg.org Accessed

  10. CSS variable groups (as a solution to several design systems pain points)

    Issue w3c/csswg-drafts github.com Accessed

    Groups and composites.

  11. Should property registration be scoped?

    Issue w3c/css-houdini-drafts github.com Accessed

    Registration scope.

  12. Should initial values be allowed to have variable references?

    Issue w3c/css-houdini-drafts github.com Accessed

    Defaults that reference other values.

  13. Mass property registration by prefix

    Issue w3c/csswg-drafts github.com Accessed

    Registering many properties at once.

  14. CSS Properties and Values API Level 1: the @property rule, CSS Working Group

    Spec W3C drafts.css-houdini.org Accessed

  15. Elevation

    Docs Atlassian Design System atlassian.design Accessed

  16. React Spectrum S2: Provider.tsx

    Code adobe/react-spectrum github.com Accessed

    Pinned to a commit, so the code it describes stays put.

  17. React Spectrum S2: Card.tsx

    Code adobe/react-spectrum github.com Accessed

    Pinned to a commit, so the code it describes stays put.

  18. Design Tokens Color Module 2025.10, Design Tokens Community Group

    Spec designtokens.org Accessed

  19. Higher level custom properties that control multiple declarations

    Issue w3c/csswg-drafts github.com Accessed

    Groups and composites.

  20. “Property registration cannot be scoped” differs from all implementations in a consistent way

    Issue w3c/csswg-drafts github.com Accessed

    Registration scope.

  21. Mass property registration

    Issue w3c/css-houdini-drafts github.com Accessed

    Registering many properties at once.

  22. @property descriptors should be optional whenever possible

    Issue w3c/csswg-drafts github.com Accessed

    Registering many properties at once.

  23. A compact syntax for registering global constants/custom properties

    Issue w3c/csswg-drafts github.com Accessed

    Registering many properties at once.

Table 1 Features still to come
FeatureWhy this argument needs itSupportSpec or discussion
Custom functions (@function)Store a scale's formula instead of its outputsChromium 139+; Safari Technology Preview; not in Firefox6
if()Branch a single value on a style, media or support queryChromium 137+; not in Firefox or Safari7
Mixins (@mixin, @apply)Bundle a composite decision, like typography, into one reusable blockNot shipped in any browser9
CSS variable groupsKeep a whole scale or palette under one nameProposal10
Scoped @property registrationLet a design system register its values without colliding with other code on the pageUnder discussion11
@property defaults that reference other valuesExpress an alias at registrationUnder discussion12
Registering many properties at onceMake registering a full system practicalUnder discussion13
Range constraints in @property syntaxCatch out-of-range design valuesNo proposal found8
Description and deprecation metadataDocument decisions the way $description and $deprecated doNo proposal found14

These are the features this post calls out as necessary for CSS to fully take over authoring from a token file, and none of them are Baseline yet. Support is as of October 2026. I couldn't find an open discussion for range constraints in the syntax descriptor or for description and deprecation metadata on registered properties. If one exists, I'd love a link.

Contact

A question about a post, a project, or working together — send it here. I try to reply within a couple of weekdays.

Required