Decision reference

Take it one answer at a time

This page keeps every decision behind Accessible 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 Accessible first's spacing is spacious, 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.

Serves the public What does the product do for the business?
- Everyone, including people with disabilities Who uses it most?
  - AAA What accessibility level do we commit to?
    - Light and dark theming →
  - One idea at a time How much is on one screen?
  - Low effort to understand What must the interface protect?
    - Calm and clear What should the brand feel like?
      - Balanced color → color.neutral.0 color.gray.dark.0: #0A0A0A
      - Slightly rounded shape → radius.control radius.6: 0.375rem
    - Quiet How visible is the brand in the interface?
    - Spacious spacing → space.gap.tight space.12: 0.75rem
  - Anywhere, on any device Where do people use it?
  - Large typography → type.body.font-size font.size.19: 1.1875rem
  - Moderate motion → motion.duration.feedback duration.moderate: 200ms
  - Larger than the text iconography → size.icon size.20: 1.25rem
  - Large accessibility → size.control.default size.52: 3.25rem
  - Plain and direct voice and tone →
  - Only when the meaning changes components →
- Forms and tasks What is the main content?
  - Complete a form What is the main task?
    - Completion without errors Which outcome matters most?
    - A task that fails What is a costly mistake?
    - One sitting How long is one visit?
- Rarely How often do people repeat actions?
  - They see it fresh each time How do people recall the interface?
One How many brands or products share the system?
A platform 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?

Everyone, including people with disabilities
- Why
  Everyone, including people with low vision, motor and cognitive needs.
- Because of
  - What does the product do for the business? → Serves the public
- What it decided (20)
  Answers it led to (18)
  - What accessibility level do we commit to? → AAA
  - How much is on one screen? → One idea at a time
  - What must the interface protect? → Low effort to understand
  - Where do people use it? → Anywhere, on any device
  - Typography · How large is body text? → LargeTypography →
  - Spacing · Which spacing roles does it need? → Gaps, insets and row heightsSpacing →
  - Spacing · How many densities exist? → OneSpacing →
  - Motion · What is motion for? → Feedback onlyMotion →
  - Motion · How is easing defined? → Standard ease-outMotion →
  - Motion · How fast does feedback feel? → ModerateMotion →
  - Iconography · What icon style? → FilledIconography →
  - Iconography · How big are icons next to text? → Larger than the textIconography →
  - Accessibility · What is the smallest target? → LargeAccessibility →
  - Voice and tone · How is the voice defined? → Rules and a word listVoice and tone →
  - Voice and tone · How does it sound? → Plain and directVoice and tone →
  - Components · Which component families does it need? → Actions, forms, feedback, overlays, layout and navigationComponents →
  - Components · How does a component earn its place? → It works for everyone, with any device and assistive technologyComponents →
  - Components · When does a component get another look? → Only when the meaning changesComponents →
  Rules it sets (2)
  - For a number in a table, use type.body. Don't use a small or mono font. Every number must be readable at large size.Typography →
  - When no component in the inventory fits, use a native HTML element with a label and a hint. Don't use a custom widget that needs hover, drag or precise pointing. Native elements work with every assistive technology without extra work.Components →

What accessibility level do we commit to?

AAA
- Why
  AAA where it applies; nobody is left out.
- Because of
  - Who uses it most? → Everyone, including people with disabilities
- What it decided (22)
  Answers it led to (10)
  - Typography · How are sizes and line heights defined? → A ratio, line heights in proportionTypography →
  - Color · How is the palette defined? → Neutrals and one brand rampColor →
  - Elevation · What rises above the page? → NothingElevation →
  - Elevation · What separates groups on the page? → LinesElevation →
  - Theming · Which modes ship? → Light and darkTheming →
  - Accessibility · Which states get their own visible value? → All, including loadingAccessibility →
  - Accessibility · How many signals carry each meaning? → Three: color, icon and wordAccessibility →
  - Accessibility · What contrast floor do we hold? → AAA for textAccessibility →
  - Components · How far does the inventory reach? → Only what today's screens useComponents →
  - Components · How does a component earn its place? → It works for everyone, with any device and assistive technologyComponents →
  Rules it sets (3)
  - For a field label or column header, use type.label, above the field, always visible. Don't use a placeholder as the label. Labels must stay visible while typing.Typography →
  - For a link, use color.text.link, underlined. Don't use color only. Underline works without color perception.Color →
  - For keyboard focus, use button/focus-ring at border-width.focus, with an offset. Don't use a thin or faint outline. Focus must be seen by everyone.Accessibility →
  Variants it picks (9)
  - Button's danger variant. The confirm of a delete, always with the verb and an icon, so color is never the only cue.Button →
  - Button's focus state. Seen by everyone: the focus ring with an offset.Button →
  - Button's disabled state isn't used. Keep it enabled and explain on press: nobody is left out, and nobody remembers the interface from last time.Button →
  - Field's vertical orientation. Every question: the label above the field, always visible.Field →
  - Field's horizontal orientation isn't used. Labels stay above the field, visible while typing and in the same place on any screen.Field →
  - Input group's inline-start align. A currency sign before the amount, with the label still above the field.Input group →
  - Input group's inline-end align. A unit after the value, as a word people can read, with the label still above the field.Input group →
  - Input group's block-start align isn't used. The label stays above the field, outside it, always visible.Input group →
  - Input group's block-end align isn't used. Hints and errors sit in the field layout, in the same place on every question.Input group →

What must the interface protect?

Low effort to understand
- Why
  Low effort to understand each step.
- Because of
  - Who uses it most? → Everyone, including people with disabilities
- What it decided (15)
  Answers it led to (10)
  - What should the brand feel like? → Calm and clear
  - How visible is the brand in the interface? → Quiet
  - Typography · Which text roles does it need? → Core: heading, body, labelTypography →
  - Typography · How many steps does the type scale take? → Only the steps the screens needTypography →
  - Color · Which color roles does it need? → Surface, text, action and statusColor →
  - Color · How many emphasis levels do actions need? → TwoColor →
  - Spacing · How are spacing steps defined? → Big, even stepsSpacing →
  - Spacing · How dense is the layout? → SpaciousSpacing →
  - Shape · Which shape roles does it need? → Controls, badges and containersShape →
  - Voice and tone · How many tones does it use? → OneVoice and tone →
  Rules it sets (3)
  - For a page title, use type.title. Don't use type.display. The same title size on every page tells people where they are. The display size changes from page to page and pushes the content down.Typography →
  - For a paragraph or help text, use type.body, short sentences. Don't use type.caption. Large text and short lines lower effort.Typography →
  - For a first visit, use say how many steps there are and how long it takes. Don't use marketing copy. Knowing the length lowers effort and anxiety.Voice →
  Variants it picks (2)
  - Alert's default variant. Important notes that stay on the page while people answer.Alert →
  - Empty's default variant isn't used. The brand stays out of the way: words say what will appear and how to start.Empty →

How do people recall the interface?

They see it fresh each time
- Why
  Nobody remembers the interface from last time.
- Because of
  - How often do people repeat actions? → Rarely
- What it decided (8)
  Answers it led to (1)
  - Iconography · What do icons do? → Actions and statusIconography →
  Rules it sets (2)
  - For an alternative or cancel, use button secondary. Don't use a text link. Every action looks like a button people can find.Color →
  - For an action on one row or item, use button secondary with a word. Don't use an icon on its own. A word says what will happen.Iconography →
  Variants it picks (5)
  - Button's secondary variant. Every other action, always with a word: alternatives, row actions, and the first step of a delete.Button →
  - Button's ghost variant isn't used. Every action looks like a button people can find.Button →
  - Button's disabled state isn't used. Keep it enabled and explain on press: nobody is left out, and nobody remembers the interface from last time.Button →
  - Field's responsive orientation isn't used. One layout on every device, so people meet the same form every time.Field →
  - Toggle's default variant isn't used. Every action looks like a control people can find, so the toggle keeps its border.Toggle →

Which outcome matters most?

Completion without errors
- Why
  Completion without errors is the measure.
- Because of
  - What is the main task? → Complete a form
- What it decided (5)
  Answers it led to (2)
  - Color · Where does color carry meaning first? → Links and actionsColor →
  - Voice and tone · Where do the words matter most? → Form steps and errorsVoice and tone →
  Rules it sets (1)
  - For a success message, use confirm what happened and what comes next. Don't use a confirmation with no next step. People need to know the task is finished and what happens now.Voice →
  Variants it picks (2)
  - Alert's default variant. Important notes that stay on the page while people answer.Alert →
  - Badge's success tone. A finished task, with a filled icon and a word.Badge →

What is a costly mistake?

A task that fails
- Why
  A failed form can cost someone a benefit.
- Because of
  - What is the main task? → Complete a form
- What it decided (8)
  Rules it sets (3)
  - For an error message, use color.status.danger, an icon and a sentence next to the field. Don't use color alone. People must know what went wrong and where.Color →
  - For a delete or remove, use button secondary, then a confirm page with Button danger. Don't use button primary. A confirm step prevents a costly error.Color →
  - For a confirmation question, use say what will happen in plain words, and offer a way back. Don't use a double negative. Plain words prevent a choice people did not mean.Voice →
  Variants it picks (5)
  - Button's secondary variant. Every other action, always with a word: alternatives, row actions, and the first step of a delete.Button →
  - Button's danger variant. The confirm of a delete, always with the verb and an icon, so color is never the only cue.Button →
  - Alert's destructive variant. Errors, with what went wrong, where, and exactly how to fix it, next to the field.Alert →
  - Badge's warning tone. A risk people can still fix before they finish, with an icon and a word.Badge →
  - Badge's danger tone. A failure that blocks the task, with a filled icon and a word; an alert says how to fix it.Badge →

Scopes

What rises above the page?

Nothing
- Why
  Flat is easier to read at high zoom.
- Because of
  - What accessibility level do we commit to? → AAA
- What it decided (4)
  Answers it led to (3)
  - Elevation · How many shadow levels exist? → NoneElevation →
  - Elevation · How soft are shadows? → No shadowsElevation →
  - Elevation · Where does elevation show? → Dialogs onlyElevation →
  Rules it sets (1)
  - For a card on the page, use a strong border, no shadow. Don't use a shadow. Shadows are hard to see; borders are not.Elevation →

How many shadow levels exist?

None
- Why
  No shadows.
- Because of
  - Elevation · What rises above the page? → Nothing
- What it decided
  It sets the values of the elevation tokens: Elevation →

What separates groups on the page?

Lines
- Why
  Strong borders separate groups at any zoom.
- Because of
  - What accessibility level do we commit to? → AAA
- What it decided (5)
  Rules it sets (1)
  - Between page sections, use space.gap.section. Don't use a thin line. Space is easy to see; thin lines are not.Spacing →
  Variants it picks (4)
  - Item's default variant isn't used. A row with no border is hard to see at high zoom; borders do the work.Item →
  - Item's outline variant. Each saved application, with a strong border that separates it at any zoom.Item →
  - Toggle's default variant isn't used. Every action looks like a control people can find, so the toggle keeps its border.Toggle →
  - Toggle's outline variant. Every toggle, with a strong border and a word, so it reads as a control at any zoom.Toggle →

How soft are shadows?

No shadows
- Why
  No shadows; borders do the work.
- Because of
  - Elevation · What rises above the page? → Nothing
- What it decided (2)
  Variants it picks (2)
  - Item's default variant isn't used. A row with no border is hard to see at high zoom; borders do the work.Item →
  - Item's outline variant. Each saved application, with a strong border that separates it at any zoom.Item →

Where does elevation show?

Dialogs only
- Why
  Only dialogs separate, with a dimmed page and a border.
- Because of
  - Elevation · What rises above the page? → Nothing
- What it decided (1)
  Rules it sets (1)
  - For a menu or dialog, use a strong border and a dimmed page. Don't use a shadow only. The dimmed page makes the dialog obvious.Elevation →

Which states get their own visible value?

All, including loading
- Why
  Every state, including loading, gets its own value.
- Because of
  - What accessibility level do we commit to? → AAA
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

How many signals carry each meaning?

Three: color, icon and word
- Why
  Never color alone.
- Because of
  - What accessibility level do we commit to? → AAA
- What it decided (10)
  Answers it led to (1)
  - Iconography · Where do icons work hardest? → Status and messagesIconography →
  Rules it sets (3)
  - For a selected row or item, use color.surface.selected and a check icon. Don't use color alone. Selection never relies on color alone.Color →
  - For an error message, use color.status.danger, an icon and a sentence next to the field. Don't use color alone. People must know what went wrong and where.Color →
  - For a status, use badge with an icon and a word. Don't use color alone. Status must survive no color and a screen reader.Color →
  Variants it picks (6)
  - Alert's destructive variant. Errors, with what went wrong, where, and exactly how to fix it, next to the field.Alert →
  - Badge's neutral tone. A waiting state, such as an application saved to resume later, with an icon and a word.Badge →
  - Badge's success tone. A finished task, with a filled icon and a word.Badge →
  - Badge's warning tone. A risk people can still fix before they finish, with an icon and a word.Badge →
  - Badge's danger tone. A failure that blocks the task, with a filled icon and a word; an alert says how to fix it.Badge →
  - Item's muted variant isn't used. A fill alone marks a row by color; status goes in a badge with an icon and a word.Item →

What contrast floor do we hold?

AAA for text
- Why
  AAA contrast for text.
- Because of
  - What accessibility level do we commit to? → AAA
- What it decided (1)
  Rules it sets (1)
  - For a value with no token, use the closest semantic token, then ask for a new one. Don't use a raw value in the component. A raw value skips the contrast checks every token passed.Naming →

What is the smallest target?

Large
- Why
  Large targets for tremor and touch.
- Because of
  - Who uses it most? → Everyone, including people with disabilities
- What it decided (10)
  Rules it sets (2)
  - For a table row height, use size.row (large). Don't use a compact row. Large rows are easy to read and tap.Spacing →
  - For the smallest clickable thing, use size.control.default (large). Don't use touch-minimum size. Large targets help people with motor needs.Accessibility →
  Variants it picks (8)
  - Button's default size. Every button. Large targets help people with motor needs.Button →
  - Button's compact size isn't used. Large targets help people with motor needs; nothing smaller.Button →
  - Button's large size isn't used. The default size is already large for motor needs; a bigger one adds nothing.Button →
  - Item's default size. Every row. Large targets help people with motor needs.Item →
  - Item's sm size isn't used. Large targets help people with motor needs; nothing smaller.Item →
  - Toggle's default size. Every toggle. Large targets help people with motor needs.Toggle →
  - Toggle's sm size isn't used. Large targets help people with motor needs; nothing smaller.Toggle →
  - Toggle's lg size isn't used. The default size is already large for motor needs; a bigger one adds nothing.Toggle →

Where are the floors hardest to hold?

Forms
- Why
  Forms are where people are blocked.
- Because of
  - What is the main content? → Forms and tasks
- What it decided
  It sets the values of the accessibility tokens: Accessibility →

Which kinds of copy does it need?

Labels, messages and help
- Why
  Hints and help text carry people through each step.
- Because of
  - What is the main content? → Forms and tasks
- What it decided (1)
  Variants it picks (1)
  - Input group's block-end align isn't used. Hints and errors sit in the field layout, in the same place on every question.Input group →

How many tones does it use?

One
- Why
  One plain tone everywhere; no surprises.
- Because of
  - What must the interface protect? → Low effort to understand
- What it decided
  It sets the values of the voice and tone tokens: Voice and tone →

How is the voice defined?

Rules and a word list
- Why
  A word list of common words, with terms to avoid.
- Because of
  - Who uses it most? → Everyone, including people with disabilities
- What it decided (1)
  Rules it sets (1)
  - For a button label, use a common verb that says what happens next. Don't use "Submit" or "Proceed". Common words are understood by the most people.Voice →

How does it sound?

Plain and direct
- Why
  Every sentence is easy to read on the first try.
- Because of
  - Who uses it most? → Everyone, including people with disabilities
  - What should the brand feel like? → Calm and clear
- What it decided (7)
  Rules it sets (5)
  - For a button label, use a common verb that says what happens next. Don't use "Submit" or "Proceed". Common words are understood by the most people.Voice →
  - For the words of an error, use say what is wrong, where, and exactly how to fix it. Don't use "Invalid input". People must be able to fix the error without help.Voice →
  - For a success message, use confirm what happened and what comes next. Don't use a confirmation with no next step. People need to know the task is finished and what happens now.Voice →
  - For an empty state, use explain what will appear here and how to start. Don't use a blank page. A blank page leaves people unsure if something failed.Voice →
  - For a confirmation question, use say what will happen in plain words, and offer a way back. Don't use a double negative. Plain words prevent a choice people did not mean.Voice →
  Variants it picks (2)
  - Alert's destructive variant. Errors, with what went wrong, where, and exactly how to fix it, next to the field.Alert →
  - Empty's icon variant. A filled icon in a tile, beside words that say what will appear here and how to start.Empty →

Where do the words matter most?

Form steps and errors
- Why
  Words decide whether a form gets finished.
- Because of
  - Which outcome matters most? → Completion without errors
- What it decided (1)
  Rules it sets (1)
  - For the words of an error, use say what is wrong, where, and exactly how to fix it. Don't use "Invalid input". People must be able to fix the error without help.Voice →

Take it one answer at a time

Where it starts​

Every question​

Reasons

Scopes

Where it starts

Every question