Decision reference

Take it one answer at a time

This page keeps every decision behind Multi-brand in one place: 78 answers and what each one shaped. It's a reference, not a reading list. Most days you only need one answer.

Three easy ways in

Take a minute with Where it starts. It shows the few first answers the rest grow from.
Open one section when you wonder why. For example, why Multi-brand's spacing is comfortable, or why its voice is plain and direct.
Come in from a component page. Each one links here, to the answers that shaped it.

Everything else can wait until you need it.

Question
Answer
Why, and what it came from
Design values
In the UI

Where it starts

The first answers lead to the rest. Each branch is an answer that follows from the one above it.

Sells and converts What does the product do for the business?
- Many How many brands or products share the system?
  - Looking off-brand What is a costly mistake?
  - Neutral and adaptable What should the brand feel like?
    - Regular typography → type.body.font-size font.size.16: 1rem
    - Balanced color → color.neutral.0 color.slate-deep.dark.0: #020617
    - Soft elevation → elevation.card shadow.card-dark: [object Object]
    - Moderate motion → motion.duration.feedback duration.moderate: 200ms
    - Plain and direct voice and tone →
  - Present How visible is the brand in the interface?
    - Also for emphasis and size components →
  - A platform team Who maintains the system?
    - Lowercase words in paths naming →
  - Every month How fast does it change?
  - Rounded shape → radius.control radius.999: 9999px
  - Match the text iconography → size.icon size.16: 1rem
  - Light and dark theming →
- Customers who choose us Who uses it most?
  - AA What accessibility level do we commit to?
  - Sometimes How often do people repeat actions?
    - They see it fresh each time How do people recall the interface?
  - Low effort to understand What must the interface protect?
  - Anywhere, on any device Where do people use it?
    - Touch size accessibility → size.control.default size.44: 2.75rem
- Forms and tasks What is the main content?
  - A moderate amount How much is on one screen?
    - Comfortable spacing → space.gap.tight space.8: 0.5rem
- Complete a form What is the main task?
  - Completion without errors Which outcome matters most?
  - A few minutes How long is one visit?

Every question

All 78, by section, in the order every scheme answers them. Each answer shows why, what it came from, and every design decision it made. The menu in the sidebar opens a section; its number is how many decisions that section made.

Reasons

What does the product do for the business?

Sells and converts
- Why
  A company sells several products under several brands.
- Because of
  Nothing before it. It's one of the first answers.
- What it decided (4)
  Answers it led to (4)
  - How many brands or products share the system? → Many
  - Who uses it most? → Customers who choose us
  - What is the main content? → Forms and tasks
  - What is the main task? → Complete a form

How many brands or products share the system?

Many
- Why
  Three brands share one system today, more tomorrow.
- Because of
  - What does the product do for the business? → Sells and converts
- What it decided (30)
  Answers it led to (30)
  - What is a costly mistake? → Looking off-brand
  - What should the brand feel like? → Neutral and adaptable
  - How visible is the brand in the interface? → Present
  - Who maintains the system? → A platform team
  - How fast does it change? → Every month
  - Typography · Which text roles does it need? → Core: heading, body, labelTypography →
  - Typography · How many steps does the type scale take? → One step per kind of textTypography →
  - Typography · How are sizes and line heights defined? → A ratio, line heights in proportionTypography →
  - Color · Which color roles does it need? → Those and brand accentsColor →
  - Color · How is the palette defined? → Shared neutrals, a ramp per brandColor →
  - Spacing · How many densities exist? → OneSpacing →
  - Spacing · How are spacing steps defined? → Small steps, on a 4px gridSpacing →
  - Shape · Which shape roles does it need? → Controls, badges and containersShape →
  - Shape · How are corners set? → Set by each brandShape →
  - Shape · What should control corners say? → RoundedShape →
  - Motion · How is easing defined? → Standard ease-outMotion →
  - Iconography · What icon style? → OutlineIconography →
  - Iconography · How big are icons next to text? → Match the textIconography →
  - Theming · What can a theme change? → Mode and brandTheming →
  - Theming · How many themes ship? → SeveralTheming →
  - Theming · How are brands handled? → Brands as modesTheming →
  - Theming · Which modes ship? → Light and darkTheming →
  - Accessibility · How many signals carry each meaning? → Two: color and wordAccessibility →
  - Accessibility · Where are the floors hardest to hold? → Brand colorAccessibility →
  - Naming · What gets a name? → Tokens and component keysNaming →
  - Naming · How are decisions named? → By roleNaming →
  - Naming · What do components read? → Component keysNaming →
  - Voice and tone · Which kinds of copy does it need? → Labels, messages and headlinesVoice and tone →
  - Voice and tone · How many tones does it use? → One per brandVoice and tone →
  - Voice and tone · How is the voice defined? → A shared core, brand tone on topVoice and tone →

Scopes

What can a theme change?

Mode and brand
- Why
  Brand and mode both change.
- Because of
  - How many brands or products share the system? → Many
- What it decided (1)
  Answers it led to (1)
  - Theming · What changes when the theme changes? → Colors, type and shapeTheming →

How many themes ship?

Several
- Why
  Three brands in light and dark: six themes.
- Because of
  - How many brands or products share the system? → Many
  - Theming · Which modes ship? → Light and dark
- What it decided
  It sets the values of the theming tokens: Theming →

How are brands handled?

Brands as modes
- Why
  Brands are theme modes over shared semantics.
- Because of
  - How many brands or products share the system? → Many
- What it decided (12)
  Rules it sets (7)
  - For a page title, use type.title in the brand font. Don't use a brand-specific style. Roles stay shared; only the brand font changes.Typography →
  - For a selected row or item, use color.surface.selected (from the brand). Don't use a fixed blue. Selection follows the brand color.Color →
  - For a link, use color.text.link (from the brand). Don't use a fixed blue. Links take the brand's color, so they look native in each brand. A fixed blue would clash with some brands.Color →
  - For the corners of buttons and inputs, use radius.control (set by the brand). Don't use a hard-coded radius. Each brand sets its own corner through the theme.Shape →
  - For the shape of a status badge, use radius.badge (set by the brand). Don't use a hard-coded shape. The brand sets the badge shape.Shape →
  - When someone switches to dark, use the dark mode of the active brand. Don't use one dark theme for all brands. Every brand ships light and dark.Theming →
  - For a value with no token, use the closest semantic token, then ask for a new one. Don't use a raw value or a brand primitive in the component. A raw value shows the same in every brand, so it breaks the theme.Naming →
  Variants it picks (5)
  - Sidebar's default variant. Account-area menu items, the same in every brand.Sidebar →
  - Sidebar's outline variant isn't used. Brands change color and corners, not the structure of the menu.Sidebar →
  - Empty's default variant isn't used. Shared structure in every brand: no brand pictures in empty states.Empty →
  - Item's muted variant. The current setting, with a soft fill from the brand.Item →
  - Toggle's outline variant. A single toggle, with a border so it reads as a control in every brand.Toggle →

Which modes ship?

Light and dark
- Why
  Light and dark ship for every brand.
- Because of
  - How many brands or products share the system? → Many
- What it decided (2)
  Answers it led to (1)
  - Theming · How many themes ship? → SeveralTheming →
  Rules it sets (1)
  - When someone switches to dark, use the dark mode of the active brand. Don't use one dark theme for all brands. Every brand ships light and dark.Theming →

What changes when the theme changes?

Colors, type and shape
- Why
  A brand switch changes colors, fonts and corners.
- Because of
  - Theming · What can a theme change? → Mode and brand
- What it decided
  It sets the values of the theming tokens: Theming →

Which states get their own visible value?

Those and pressed
- Why
  Pressed for touch.
- Because of
  - Accessibility · What is the smallest target? → Touch size
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

How many signals carry each meaning?

Two: color and word
- Why
  Brand colors vary, so meaning needs a word.
- Because of
  - How many brands or products share the system? → Many
- What it decided (8)
  Rules it sets (2)
  - For an error message, use color.status.danger and a sentence. Don't use the brand color. Status colors are shared, never branded.Color →
  - For a status, use badge with a word. Don't use a brand color as status. Brand hues vary, so meaning needs a word.Color →
  Variants it picks (6)
  - Badge's neutral tone. Trial: the plan works and billing has not started.Badge →
  - Badge's info tone. Renews in 3 days: a payment is coming; nothing has gone wrong.Badge →
  - Badge's success tone. Active: the plan is paid and running.Badge →
  - Badge's warning tone isn't used. No plan or order state sits between running and failed; a coming renewal is news, not a warning.Badge →
  - Badge's danger tone. Card declined: the payment failed, so the plan will stop.Badge →
  - Alert's destructive variant. A billing problem such as a declined card: plain and specific, the same in every brand.Alert →

What contrast floor do we hold?

AA
- Why
  AA in every brand and mode.
- Because of
  - What accessibility level do we commit to? → AA
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

What is the smallest target?

Touch size
- Why
  Customers sign up on phones.
- Because of
  - Where do people use it? → Anywhere, on any device
- What it decided (11)
  Answers it led to (1)
  - Accessibility · Which states get their own visible value? → Those and pressedAccessibility →
  Rules it sets (2)
  - For an icon with no label, use not used: always add a word; a popover explains a fee. Don't use an icon button with a hover hint. On touch screens hover hints never show; a word says what will happen.Iconography →
  - For the smallest clickable thing, use size.control.default (touch). Don't use a compact control. Customers are often on phones.Accessibility →
  Variants it picks (8)
  - Button's default size. Every button, at touch size: customers are often on phones.Button →
  - Button's compact size isn't used. Customers are often on phones: no compact controls.Button →
  - Button's icon size isn't used. Customers use any device and hover hints never show on touch, so every button has a word.Button →
  - Field's horizontal orientation isn't used. Customers sign up on phones: labels stay above.Field →
  - Item's default size. Every row, at touch size: customers are often on phones.Item →
  - Item's sm size isn't used. One density across brands, at touch size.Item →
  - Toggle's default size. Every toggle, at touch size: customers are often on phones.Toggle →
  - Toggle's sm size isn't used. Customers are often on phones: no compact controls.Toggle →

Where are the floors hardest to hold?

Brand color
- Why
  Brand colors must pass in every mode.
- Because of
  - How many brands or products share the system? → Many
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

Which kinds of copy does it need?

Labels, messages and headlines
- Why
  Each brand has headlines on top of shared UI copy.
- Because of
  - How many brands or products share the system? → Many
- What it decided
  It sets the values of the voice and tone tokens: Voice and tone →

How many tones does it use?

One per brand
- Why
  A shared core, with a tone per brand.
- Because of
  - How many brands or products share the system? → Many
- What it decided (2)
  Rules it sets (1)
  - For a success message, use brand tone allowed: Aster calm, Birch friendly, Coral upbeat. Don't use the same flat line in every brand. Success is a safe moment for brand tone.Voice →
  Variants it picks (1)
  - Toast's success tone. Brand tone allowed: Aster calm, Birch friendly, Coral upbeat.Toast →

How is the voice defined?

A shared core, brand tone on top
- Why
  Errors and confirmations are shared; brand tone sits on top.
- Because of
  - How many brands or products share the system? → Many
  - Who maintains the system? → A platform team
- What it decided (8)
  Rules it sets (4)
  - For a button label, use a shared verb; the brand may choose the headline verb. Don't use brand slang on account actions. Shared labels keep the account area the same in every brand.Voice →
  - For the words of an error, use shared across brands: plain and specific. Don't use brand tone in errors. Errors read the same in every brand, so support can help anyone.Voice →
  - For an empty state, use shared structure, brand words. Don't use a different structure per brand. The structure is the shared core; words carry the brand.Voice →
  - For a confirmation question, use shared across brands: plain and specific. Don't use brand tone when something is lost. Loss is never the moment for personality.Voice →
  Variants it picks (4)
  - Alert's destructive variant. A billing problem such as a declined card: plain and specific, the same in every brand.Alert →
  - Toast's neutral tone. A shared line with brand words.Toast →
  - Toast's danger tone. Shared across brands: plain and specific.Toast →
  - Empty's default variant isn't used. Shared structure in every brand: no brand pictures in empty states.Empty →

How does it sound?

Plain and direct
- Why
  The shared core is plain and direct.
- Because of
  - What should the brand feel like? → Neutral and adaptable
- What it decided (2)
  Rules it sets (1)
  - For the words of an error, use shared across brands: plain and specific. Don't use brand tone in errors. Errors read the same in every brand, so support can help anyone.Voice →
  Variants it picks (1)
  - Toast's danger tone. Shared across brands: plain and specific.Toast →

Where do the words matter most?

Headlines and buttons
- Why
  Brand tone shows in headlines and buttons.
- Because of
  - How visible is the brand in the interface? → Present
- What it decided (1)
  Rules it sets (1)
  - For a first visit, use brand tone in the first headline only. Don't use brand tone in every line. One headline carries the brand; the rest stays shared.Voice →

Take it one answer at a time

Where it starts​

Every question​

Reasons

Scopes

Where it starts

Every question