Foundation Color System Redesign

Overview

The EDS colour and token system had grown modern but overly complex and inconsistent, which slowed onboarding, diverged from common design-system patterns, and made token usage hard to measure. Following the June 2026 decision to redefine, not rebuild, this work keeps the proven foundation (the colour generator and values, the type scale, the contrast algorithm, and the primitives) and reworks the structure around it: simpler, more standard, and reliable enough for programmatic use. Accessibility is treated as a first-class constraint throughout, validated against both APCA and WCAG.

The problem

The variables had become overly complex and inconsistent, and the cost showed up everywhere: long onboarding for new team members, divergence from common patterns (for example, awkward export and import with Tokens Studio), and little visibility into component and token usage. The same semantic role was expressed with different values across sources, and three competing tier vocabularies (muted / default / emphasis versus subtle / medium / strong versus flat / nested) made the system hard to reason about.

Complexity also blocked the workflows the system needs to support next. Inconsistency between design and code, plus a structure that resisted reliable automation, made programmatic use by AI agents and citizen developers unpredictable and more token-hungry than it should be. And it held back progress on higher-level work: patterns, tables, and governance.

Contrast was a sharper issue underneath. Pairings had been chosen by eye, and while WCAG's ratio model catches many failures, it does not reflect how the eye actually perceives contrast, especially for light text and non-text elements like borders and icons. An audit surfaced real contrast failures in both light and dark themes.

Redefine, don't rebuild

The June 2026 decision set the constraint: keep what works, change the structure. In practice that means decoupling typography, spacing, and corner radius from colour so each can evolve on its own; consolidating colour on a static, semantic model and dropping the dynamic set; and expanding the static colour scale, shipped alongside the current colours rather than edited in place, so consumers migrate at their own pace. The current scale of roughly fifteen steps was not enough, and inserting steps in place would cascade-rename the whole scale and break every consumer, so the expanded scale ships in its own library using the same deprecation pattern EDS already uses for components.

APCA and WCAG together

The foundation is validated against both. WCAG stays as the baseline for compliance, and APCA (the Accessible Perceptual Contrast Algorithm, the contrast model behind the upcoming WCAG 3 direction) is the perceptual check the ratio model misses. APCA scores contrast the way perception works: it accounts for text weight and size, treats light-on-dark and dark-on-light differently, and covers non-text elements. That makes it well suited to a token system where the same colour role has to hold up across themes, weights, and component states.

The emphasis-tier model

To kill the competing vocabularies, the redefinition settles on a single emphasis model mapped onto the palette, work I contributed to through the token variable architecture. Component emphasis (high / medium / low) maps to non-interactive emphasis / default / muted, which in turn maps to fixed palette steps, and the on-context text and icon colours are pinned to their own steps so contrast is predictable wherever a role is used. One model, one vocabulary, one place to reason about it.

Generated and checked, not eyeballed

Colours are not hand-picked. The kept foundation includes an APCA-driven palette generator that computes the ramps, applies the emphasis-to-step mapping, and reports the contrast level of each pairing so a failing combination is caught before it becomes a token. My work here was refining and expanding the static colour token values: growing the scale past the roughly fifteen steps that were not enough, reusing existing values where possible, and closing known gaps (a dataviz palette, missing background-fill hover and active steps, and hover and active guidance for non-button clickables like cards).

Auditing across sources

A design system's colour truth lives in several places at once: the token repository, the build packages, the Tokens Studio project, and the Figma libraries. Consolidating on Tokens Studio and a rebuilt CI/CD pipeline is what reduces vendor lock-in and finally makes usage measurable. I ran a cross-source audit so inconsistencies between them surfaced as findings rather than silent drift, and treated any divergence between the exported tokens and Figma as a bug in its own right.

Validating that designers can consume it

The model was built AI-native: one vocabulary, purpose-based names, and a structure a model can reason about without guessing. But a token system only works if the people using it can pick the right variable too. So I designed and ran a round of one-on-one testing sessions with designers, roughly 35 minutes each, across a mix of testers with and without EDS 1.x experience, to confirm the naming and the emphasis model are legible in practice, not just to a model. The developer track, how the same tokens are consumed in code, runs as a separate test.

The session moves in a deliberate order: browse the variables in Figma with no documentation, then read the docs, then rebuild a reference card that uses every kind of token. Browsing first shows whether the names hold up on their own; the docs task exposes the gap between what a designer guessed and what the system means; the rebuild shows which variable they actually reach for. I score two things separately: what I observe while watching, and what the tester rates themselves at the end. A confident wrong pick is the most valuable result, because it means the name is actively misleading, not just unfamiliar.

The variables documentation is the reference artifact handed over mid-session: one table per category, each variable paired with the purpose it serves, so a designer chooses by intent rather than by scanning raw values. What surfaces, names that read as ambiguous, tokens that are right but hard to find, or gaps where designers grab a raw primitive instead, feeds straight back into the model.

My role

This is a team epic, and my part sits across a few tracks. I refined and expanded the static colour token values (the expanded scale, reused values, and gap-closing), contributed to the token variable architecture that fixes the naming and emphasis model, took part in the Tokens Studio exploration that shapes the tooling direction, authored the Figma migration playbook, and designed and ran the designer validation sessions on whether the variables are actually consumable. I work in code with Claude Code, treating accessibility as a design decision rather than a compliance step bolted on at the end.

Migrating without disruption

The hardest constraint is changing the system without disturbing the people already building on it. Part of the point is to reduce the number of variables: consolidating colour on static and semantic (dropping the dynamic set) and decoupling typography, spacing, and corner radius removes duplication and leaves a smaller, clearer set to choose from. But fewer variables cannot mean broken files.

So nothing is edited in place. A renamed or reordered token would cascade through every consumer, so the redefined variables ship alongside the current ones in their own library, and the old set is marked unmaintained rather than deleted. That is the same deprecation pattern EDS already uses for components: teams migrate at their own pace instead of being forced through a breaking change on someone else's schedule.

Status & what's next

This is active work. The token variable architecture and the expanded static colour scale are being defined and moved into Tokens Studio, ahead of a rebuilt CI/CD pipeline. It ships beta first, under current beta naming rather than a "3.0 beta" label, with a stable major (likely 3.0) once it is verified against real components, not this year. Next steps: land the architecture decisions, expand and validate the static scale, run the designer and developer validation rounds, and migrate components colour first, then spacing and typography.