Eight months after Northwind acquired Tidewater, its marketing site moved onto Northwind UI. Tidewater’s brand team arrived with a 60-page brand book, a serif typeface, a teal palette and rounded pill buttons. They also arrived with a list of 23 “brand requirements” for components. Our job was to say yes to the brand and no to most of the list, and to make both feel reasonable.
\nThe first conversation set a boundary. A brand changes personality: color palette, typefaces, corner radius, illustration style and voice. A brand doesn’t change behavior or structure: keyboard handling, focus management, spacing scale, layout grids, component APIs, accessibility. Tidewater’s buttons can be teal pills with a serif label. They can’t close dialogs on outside click when Northwind’s don’t, because that’s a product decision, not a brand one.
\nOf the 23 requirements, 15 turned out to be visual and fit into tokens. Six were behavior requests, which went through API review as ordinary proposals for both brands (two were accepted, for both). Two were dropped.
\nSection 2 introduced a brand ramp so dark mode could pick steps. For a full second brand, that ramp grows into its own tier between primitives and semantic tokens:
\nThe brand tier is deliberately small. Northwind’s has 24 tokens: a color ramp from 50 to 900, a heading and a body font family, two radii and a focus-ring color. Semantic tokens point at brand tokens, and components never know a brand exists.
\n:root,\n[data-brand] {\n --nw-color-action-bg: var(--nw-brand-600);\n --nw-color-action-text: var(--nw-white);\n --nw-font-heading: var(--nw-brand-font-heading);\n --nw-radius-control: var(--nw-brand-radius-control);\n}\n\n[data-brand=\"tidewater\"] {\n --nw-brand-600: var(--nw-teal-600);\n --nw-brand-700: var(--nw-teal-700);\n --nw-brand-font-heading: Georgia, 'Times New Roman', serif;\n --nw-brand-radius-control: 999px;\n /* Tidewater's 600 fails contrast with white text: use the darker step. */\n --nw-color-action-bg: var(--nw-brand-700);\n}The selector :root, [data-brand] matters. Remember from the themes lesson that a custom property containing var() is resolved where it is declared. Declared only on :root, --nw-color-action-bg would be computed once with Northwind’s ramp, and a Tidewater section on the same page would inherit Northwind blue. Re-declaring the semantic mappings on every [data-brand] element makes them resolve inside each brand’s scope. That’s what lets Northwind’s co-branded comparison page show both brands side by side.
The last line of the Tidewater block is the interesting one. Northwind’s action color is step 600 of its ramp. Tidewater’s 600 is lighter, so white button text on it fails:
\nfunction luminance(hex) {\n const [r, g, b] = [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)\n .map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4));\n return 0.2126 * r + 0.7152 * g + 0.0722 * b;\n}\nfunction contrast(a, b) {\n const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);\n return (hi + 0.05) / (lo + 0.05);\n}\n\nconst pairs = { 'northwind blue-600': '#1f5ae0', 'tidewater teal-600': '#0d9488', 'tidewater teal-700': '#0f766e' };\nfor (const [name, bg] of Object.entries(pairs)) {\n const ratio = contrast(bg, '#ffffff');\n console.log(`${name} + white text: ${ratio.toFixed(2)}:1 ${ratio >= 4.5 ? 'pass' : 'FAIL'}`);\n}So Tidewater maps the same semantic role to a different step. This is why the brand tier doesn’t just swap palettes blindly: each brand’s semantic mapping is designed and checked. The contrast check in Northwind’s pipeline runs every documented pair in every brand and theme, and it caught this before the brand team saw a single button.
\n\nEach surface loads what it needs. The marketing sites set data-brand on <html> and load only their brand’s CSS file, generated by the pipeline from primitives + brand-tidewater + semantic. The dispatch app, which shows both brands in its admin views, loads both blocks. In Figma, the same structure lives in extended collections, so Tidewater’s designers see the shared semantic variables with their brand’s values.
Every brand also doubles the test matrix. With two brands, two color schemes and two densities, each core component renders in eight combinations in the visual suite from Section 4. That sounds expensive until you remember the alternative: a Tidewater designer discovering in production that the dark-mode focus ring is invisible on teal. Machines are cheap reviewers for combinations; humans only look at the diffs.
\n\nIn the exercise, you add Tidewater to a page where both brands appear side by side. Next, you measure whether all of this is actually being used.
\n","toc":[{"id":"sec-1","text":"What a brand may change","level":2},{"id":"sec-2","text":"The brand tier","level":2},{"id":"sec-3","text":"Contrast is per brand","level":2},{"id":"sec-4","text":"Delivering brands","level":2}],"takeaways":["A brand changes personality (color ramp, typefaces, shape) through a small set of brand tokens; behavior, spacing and accessibility stay shared.","Put a brand tier between primitives and semantic tokens, so each brand points the same semantic names at its own palette.","Contrast must be checked per brand, and a brand may need a different step of its ramp for the same semantic role.","When brands can appear side by side, re-declare semantic mappings under the brand selector so they resolve inside each brand’s scope."],"further":[{"title":"Understanding SC 1.4.3 Contrast (Minimum) (W3C)","url":"https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html"},{"title":"Extend a variable collection (Figma)","url":"https://help.figma.com/hc/en-us/articles/36346281624471-Extend-a-variable-collection"},{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"}],"quiz":[{"q":"Tidewater’s brand team asks for its Dialog to close when people click outside, while Northwind’s doesn’t. How should the system respond?
","options":[{"text":"Add abrand prop to Dialog that switches the behavior.","why":"Brand-specific behavior inside components means every component must know about every brand, which doesn’t scale past two."},{"text":"Fork Dialog for Tidewater.","why":"Two Dialogs drift apart in fixes and accessibility, which is the cost the system exists to avoid."},{"text":"Treat it as a product behavior question for both brands, decided in API review; brands change look and voice, not behavior.","why":"Correct. If outside-click closing is right, it’s right for both brands; if not, it’s wrong for both."},{"text":"Let Tidewater override the Dialog’s JavaScript with a theme token.","why":"Tokens describe visual values; behavior hidden in tokens is untestable and surprising."}],"answer":2},{"q":"Tidewater’s teal-600 on white text has a contrast ratio of 3.74:1. What should the Tidewater mapping for --nw-color-action-bg be?
On the co-branded comparison page, a Tidewater section’s buttons are still Northwind blue, although [data-brand="tidewater"] sets --nw-brand-600 correctly. What’s missing?
--nw-color-action-bg is only declared on :root, so it was resolved with Northwind’s ramp at the root.","why":"Correct. Re-declaring the semantic mappings under [data-brand] makes them resolve inside each brand’s section."},{"text":"data-brand attributes only work on <html>.","why":"Attribute selectors match any element; the problem is where the semantic token is computed."},{"text":"The button needs a .tidewater class.","why":"Brand-aware classes on components are exactly what the token tiers avoid."},{"text":"Custom properties can’t be overridden twice on one page.","why":"Custom properties can be redeclared at any level; each element sees its nearest declaration."}],"answer":0}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"The co-branded comparison page shows both brands side by side, each in a section with its own data-brand. Add the Tidewater brand without touching the component rules:
--nw-font-georgia),999px radius),--nw-teal-700, because teal-600 fails contrast with white text,Right now the semantic tier is only declared on :root. Think about where it gets resolved.
[data-brand="tidewater"] { … } block that points the brand tokens (--nw-brand-font-heading, --nw-brand-radius-control and the ramp) at Tidewater values.","Brand tokens alone won’t reach the section: the semantic tokens were computed on :root with Northwind’s values. Change the semantic rule’s selector to :root, [data-brand].","Inside the Tidewater block, also map --nw-color-action-bg to var(--nw-brand-700)."],"explanation":"The brand block only swaps brand-tier values, plus one semantic mapping that Tidewater genuinely needs for contrast. Re-declaring the semantic tier under [data-brand] is what makes each section compute --nw-color-action-bg, --nw-font-heading and --nw-radius-control from its own brand tokens, instead of inheriting values already resolved at the root. The components never mention a brand, so a third brand is one more block.