MCM-52 — Shared Design Tokens

← Back to MCM Design System overview

As a Design Lead,
I want colour, typography, spacing, corner-radius, and other foundational visual values defined once and consumed by all three surfaces,
so that changing a value in one place updates every surface consistently, instead of the surfaces slowly drifting apart.

Acceptance Criteria

• A single, versioned source defines the full token set: colour palette (including light and dark variants), typography scale, spacing scale, corner-radius, and elevation/shadow values.
• All three surfaces (product console, customer portal, marketing site) consume this same source rather than each maintaining its own copy.
• Publishing a new version of the token source is sufficient to update a value everywhere it's used, without hand-editing each surface's own styles.
• Where a surface today defines a value that conflicts with another surface's equivalent (for example, two surfaces currently use different corner-radius values for what's meant to be the same shape), adopting the shared tokens resolves both to the one shared value.
• Both light and dark variants of every colour token are defined and available to every surface, even the surface that doesn't yet offer a dark appearance.
• The token source is documented well enough (see MCM-55) that an engineer can find the right token for a given design decision without asking the Design Lead directly.

---

Technical Design

This introduces one canonical, versioned set of design tokens, published as a shared package and consumed by all three surfaces as the input to their own styling layer. Today each surface defines these values by hand in its own codebase; one surface's copy was manually kept "in sync" with another's at the time it was built but has since silently drifted on at least one value, and there is no shared package of any kind between the three codebases today — this is the first shared dependency introduced across them. Adopting the shared tokens means each surface's local colour/spacing/radius definitions are replaced by the published output of this source rather than removed outright with nothing to replace them.

---

UI / Frontend Changes

• Each surface's existing style definitions (its own colour/spacing/radius/typography values) are replaced with the shared token source's published output rather than a hand-maintained local copy.
• No new end-user-facing screen — this is a foundation layer that other design-system stories and future feature work build on.
• Visual output is unchanged wherever surfaces already agreed on a value; where two surfaces had already disagreed, both converge to the one shared value as part of adopting the tokens.