I built token governance for multi-brand eCommerce: primitive to semantic layers, change review, and per-market overrides without breaking the shared template.
One template carried ninety-plus sub-brands through peak trading seasons with fewer emergency CSS hotfixes. Market launches became override files plus portal updates, not template forks. The same hierarchy powers token export in weableColor today: primitives in the engine, semantics in product UI, stable names QA can grep.
90+ brands · semantic tokens · versioned releases
- 90+
- Sub-brands on one template (Rexel)
- 3 layers
- Primitive · semantic · component
- 37
- Countries · locale-aware overrides
- Versioned
- Token releases with change review
Why token governance fails without layers
Design tokens became trendy; token debt became common. Teams show up with a Figma library and a JSON dump, but checkout buttons still hardcode brand hex because nobody enforced which layer feature code could touch.
Multi-brand commerce makes the failure mode obvious. France needs a blue primary; Germany needs red; Nordics need green; all three share the same button component. Without semantic indirection, you get three button forks or three CSS overrides that break when the shared template updates.
I treat governance as change management for visual intent. Primitives change rarely. Semantics change per brand or theme. Components change when UX patterns change. Blurring those layers is how ninety brands become ninety unmaintainable forks.
Token hierarchy
Figure 1 stacks the three layers I enforce on every engagement. Primitives hold palette steps, spacing scale, and type sizes. They are the only place raw hex and pixel values live. Product code and Figma components should not reference primitives directly except through tooling pipelines.
Semantic tokens map intent: `color.action.primary`, `color.text.muted`, `space.inset.md`. Brand overrides swap semantic targets, not component CSS. When Germany's primary shifts, you update one semantic row; every button, link, and badge that consumes `color.action.primary` moves together.
Component tokens are the narrowest surface: `button.bg.default`, `card.border.subtle`, `nav.link.active`. They exist when a component needs a dedicated alias, but they still resolve through semantics, never through one-off hex in a feature branch.
The breakthrough on engagements like this is banning primitive references in Hybris component SCSS. Code review rejects PRs that introduce raw values; Style Dictionary builds fail if a component token skips the semantic chain.
Three layers
Governance workflow
Figure 2 shows the workflow from proposal to release. A squad proposes a semantic change with rationale (brand refresh, contrast fix, new market). Design systems review checks layer discipline, downstream impact, and portal documentation. Build pipelines compile tokens into platform outputs (CSS variables, Hybris theme packs, Figma library updates). Release notes tag version bumps so markets know which override files to pull.
Hotfixes still happen, but they flow through the same gate. Emergency contrast fixes on checkout CTAs go through semantic overrides, not a production CSS patch that the next template merge would erase.
I pair governance with accessibility audits on the same program. When semantic text colors change, contrast is re-measured on composed components, not on the swatch page alone. That cross-link keeps renewal stories coherent: tokens plus component proof, not two conflicting narratives.
- Proposal → review → build → portal update → tagged release
- No primitive references in component feature code
- Override files per market, shared core template
- Release notes tied to design system version tags
Change gate
Multi-brand sync
Figure 3 is the pattern Rexel scaled and I repeat on distributor programs: one shared core template, per-market semantic override files, single component library. France, Germany, and Nordics each swap `color.action.primary` at the semantic layer while checkout, PLP, and account flows stay byte-identical in structure.
Locale and currency ride alongside visual overrides. Typography stacks that support nine languages share primitive line heights; semantics adjust heading weight per brand without forking HTML templates.
Style-guide portals made overrides legible to non-developers. Market leads saw which semantic tokens their brand owned, which PLP blocks consumed them, and which portal pages updated on a given release tag. That visibility cut Slack negotiations about whose blue was correct.
The same sync model appears in weableColor today: one contrast engine, CSV export of resolved tokens, Figma and VS Code surfaces consuming the same semantic names. Enterprise scale and indie product scale share the hierarchy; only the release cadence differs.
Per-market overrides
Rexel proof at enterprise scale
I led UI for Rexel's global Hybris program: ninety-plus sub-brands, nine-plus languages, thirty-seven countries on one template. Token governance was survival, not a conference talk. Peak trading seasons could not wait for a France-only fork to merge before Black Friday.
Style-guide portals documented typography blocks, PLP patterns, and checkout components with the semantic tokens each block consumed. When a market launched, the work was override files plus portal entries, not a new repository.
SACA's section-first naming came from the same era: if you cannot name the block, you cannot theme it or test it. Tokens name visual intent; SACA names DOM intent. I still ship both together on new surfaces.
Live product: weableColor token export
I dogfood the hierarchy in weableColor. Primitives live in the color engine; product UI references semantic roles for text, surface, and action pairs. CSV export gives teams a portable token sheet that matches what Mission Control scores in Figma.
That export is how I prove governance is not enterprise-only theory. A solo founder workflow still benefits when semantic names stay stable across Figma plugin, VS Code extension, and marketing site.
Contrast fixes flow through semantics: when `color.text.muted` fails on `color.surface.elevated`, I adjust the semantic mapping or the primitive step once, then re-score every component that consumes the pair.
Portal, documentation, and handoff
Tokens without documentation are a zip file engineers ignore. A maintained portal lists each semantic token, allowed values per market, consuming components, and last-changed release tag. Figma libraries mirror the same names so design and code diffs stay aligned.
Handoff to offshore and vendor squads improved because arguments moved from is this the right blue to which semantic token is your PR touching. Code review checklist included layer discipline, portal update, and contrast re-check when text or surface semantics changed.
I still recommend portal investment even for mid-size teams. The cost of one wrongful primitive reference in a shared button component exceeds the cost of a maintained semantic catalog.
RFC template and semver discipline
Every token change starts as a short RFC: token name, tier (primitive, semantic, component), before and after values, consuming components, contrast impact on text pairs, and semver recommendation. Breaking changes (removing a semantic, renaming a component alias) require major bumps and migration notes. Additive semantics minor. Documentation-only portal edits patch.
The RFC template stopped hallway negotiations. Market leads could request a deeper blue; engineering could see blast radius before merge. Design systems council met weekly; emergency hotfixes still filed retro RFCs within forty-eight hours so the changelog stayed honest.
I treat semver like API contracts because tokens are APIs for visual intent. Teams that skip version tags discover drift at the worst moment: a Black Friday deploy where Germany's checkout green came from a primitive someone pasted in a hotfix branch.
- RFC fields: tier, diff, consumers, contrast pairs, semver
- Major: breaking rename or removal; minor: additive semantic
- Retro RFC for hotfixes within 48h of merge
- Visual regression snapshots on top-five brands pre-release
Pairing tokens with accessibility audits
Token governance and component accessibility are one program at enterprise scale. When semantic text colors refresh for a brand pack, I re-run contrast on composed buttons, links, and form labels, not the swatch page. When the accessibility audit flags a failing pair, the fix is usually a semantic mapping adjustment, not a one-off hex in a feature stylesheet.
That pairing is why I cross-link these case studies on the portfolio. Hiring teams ask whether I understand design systems as theory or as ship discipline. The answer is both: tokens name visual intent, audits prove the composed UI still works for keyboard and low-vision users, portals and matrices make the work repeatable.
weableColor closes the loop on my own products: CSV export lists resolved semantic pairs; Mission Control scores the same pairs on Figma layers. Enterprise client and indie product share the hierarchy even when release cadence differs.
Lessons and what ships next
Primitives are implementation detail. Semantics are brand and theme. Components are UX patterns. Mix the layers and governance becomes whack-a-mole.
Override files beat template forks. Markets can launch in parallel because Germany does not wait for France's CSS branch to merge.
Versioned releases create audit trails procurement understands. Tagged token releases paired with component accessibility matrices give enterprise buyers a credible evidence story.
Portals earn their keep when market leads edit semantics without opening SCSS. The portal is not documentation theater; it is the contract offshore vendors sign against.
Next: automated diff reports when semantic tokens change downstream contrast, Figma variable sync hooks into the same release tag, and a public token schema extract for teams evaluating Style Dictionary without Rexel-scale baggage.