Decision reference

Take it one answer at a time

This page keeps every decision behind Content first 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 Content first's spacing is spacious, or why its voice is conversational.
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.

Informs and publishes What does the product do for the business?
- Occasional visitors Who uses it most?
  - AA What accessibility level do we commit to?
  - They see it fresh each time How do people recall the interface?
  - Anywhere, on any device Where do people use it?
    - Light and dark theming →
    - Touch size accessibility → size.control.default size.48: 3rem
  - Conversational voice and tone →
- Long-form text What is the main content?
  - One idea at a time How much is on one screen?
  - Read start to end What is the main task?
    - Rarely How often do people repeat actions?
    - Attention on the content What must the interface protect?
      - Match the text iconography → size.icon size.16: 1rem
    - Reading comfort Which outcome matters most?
      - Large typography → type.body.font-size font.size.18: 1.125rem
      - Spacious spacing → space.gap.tight space.8: 0.5rem
    - Losing your place What is a costly mistake?
  - One sitting How long is one visit?
- Warm What should the brand feel like?
  - Present How visible is the brand in the interface?
    - Only when the meaning changes components →
  - Balanced color → color.neutral.0 color.stone.dark.0: #14110D
  - Rounded shape → radius.control radius.8: 0.5rem
  - Soft elevation → elevation.card shadow.none: [object Object]
  - Moderate motion → motion.duration.feedback duration.moderate: 200ms
One How many brands or products share the system?
A small team Who maintains the system?
- Lowercase words in paths naming →
Rarely How fast does it change?

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

Who uses it most?

Occasional visitors
- Why
  Most readers arrive from search and visit now and then.
- Because of
  - What does the product do for the business? → Informs and publishes
- What it decided (9)
  Answers it led to (7)
  - What accessibility level do we commit to? → AA
  - How do people recall the interface? → They see it fresh each time
  - Where do people use it? → Anywhere, on any device
  - Motion · What is motion for? → Feedback and guidanceMotion →
  - Iconography · What do icons do? → Actions, status and navigationIconography →
  - Iconography · Where do icons work hardest? → NavigationIconography →
  - Voice and tone · How does it sound? → ConversationalVoice and tone →
  Rules it sets (2)
  - For an empty state, use an invitation, not a dead end. Don't use "No items". An empty list is a chance to show what the product offers.Voice →
  - For a first visit, use one sentence on what is here and why it is worth reading. Don't use a sign-up wall. Occasional readers decide in seconds whether to stay.Voice →

What accessibility level do we commit to?

AA
- Why
  AA is the commitment for a public site.
- Because of
  - Who uses it most? → Occasional visitors
- What it decided (8)
  Answers it led to (3)
  - Typography · How are sizes and line heights defined? → A ratio, line heights in proportionTypography →
  - Accessibility · How many signals carry each meaning? → Two: color and wordAccessibility →
  - Accessibility · What contrast floor do we hold? → AAAccessibility →
  Rules it sets (2)
  - For a field label or column header, use type.label. Don't use type.caption. Caption is too faint for a label people must read.Typography →
  - For keyboard focus, use button/focus-ring at border-width.focus. Don't use removing the outline. Keyboard users must always see where they are.Accessibility →
  Variants it picks (3)
  - Button's focus state. Always visible.Button →
  - Button's disabled state isn't used. Keep it enabled and explain on press: visitors see the interface fresh each time.Button →
  - Field's vertical orientation. Newsletter and search forms: the label above.Field →

What is the main task?

Read start to end
- Why
  People read from start to end.
- Because of
  - What is the main content? → Long-form text
- What it decided (12)
  Answers it led to (8)
  - How often do people repeat actions? → Rarely
  - What must the interface protect? → Attention on the content
  - Which outcome matters most? → Reading comfort
  - What is a costly mistake? → Losing your place
  - Typography · How are sizes and line heights defined? → A ratio, line heights in proportionTypography →
  - Color · Where does color carry meaning first? → Links and actionsColor →
  - Components · Which component families does it need? → Core, plus content and mediaComponents →
  - Components · How does a component earn its place? → A use scenario needs itComponents →
  Rules it sets (3)
  - For a number in a table, use type.body. Don't use a mono font. Tables are rare and read row by row, so digits never need to line up in columns. A mono font would break the reading voice.Typography →
  - For a table row height, use size.row (comfortable). Don't use a compact row. Rows are read, not scanned.Spacing →
  - When no component in the inventory fits, use plain text, a link or a heading. Don't use a new component for one article. Readers come for the words; extra parts pull the eye away from them.Components →
  Variants it picks (1)
  - Item's sm size isn't used. Many readers are on phones, and rows are read, not scanned.Item →

How often do people repeat actions?

Rarely
- Why
  Actions are rare: subscribe, share, save.
- Because of
  - What is the main task? → Read start to end
- What it decided (8)
  Answers it led to (2)
  - Color · How many emphasis levels do actions need? → ThreeColor →
  - Components · How far does the inventory reach? → Only what today's screens useComponents →
  Rules it sets (1)
  - For the action that completes the task, use button primary, one per section. Don't use two primaries side by side. One clear action per section. Two primaries make the reader choose before they have read.Color →
  Variants it picks (5)
  - Button's primary variant. One clear action per section.Button →
  - Button's large size isn't used. Attention belongs to the text: one clear action per section, at the normal size.Button →
  - Field's horizontal orientation isn't used. Forms are rare and short; stacking keeps the reading column.Field →
  - Input group's block-start align isn't used. Search is one line, and forms are rare and short.Input group →
  - Input group's block-end align isn't used. Search is one line, and forms are rare and short.Input group →

What must the interface protect?

Attention on the content
- Why
  Attention belongs to the text.
- Because of
  - What is the main task? → Read start to end
- What it decided (9)
  Answers it led to (5)
  - Color · Which color roles does it need? → Surface, text, action and statusColor →
  - Elevation · What rises above the page? → Only what floatsElevation →
  - Iconography · What icon style? → OutlineIconography →
  - Iconography · How big are icons next to text? → Match the textIconography →
  - Voice and tone · How many tones does it use? → One per momentVoice and tone →
  Variants it picks (4)
  - Button's large size isn't used. Attention belongs to the text: one clear action per section, at the normal size.Button →
  - Field's horizontal orientation isn't used. Forms are rare and short; stacking keeps the reading column.Field →
  - Empty's default variant isn't used. Attention belongs to the text: the invitation is in words, not a picture.Empty →
  - Item's muted variant isn't used. Every row in the reading list weighs the same; attention belongs to the text.Item →

How do people recall the interface?

They see it fresh each time
- Why
  Visitors see the interface fresh each time.
- Because of
  - Who uses it most? → Occasional visitors
- What it decided (9)
  Rules it sets (4)
  - For a selected row or item, use color.surface.selected. Don't use bold text only. A tint shows the choice clearly on warm paper.Color →
  - For a link, use color.text.link, underlined. Don't use color without underline. Readers expect links to be underlined inside text.Color →
  - For an icon with no label, use not used: always add a word. Don't use an icon button. Occasional visitors do not know icons.Iconography →
  - For an action on one row or item, use button ghost with a word. Don't use an icon on its own. Occasional visitors need the word.Iconography →
  Variants it picks (5)
  - Button's ghost variant. Alternatives as a text link, and row actions with a word.Button →
  - Button's icon size isn't used. Occasional visitors do not know icons: always add a word.Button →
  - Button's disabled state isn't used. Keep it enabled and explain on press: visitors see the interface fresh each time.Button →
  - Input group's inline-start align. The search icon before the text, with the visible label above the field.Input group →
  - Input group's inline-end align. The clear button after the text, with a word: occasional visitors do not know icons.Input group →

Scopes

Which states get their own visible value?

Those and pressed
- Why
  Pressed gets its own value 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
  Status is rare; color and a word are enough.
- Because of
  - What accessibility level do we commit to? → AA
- What it decided (8)
  Rules it sets (2)
  - For an error message, use color.status.danger and a plain sentence. Don't use color alone. The sentence says what to fix; color only draws the eye.Color →
  - For a status, use badge pill with a word. Don't use an icon alone. Status is rare, so readers never learn an icon for it. A word is clear the first time.Color →
  Variants it picks (6)
  - Alert's destructive variant. A failed save or sign-up: calm, take the blame, offer the way forward.Alert →
  - Badge's neutral tone. Saved: waiting for you; nothing is wrong.Badge →
  - Badge's info tone isn't used. Topics and reading states need no news tone; status is rare.Badge →
  - Badge's success tone. Finished: you read it to the end.Badge →
  - Badge's warning tone. Out of date: the facts may have changed since it was written.Badge →
  - Badge's danger tone isn't used. Nothing in an article fails; errors are calm sentences, not labels.Badge →

What contrast floor do we hold?

AA
- Why
  AA contrast, with large text helping further.
- 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
  Readers are often on phones.
- Because of
  - Where do people use it? → Anywhere, on any device
- What it decided (6)
  Answers it led to (1)
  - Accessibility · Which states get their own visible value? → Those and pressedAccessibility →
  Rules it sets (1)
  - For the smallest clickable thing, use size.control.default (touch). Don't use a compact control. Many readers are on phones.Accessibility →
  Variants it picks (4)
  - Button's default size. Every button, at touch size: many readers are on phones.Button →
  - Button's compact size isn't used. Many readers are on phones: no compact controls.Button →
  - Item's default size. Every row, at touch size: many readers are on phones.Item →
  - Item's sm size isn't used. Many readers are on phones, and rows are read, not scanned.Item →

Where are the floors hardest to hold?

Long text
- Why
  Long text needs steady contrast and line length.
- Because of
  - What is the main content? → Long-form text
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

Which kinds of copy does it need?

Labels, messages and articles
- Why
  Articles are the product; the UI copy must match them.
- Because of
  - What is the main content? → Long-form text
- What it decided
  It sets the values of the voice and tone tokens: Voice and tone →

How many tones does it use?

One per moment
- Why
  Warm by default, calmer for errors.
- Because of
  - What must the interface protect? → Attention on the content
- What it decided (4)
  Rules it sets (1)
  - For the words of an error, use calm and helpful. Take the blame, offer the way forward. Don't use blaming the reader. A calm error keeps the reader's trust.Voice →
  Variants it picks (3)
  - Alert's destructive variant. A failed save or sign-up: calm, take the blame, offer the way forward.Alert →
  - Toast's danger tone. Calm and helpful: take the blame, offer the way forward.Toast →
  - Badge's danger tone isn't used. Nothing in an article fails; errors are calm sentences, not labels.Badge →

How is the voice defined?

Principles and examples
- Why
  Editors work from principles and examples, not word lists.
- Because of
  - Who maintains the system? → A small team
  - What is the main content? → Long-form text
- What it decided
  It sets the values of the voice and tone tokens: Voice and tone →

How does it sound?

Conversational
- Why
  Talk to one reader, like a good editor.
- Because of
  - Who uses it most? → Occasional visitors
  - What should the brand feel like? → Warm
- What it decided (9)
  Rules it sets (5)
  - For a button label, use a warm verb a reader would say. Don't use "Submit" or "Click here". Buttons are part of the reading voice.Voice →
  - For the words of an error, use calm and helpful. Take the blame, offer the way forward. Don't use blaming the reader. A calm error keeps the reader's trust.Voice →
  - For a success message, use warm and brief, with what happens next. Don't use a bare "Done". A warm close invites the reader back.Voice →
  - For an empty state, use an invitation, not a dead end. Don't use "No items". An empty list is a chance to show what the product offers.Voice →
  - For a confirmation question, use gentle and clear about what changes. Don't use guilt or pressure. Readers come back when leaving felt respectful.Voice →
  Variants it picks (4)
  - Toast's neutral tone. A calm note: You're all caught up.Toast →
  - Toast's success tone. Warm and brief, with what happens next.Toast →
  - Toast's danger tone. Calm and helpful: take the blame, offer the way forward.Toast →
  - Empty's icon variant. A quiet outline icon in a small tile, above a warm invitation to save an article.Empty →

Where do the words matter most?

Articles and guides
- Why
  Most words are in articles and guides.
- Because of
  - What is the main content? → Long-form text
- What it decided
  It sets the values of the voice and tone tokens: Voice and tone →

Take it one answer at a time

Where it starts​

Every question​

Reasons

Scopes

Where it starts

Every question