Decision reference
Take it one answer at a time
This page keeps every decision behind Dense data 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 Dense data's spacing is compact, or why its voice is terse.
- 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.
- Runs daily operations What does the product do for the business?
- Daily experts Who uses it most?
- AA What accessibility level do we commit to?
- A lot How much is on one screen?, also because Numbers and records
- Quiet How visible is the brand in the interface?
- Muted color → color.neutral.0 color.slate.dark.0: #0D1117
- Only when the meaning changes components →
- Small typography → type.body.font-size font.size.14: 0.875rem
- Compact spacing → space.gap.tight space.4: 0.25rem
- Match the text iconography → size.icon size.16: 1rem
- Quiet How visible is the brand in the interface?
- Constantly How often do people repeat actions?
- Time on task Which outcome matters most?
- Fast motion → motion.duration.feedback duration.fast: 120ms
- All day How long is one visit?
- Light and dark theming →
- Time on task Which outcome matters most?
- They learn it and recognize it How do people recall the interface?
- At a desk Where do people use it?
- Compact, for a pointer accessibility → size.control.default size.32: 2rem
- Terse voice and tone →
- Numbers and records What is the main content?
- Scan and compare What is the main task?
- People keep their place What must the interface protect?
- Acting on the wrong record What is a costly mistake?
- Precise What should the brand feel like?
- Slightly rounded shape → radius.control radius.2: 0.125rem
- Subtle elevation → elevation.card shadow.none: [object Object]
- Scan and compare What is the main task?
- Daily experts Who uses it most?
- One How many brands or products share the system?
- A small team Who maintains the system?
- Lowercase words in paths naming →
- Every month 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
What does the product do for the business?
- Runs daily operations
- Why
The product runs daily security operations: alerts, incidents and the assets they touch.
- Because of
Nothing before it. It's one of the first answers.
- What it decided (3)Answers it led to (3)
- Who uses it most? → Daily experts
- What is the main content? → Numbers and records
- Voice and tone · Which kinds of copy does it need? → Labels and messagesVoice and tone →
- Why
How many brands or products share the system?
- One
- Why
One internal product, one brand.
- Because of
Nothing before it. It's one of the first answers.
- What it decided (4)
- Why
Who uses it most?
- Daily experts
- Why
The same people use it all day, every day.
- Because of
- What does the product do for the business? → Runs daily operations
- What it decided (9)Answers it led to (8)
- What accessibility level do we commit to? → AA
- How much is on one screen? → A lot
- How often do people repeat actions? → Constantly
- How do people recall the interface? → They learn it and recognize it
- Where do people use it? → At a desk
- Accessibility · Which states get their own visible value? → Hover, focus, disabledAccessibility →
- Voice and tone · How many tones does it use? → OneVoice and tone →
- Voice and tone · How does it sound? → TerseVoice and tone →
Rules it sets (1)- For a first visit, use no tour. Show the data, with a tooltip where needed. Don't use a welcome tour. Daily experts skip tours; tooltips cover the first uses.Voice →
- Why
What accessibility level do we commit to?
- AA
- Why
AA is the floor for an internal tool used by trained staff.
- Because of
- Who uses it most? → Daily experts
- What it decided (6)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? → Three: color, icon and wordAccessibility →
- Accessibility · What contrast floor do we hold? → AAAccessibility →
Rules it sets (1)- 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 →
- Why
What is the main content?
- Numbers and records
- Why
Most of the screen is numbers and records.
- Because of
- What does the product do for the business? → Runs daily operations
- What it decided (22)Answers it led to (9)
- How much is on one screen? → A lot
- What is the main task? → Scan and compare
- What should the brand feel like? → Precise
- Typography · Which text roles does it need? → Core and dataTypography →
- Typography · Where does type do the most work? → Tables and inputsTypography →
- Spacing · Which spacing roles does it need? → Gaps, insets and row heightsSpacing →
- Accessibility · How many signals carry each meaning? → Three: color, icon and wordAccessibility →
- Components · Which component families does it need? → Core, plus dataComponents →
- Components · Where do components do the most work? → Tables and formsComponents →
Rules it sets (1)- For a status, use badge with a subtle fill, an icon and a word. Don't use a full-strength fill. Subtle fills let many statuses share one table.Color →
Variants it picks (12)- Badge's neutral tone. New and False positive: not triaged yet, or a finished outcome that is not a failure.Badge →
- Badge's info tone. Investigating: an analyst is on it; news, nothing to act on.Badge →
- Badge's success tone. Resolved: contained and closed.Badge →
- Badge's warning tone. Escalated: needs a senior analyst soon, still containable.Badge →
- Badge's danger tone. Breach confirmed: a real loss.Badge →
- Sidebar's default variant. Menu items with no border, quiet beside dense data.Sidebar →
- Sidebar's outline variant isn't used. Borders on every item would compete with the data.Sidebar →
- Empty's default variant isn't used. No pictures: an empty table needs the reason and the one action that fills it.Empty →
- Item's default variant. Users and settings in a panel or menu, with no border, quiet beside the data.Item →
- Item's outline variant isn't used. Borders on every row would compete with the data; hairlines between sections do that work.Item →
- Toggle's default variant. In the table toolbar, with no border; the pressed state shows as a fill, quiet beside the data.Toggle →
- Toggle's outline variant isn't used. Borders on every toggle would compete with the data.Toggle →
- Why
How much is on one screen?
- A lot
- Why
Experts want many records on one screen.
- Because of
- Who uses it most? → Daily experts
- What is the main content? → Numbers and records
- What it decided (23)Answers it led to (10)
- How visible is the brand in the interface? → Quiet
- Typography · How many steps does the type scale take? → Only the steps the screens needTypography →
- Typography · How large is body text? → SmallTypography →
- Spacing · How are spacing steps defined? → Small steps, on a 4px gridSpacing →
- Spacing · How dense is the layout? → CompactSpacing →
- Shape · Where does shape show most? → Controls in dense rowsShape →
- Iconography · What icon style? → OutlineIconography →
- Iconography · How big are icons next to text? → Match the textIconography →
- Accessibility · Where are the floors hardest to hold? → Dense tablesAccessibility →
- Components · How far does the inventory reach? → What today's screens use, plus what the next ones will likely needComponents →
Rules it sets (3)- For a page title, use type.title. Don't use type.display. Titles stay small so the table starts higher on the screen.Typography →
- Between page sections, use space.gap.section and a hairline. Don't use a card around every section. Lines separate without taking room from the data.Spacing →
- For a table row height, use size.row (compact). Don't use the comfortable row. Compact rows show more records without scrolling.Spacing →
Variants it picks (10)- Button's default size. Actions outside tables: forms, dialogs, page actions.Button →
- Button's compact size. Table rows and toolbars. Compact still fits a mouse.Button →
- Button's large size isn't used. Controls stay small so more records fit on one screen.Button →
- Input group's block-start align isn't used. Inputs stay one line high in toolbars and filter bars.Input group →
- Input group's block-end align isn't used. Inputs stay one line high in toolbars and filter bars.Input group →
- Field's horizontal orientation. Settings and filter panels: switches and short controls with the label beside.Field →
- Sidebar's lg size isn't used. Rows stay small so the whole navigation fits the screen all shift.Sidebar →
- Toggle's default size isn't used. Toggles sit in the table toolbar, at the smaller size like compact buttons.Toggle →
- Toggle's sm size. The table toolbar, matching compact buttons. It still fits a mouse.Toggle →
- Toggle's lg size isn't used. Controls stay small so more records fit on one screen.Toggle →
- Why
What is the main task?
- Scan and compare
- Why
People scan rows and compare values.
- Because of
- What is the main content? → Numbers and records
- What it decided (14)Answers it led to (9)
- What must the interface protect? → People keep their place
- What is a costly mistake? → Acting on the wrong record
- Typography · Which text roles does it need? → Core and dataTypography →
- Typography · How are sizes and line heights defined? → A ratio, line heights in proportionTypography →
- Spacing · How many densities exist? → TwoSpacing →
- Spacing · Where does spacing matter most? → Rows and cellsSpacing →
- Shape · Which shape roles does it need? → Controls, badges and containersShape →
- Components · Which component families does it need? → Core, plus dataComponents →
- Components · Where do components do the most work? → Tables and formsComponents →
Rules it sets (3)- For a number in a table, use type.data. Don't use type.body. Mono digits line up in columns, so values compare at a glance.Typography →
- For a field label or column header, use type.label. Don't use type.heading. Headers repeat on every column; a heavy style would compete with the data.Typography →
- For a selected row or item, use color.surface.selected. Don't use color.action.primary as a fill. A light tint shows selection without hiding the data.Color →
- Why
How often do people repeat actions?
- Constantly
- Why
The same actions repeat many times an hour.
- Because of
- Who uses it most? → Daily experts
- What it decided (16)Answers it led to (8)
- Which outcome matters most? → Time on task
- How long is one visit? → All day
- Color · How many emphasis levels do actions need? → ThreeColor →
- Iconography · What do icons do? → Actions and statusIconography →
- Iconography · Where do icons work hardest? → Toolbars and rowsIconography →
- Voice and tone · How is the voice defined? → Rules and a word listVoice and tone →
- Components · How does a component earn its place? → A use scenario needs itComponents →
- Components · When does a component get another look? → Only when the meaning changesComponents →
Rules it sets (2)- For an action on one row or item, use icon button, ghost, compact. Don't use button secondary in every row. Rows repeat dozens of times; a quiet icon keeps the table readable.Iconography →
- For a success message, use a short confirmation with the count. Don't use celebration. Confirm and get out of the way; the next task is waiting.Voice →
Variants it picks (6)- Button's ghost variant. Row actions, as compact icon buttons. Never for cancel.Button →
- Input group's inline-end align. The clear button after the text, for searches people repeat all day.Input group →
- Sidebar's default size. Every section of the app.Sidebar →
- Alert's default variant isn't used. Alerts here are for problems that stay on the page; news goes in a toast or a badge.Alert →
- Toast's success tone. A short confirmation with the count: 12 alerts exported.Toast →
- Toggle's default variant. In the table toolbar, with no border; the pressed state shows as a fill, quiet beside the data.Toggle →
- Why
What must the interface protect?
- People keep their place
- Why
Losing your place in a long table costs time and errors.
- Because of
- What is the main task? → Scan and compare
- What it decided (4)Answers it led to (3)
- Elevation · What separates groups on the page? → LinesElevation →
- Motion · What is motion for? → Feedback onlyMotion →
- Theming · What changes when the theme changes? → Colors onlyTheming →
Variants it picks (1)- Item's muted variant. The current user or setting, with a soft fill so people keep their place.Item →
- Why
How do people recall the interface?
- They learn it and recognize it
- Why
Daily users learn the interface and recognize it.
- Because of
- Who uses it most? → Daily experts
- What it decided (5)Rules it sets (3)
- For a link, use color.text.link. Don't use color.action.primary. Links and buttons look different, so people know which one navigates.Color →
- For items that belong together, use space.gap.tight. Don't use space.gap.group. Things that belong together sit close.Spacing →
- For an alternative or cancel, use button secondary. Don't use button ghost. A ghost button has no edge, so next to a filled primary it reads as plain text and cancel gets lost. Secondary keeps a visible border, so people find it at once.Color →
- Why
Which outcome matters most?
- Time on task
- Why
Speed on repeated tasks is the measure.
- Because of
- How often do people repeat actions? → Constantly
- What it decided (2)Answers it led to (1)
- Motion · How fast does feedback feel? → FastMotion →
Rules it sets (1)- For a paragraph or help text, use type.body. Don't use type.label. Help text is a sentence read in passing. Body size reads quickly; the label style is made for short names, not sentences.Typography →
- Why
What is a costly mistake?
- Acting on the wrong record
- Why
Acting on the wrong row is the costly error.
- Because of
- What is the main task? → Scan and compare
- What it decided (12)Answers it led to (2)
- Color · Where does color carry meaning first? → Status in tablesColor →
- Voice and tone · Where do the words matter most? → Errors and empty statesVoice and tone →
Rules it sets (4)- For an error message, use color.status.danger with an icon. Don't use color.status.warning. Red always means fix this, and the icon says it without color.Color →
- For the action that completes the task, use button primary, one per view. Don't use two primaries side by side. One primary makes the committing action obvious.Color →
- For a delete or remove, use button secondary, then confirm in a dialog with Button danger. Don't use button primary as the first step. Deleting is rare and costly; a confirm step catches mistakes.Color →
- For a confirmation question, use name the exact object and the consequence. Don't use "Are you sure?". Acting on the wrong record is the costly mistake.Voice →
Variants it picks (6)- Button's primary variant. The one commit in a view.Button →
- Button's secondary variant. Alternatives and cancel next to the primary, and the first step of a delete.Button →
- Button's danger variant. The confirm of a bulk delete. Many records go at once, so the last press must not look like the everyday primary.Button →
- Alert's default variant isn't used. Alerts here are for problems that stay on the page; news goes in a toast or a badge.Alert →
- Alert's destructive variant. A record that was not saved or an action that failed: name the record, then the fix, with an icon.Alert →
- Toast's danger tone. A background failure: name the record, then the fix.Toast →
- Why
What should the brand feel like?
- Precise
- Why
The interface must feel exact and trustworthy.
- Because of
- What is the main content? → Numbers and records
- What it decided (4)Answers it led to (4)
- Shape · What should control corners say? → Slightly roundedShape →
- Elevation · How soft are shadows? → SubtleElevation →
- Motion · How is easing defined? → Standard ease-outMotion →
- Voice and tone · How does it sound? → TerseVoice and tone →
- Why
How visible is the brand in the interface?
- Quiet
- Why
The data is the hero; the brand steps back.
- Because of
- How much is on one screen? → A lot
- What it decided (3)Answers it led to (3)
- Color · Which color roles does it need? → Surface, text, action and statusColor →
- Color · How saturated is the palette? → MutedColor →
- Components · When does a component get another look? → Only when the meaning changesComponents →
- Why
Where do people use it?
- At a desk
- Why
Experts work at a desk with a mouse and keyboard.
- Because of
- Who uses it most? → Daily experts
- What it decided (3)Answers it led to (2)
- Accessibility · What is the smallest target? → Compact, for a pointerAccessibility →
- Components · How does a component earn its place? → A use scenario needs itComponents →
Variants it picks (1)- Field's responsive orientation isn't used. A desk with a mouse and keyboard: there is no narrow screen to adapt to.Field →
- Why
How long is one visit?
- All day
- Why
The tool stays open for the whole shift.
- Because of
- How often do people repeat actions? → Constantly
- What it decided (1)Answers it led to (1)
- Theming · Which modes ship? → Light and darkTheming →
- Why
Who maintains the system?
- A small team
- Why
A small team keeps the system right.
- Because of
Nothing before it. It's one of the first answers.
- What it decided (5)Answers it led to (4)
- Naming · How are decisions named? → By roleNaming →
- Naming · How are names written? → Lowercase words in pathsNaming →
- Voice and tone · How is the voice defined? → Rules and a word listVoice and tone →
- Components · How far does the inventory reach? → What today's screens use, plus what the next ones will likely needComponents →
Rules it sets (1)- When no component in the inventory fits, use a component from the inventory, composed (for example a popover with a command list). Don't use a one-off component built for one screen. A small team keeps fewer parts right, and experts expect the same parts everywhere.Components →
- Why
How fast does it change?
- Every month
- Why
Features ship every month; the system must keep up.
- Because of
Nothing before it. It's one of the first answers.
- What it decided (3)
- Why
Scopes
Which text roles does it need?
- Core and data
- Why
A data role keeps numbers in aligned columns.
- Because of
- What is the main content? → Numbers and records
- What is the main task? → Scan and compare
- What it decided (1)Rules it sets (1)
- For a number in a table, use type.data. Don't use type.body. Mono digits line up in columns, so values compare at a glance.Typography →
- Why
How many steps does the type scale take?
- Only the steps the screens need
- Why
A screen full of records stays calm with only the sizes it needs.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the typography tokens: Typography →
- Why
How are sizes and line heights defined?
- A ratio, line heights in proportion
- Why
Line height is a ratio of each text's own size, so it follows the text. Two steps: tight for headings and labels, open for body, data and captions.
- Because of
- What is the main task? → Scan and compare
- What accessibility level do we commit to? → AA
- What it decided
It sets the values of the typography tokens: Typography →
- Why
How large is body text?
- Small
- Why
Small body text fits more rows on the screen.
- Because of
- How much is on one screen? → A lot
- What it decided (1)Answers it led to (1)
- Iconography · How many icon sizes exist? → OneIconography →
- Why
Where does type do the most work?
- Tables and inputs
- Why
Most text sits in table cells and inputs.
- Because of
- What is the main content? → Numbers and records
- What it decided
It sets the values of the typography tokens: Typography →
- Why
Which color roles does it need?
- Surface, text, action and status
- Why
Surface, text, action and status cover an operations tool.
- Because of
- How visible is the brand in the interface? → Quiet
- What it decided
It sets the values of the color tokens: Color →
- Why
How many emphasis levels do actions need?
- Three
- Why
One primary per view; the rest step back.
- Because of
- How often do people repeat actions? → Constantly
- What it decided (2)Rules it sets (1)
- For the action that completes the task, use button primary, one per view. Don't use two primaries side by side. One primary makes the committing action obvious.Color →
Variants it picks (1)- Button's primary variant. The one commit in a view.Button →
- Why
How is the palette defined?
- Neutrals and one brand ramp
- Why
One product, one brand ramp on cool neutrals.
- Because of
- How many brands or products share the system? → One
- What it decided
It sets the values of the color tokens: Color →
- Why
How saturated is the palette?
- Muted
- Why
Muted color keeps attention on the data.
- Because of
- How visible is the brand in the interface? → Quiet
- What it decided
It sets the values of the color tokens: Color →
- Why
Where does color carry meaning first?
- Status in tables
- Why
Color earns its place by marking late and failed records.
- Because of
- What is a costly mistake? → Acting on the wrong record
- What it decided
It sets the values of the color tokens: Color →
- Why
Which spacing roles does it need?
- Gaps, insets and row heights
- Why
Row height is a decision of its own in a table product.
- Because of
- What is the main content? → Numbers and records
- What it decided
It sets the values of the spacing tokens: Spacing →
- Why
How many densities exist?
- Two
- Why
A second, denser size serves tables and toolbars.
- Because of
- What is the main task? → Scan and compare
- What it decided (5)Rules it sets (1)
- For a table row height, use size.row (compact). Don't use the comfortable row. Compact rows show more records without scrolling.Spacing →
Variants it picks (4)- Field's horizontal orientation. Settings and filter panels: switches and short controls with the label beside.Field →
- Sidebar's sm size. Long secondary lists, at the denser size.Sidebar →
- Item's default size. Settings and user lists outside the table, at the standard row.Item →
- Item's sm size. Long lists in a side panel, at the denser size. It still fits a mouse.Item →
- Why
How are spacing steps defined?
- Small steps, on a 4px grid
- Why
Steps on a 4px grid give the small gaps dense screens need.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the spacing tokens: Spacing →
- Why
How dense is the layout?
- Compact
- Why
Compact spacing shows more records.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the spacing tokens: Spacing →
- Why
Where does spacing matter most?
- Rows and cells
- Why
Space is spent inside rows and cells.
- Because of
- What is the main task? → Scan and compare
- What it decided
It sets the values of the spacing tokens: Spacing →
- Why
Which shape roles does it need?
- Controls, badges and containers
- Why
Badges sit in columns and need their own corner.
- Because of
- What is the main task? → Scan and compare
- What it decided (2)Answers it led to (1)
- Shape · How many corner sizes exist? → ThreeShape →
Rules it sets (1)- For the shape of a status badge, use radius.badge (rectangle). Don't use a pill. Rectangles line up in a column.Shape →
- Why
How many corner sizes exist?
- Three
- Why
Control, badge and container corners differ.
- Because of
- Shape · Which shape roles does it need? → Controls, badges and containers
- What it decided
It sets the values of the shape tokens: Shape →
- Why
How are corners set?
- Fixed for the product
- Why
One brand, one fixed set of corners.
- Because of
- How many brands or products share the system? → One
- What it decided
It sets the values of the shape tokens: Shape →
- Why
What should control corners say?
- Slightly rounded
- Why
Small corners keep dense rows straight.
- Because of
- What should the brand feel like? → Precise
- What it decided (1)Rules it sets (1)
- For the corners of buttons and inputs, use radius.control. Don't use radius.round. Small corners keep dense rows straight.Shape →
- Why
Where does shape show most?
- Controls in dense rows
- Why
Corners show most on controls in dense rows.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the shape tokens: Shape →
- Why
What rises above the page?
- Only what floats
- Why
Only menus and dialogs float; cards use lines.
- Because of
- Elevation · What separates groups on the page? → Lines
- What it decided (3)Answers it led to (2)
- Elevation · How many shadow levels exist? → OneElevation →
- Elevation · Where does elevation show? → Menus and dialogsElevation →
Rules it sets (1)- For a card on the page, use a hairline border, no shadow. Don't use a shadow. On a busy grid, lines separate. Shadows blur the edges.Elevation →
- Why
How many shadow levels exist?
- One
- Why
One shadow for everything that floats.
- Because of
- Elevation · What rises above the page? → Only what floats
- What it decided
It sets the values of the elevation tokens: Elevation →
- Why
What separates groups on the page?
- Lines
- Why
Thin lines guide the eye along rows.
- Because of
- What must the interface protect? → People keep their place
- What it decided (3)Answers it led to (1)
- Elevation · What rises above the page? → Only what floatsElevation →
Rules it sets (1)- Between page sections, use space.gap.section and a hairline. Don't use a card around every section. Lines separate without taking room from the data.Spacing →
Variants it picks (1)- Item's outline variant isn't used. Borders on every row would compete with the data; hairlines between sections do that work.Item →
- Why
How soft are shadows?
- Subtle
- Why
Subtle shadows keep the grid crisp.
- Because of
- What should the brand feel like? → Precise
- What it decided
It sets the values of the elevation tokens: Elevation →
- Why
Where does elevation show?
- Menus and dialogs
- Why
Menus and dialogs are the only layers.
- Because of
- Elevation · What rises above the page? → Only what floats
- What it decided (1)Rules it sets (1)
- For a menu or dialog, use elevation.overlay and a dimmed page for dialogs. Don't use a border only. Floating things need a shadow so they read as on top.Elevation →
- Why
What is motion for?
- Feedback only
- Why
Motion confirms an action; nothing else moves.
- Because of
- What must the interface protect? → People keep their place
- What it decided (3)Answers it led to (2)Rules it sets (1)
- When someone asks for less motion, use no motion. Don't use a shorter version of the motion. A shorter motion still moves. When people ask for less motion, nothing moves.Motion →
- Why
How many speeds exist?
- One
- Why
One speed is enough for feedback.
- Because of
- Motion · What is motion for? → Feedback only
- What it decided
It sets the values of the motion tokens: Motion →
- Why
How is easing defined?
- Standard ease-out
- Why
A standard ease-out never draws attention.
- Because of
- What should the brand feel like? → Precise
- What it decided
It sets the values of the motion tokens: Motion →
- Why
How fast does feedback feel?
- Fast
- Why
Fast feedback keeps up with experts.
- Because of
- Which outcome matters most? → Time on task
- What it decided (2)Rules it sets (1)
- For hover and press feedback, use motion.duration.feedback (fast). Don't use no transition. Fast feedback confirms the pointer without slowing experts.Motion →
Variants it picks (1)- Button's hover state. Fast feedback that confirms the pointer.Button →
- Why
Where does motion show?
- State changes only
- Why
Only state changes move.
- Because of
- Motion · What is motion for? → Feedback only
- What it decided
It sets the values of the motion tokens: Motion →
- Why
What do icons do?
- Actions and status
- Why
Icons mark row actions and status.
- Because of
- How often do people repeat actions? → Constantly
- What it decided (4)Rules it sets (1)
- For an icon with no label, use icon button with a tooltip. Don't use a bare icon. Experts learn icons; the tooltip covers the first uses.Iconography →
Variants it picks (3)- Button's icon size. Known row and toolbar actions, always with a tooltip.Button →
- Input group's inline-start align. The search icon before the text.Input group →
- Empty's icon variant. An outline icon in a small tile beside the reason and the action.Empty →
- Why
How many icon sizes exist?
- One
- Why
One size, matched to the small text.
- Because of
- Typography · How large is body text? → Small
- What it decided
It sets the values of the iconography tokens: Iconography →
- Why
What icon style?
- Outline
- Why
Outline icons stay light next to dense text.
- Because of
- How much is on one screen? → A lot
- What it decided (1)Variants it picks (1)
- Empty's icon variant. An outline icon in a small tile beside the reason and the action.Empty →
- Why
How big are icons next to text?
- Match the text
- Why
Icons match the label so they do not outweigh it.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the iconography tokens: Iconography →
- Why
Where do icons work hardest?
- Toolbars and rows
- Why
Icons work hardest in toolbars and row actions.
- Because of
- How often do people repeat actions? → Constantly
- What it decided
It sets the values of the iconography tokens: Iconography →
- Why
What can a theme change?
- Mode only
- Why
One brand, so only the mode changes.
- Because of
- How many brands or products share the system? → One
- What it decided
It sets the values of the theming tokens: Theming →
- Why
How many themes ship?
- Two
- Why
Light and dark.
- Because of
- Theming · Which modes ship? → Light and dark
- What it decided
It sets the values of the theming tokens: Theming →
- Why
How are brands handled?
- One brand
- Why
One product, one brand.
- Because of
- How many brands or products share the system? → One
- What it decided
It sets the values of the theming tokens: Theming →
- Why
Which modes ship?
- Light and dark
- Why
Light first, always; dark ships as standard for night shifts.
- Because of
- How long is one visit? → All day
- What it decided (2)Answers it led to (1)
- Theming · How many themes ship? → TwoTheming →
Rules it sets (1)- When someone switches to dark, use the dark semantic mode. Don't use a second palette in components. Only semantic colors change, so layout never moves.Theming →
- Why
What changes when the theme changes?
- Colors only
- Why
A mode switch changes colors only, so layout never moves.
- Because of
- What must the interface protect? → People keep their place
- What it decided
It sets the values of the theming tokens: Theming →
- Why
Which states get their own visible value?
- Hover, focus, disabled
- Why
Pressed reuses hover; experts do not need more.
- Because of
- Who uses it most? → Daily experts
- What it decided
It sets the values of the accessibility tokens: Accessibility →
- Why
How many signals carry each meaning?
- Three: color, icon and word
- Why
Many statuses share one table; color alone is not enough.
- Because of
- What accessibility level do we commit to? → AA
- What is the main content? → Numbers and records
- What it decided (8)Rules it sets (2)
- For an error message, use color.status.danger with an icon. Don't use color.status.warning. Red always means fix this, and the icon says it without color.Color →
- For a status, use badge with a subtle fill, an icon and a word. Don't use a full-strength fill. Subtle fills let many statuses share one table.Color →
Variants it picks (6)- Badge's neutral tone. New and False positive: not triaged yet, or a finished outcome that is not a failure.Badge →
- Badge's info tone. Investigating: an analyst is on it; news, nothing to act on.Badge →
- Badge's success tone. Resolved: contained and closed.Badge →
- Badge's warning tone. Escalated: needs a senior analyst soon, still containable.Badge →
- Badge's danger tone. Breach confirmed: a real loss.Badge →
- Alert's destructive variant. A record that was not saved or an action that failed: name the record, then the fix, with an icon.Alert →
- Why
What contrast floor do we hold?
- AA
- Why
AA contrast for every text.
- Because of
- What accessibility level do we commit to? → AA
- What it decided
It sets the values of the accessibility tokens: Accessibility →
- Why
What is the smallest target?
- Compact, for a pointer
- Why
Mouse and keyboard; compact targets are enough.
- Because of
- Where do people use it? → At a desk
- What it decided (5)Rules it sets (1)
- For the smallest clickable thing, use size.control.compact. Don't use anything smaller. Compact still fits a mouse. Touch is not this product's input.Accessibility →
Variants it picks (4)- Button's default size. Actions outside tables: forms, dialogs, page actions.Button →
- Button's compact size. Table rows and toolbars. Compact still fits a mouse.Button →
- Item's sm size. Long lists in a side panel, at the denser size. It still fits a mouse.Item →
- Toggle's sm size. The table toolbar, matching compact buttons. It still fits a mouse.Toggle →
- Why
Where are the floors hardest to hold?
- Dense tables
- Why
Small text and thin lines in tables need the most care.
- Because of
- How much is on one screen? → A lot
- What it decided
It sets the values of the accessibility tokens: Accessibility →
- Why
What gets a name?
- Tokens and component keys
- Why
Components get their own keys.
- Because of
- How fast does it change? → Every month
- What it decided
It sets the values of the naming tokens: Naming →
- Why
How many token tiers?
- Three
- Why
Primitives, semantics and component keys.
- Because of
- How fast does it change? → Every month
- What it decided
It sets the values of the naming tokens: Naming →
- Why
How are decisions named?
- By role
- Why
Role names survive a redesign.
- Because of
- Who maintains the system? → A small team
- What it decided
It sets the values of the naming tokens: Naming →
- Why
How are names written?
- Lowercase words in paths
- Why
Lowercase paths read the same in CSS, JSON and Figma.
- Because of
- Who maintains the system? → A small team
- What it decided
It sets the values of the naming tokens: Naming →
- Why
What do components read?
- Component keys
- Why
A component API keeps changes local.
- Because of
- How fast does it change? → Every month
- 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. Raw values break dark mode and the next redesign.Naming →
- Why
Which kinds of copy does it need?
- Labels and messages
- Why
Labels and messages are all the copy an operations tool needs.
- Because of
- What does the product do for the business? → Runs daily operations
- What it decided
It sets the values of the voice and tone tokens: Voice and tone →
- Why
How many tones does it use?
- One
- Why
One flat tone everywhere; experts want no surprises.
- Because of
- Who uses it most? → Daily experts
- What it decided (1)Rules it sets (1)
- For a first visit, use no tour. Show the data, with a tooltip where needed. Don't use a welcome tour. Daily experts skip tours; tooltips cover the first uses.Voice →
- Why
How is the voice defined?
- Rules and a word list
- Why
A word list keeps labels identical across screens.
- Because of
- Who maintains the system? → A small team
- How often do people repeat actions? → Constantly
- What it decided (1)Rules it sets (1)
- For a button label, use one verb from the word list. Don't use a sentence or "Please". Labels repeat on every screen; one verb reads fastest.Voice →
- Why
How does it sound?
- Terse
- Why
Experts want short labels and short messages.
- Because of
- Who uses it most? → Daily experts
- What should the brand feel like? → Precise
- What it decided (7)Rules it sets (3)
- For a button label, use one verb from the word list. Don't use a sentence or "Please". Labels repeat on every screen; one verb reads fastest.Voice →
- For the words of an error, use name the record, then the fix. Flat and specific. Don't use "Oops" or a vague apology. Experts act on the message; the record and the fix are all they need.Voice →
- For a success message, use a short confirmation with the count. Don't use celebration. Confirm and get out of the way; the next task is waiting.Voice →
Variants it picks (4)- Alert's destructive variant. A record that was not saved or an action that failed: name the record, then the fix, with an icon.Alert →
- Toast's neutral tone. A plain confirmation: Filters cleared.Toast →
- Toast's success tone. A short confirmation with the count: 12 alerts exported.Toast →
- Toast's danger tone. A background failure: name the record, then the fix.Toast →
- Why
Where do the words matter most?
- Errors and empty states
- Why
Errors and empty tables are where words decide the next action.
- Because of
- What is a costly mistake? → Acting on the wrong record
- What it decided (4)Rules it sets (2)
- For the words of an error, use name the record, then the fix. Flat and specific. Don't use "Oops" or a vague apology. Experts act on the message; the record and the fix are all they need.Voice →
- For an empty state, use why it is empty and the one action that fills it. Don't use a blank table. An empty table with no words looks like an error.Voice →
- Why
Which component families does it need?
- Core, plus data
- Why
Records need tables, filters and fast ways to move between them.
- Because of
- What is the main content? → Numbers and records
- What is the main task? → Scan and compare
- What it decided
It sets the values of the components tokens: Components →
- Why
How far does the inventory reach?
- What today's screens use, plus what the next ones will likely need
- Why
A full operations tool with the parts its next screens will need, still few enough for a small team to keep right.
- Because of
- How much is on one screen? → A lot
- Who maintains the system? → A small team
- What it decided
It sets the values of the components tokens: Components →
- Why
How does a component earn its place?
- A use scenario needs it
- Why
A component joins only when a daily task needs it.
- Because of
- Where do people use it? → At a desk
- How often do people repeat actions? → Constantly
- What it decided (1)Rules it sets (1)
- When no component in the inventory fits, use a component from the inventory, composed (for example a popover with a command list). Don't use a one-off component built for one screen. A small team keeps fewer parts right, and experts expect the same parts everywhere.Components →
- Why
When does a component get another look?
- Only when the meaning changes
- Why
Repeated screens stay identical when a component changes only with its meaning.
- Because of
- How visible is the brand in the interface? → Quiet
- How often do people repeat actions? → Constantly
- What it decided
It sets the values of the components tokens: Components →
- Why
Where do components do the most work?
- Tables and forms
- Why
Most work happens in tables and the forms that edit them.
- Because of
- What is the main content? → Numbers and records
- What is the main task? → Scan and compare
- What it decided
It sets the values of the components tokens: Components →
- Why