Size and density
A ladder of five heights for the sizes of controls, the least size anything pressable is drawn at, and a size a container passes to what it holds.
How tall a control or a row is comes from three values. The control height and the minimum target belong to the whole design system: a product sets each once, in its layer. The size belongs to one component, or to a group of them: a button is small, medium or large where it stands.
The ladder is five heights, tanrei.sys.control.height.*, that the sizes of controls read. medium is the control height, tanrei.dial.control.height (40 by default), and the others are whole size units (dial.size.unit, 4px by default) below and above it: small two, extra-small four, large four and extra-large eight. These are the heights at a few control heights, evaluated from the tokens’ own rules:
| Token | dial.control.height 36px | dial.control.height 40px | dial.control.height 44px | dial.control.height 48px | dial.control.height 56px |
|---|---|---|---|---|---|
--tanrei-sys-control-height-extra-small | 20px | 24px | 28px | 32px | 40px |
--tanrei-sys-control-height-small | 28px | 32px | 36px | 40px | 48px |
--tanrei-sys-control-height-medium | 36px | 40px | 44px | 48px | 56px |
--tanrei-sys-control-height-large | 52px | 56px | 60px | 64px | 72px |
--tanrei-sys-control-height-extra-large | 68px | 72px | 76px | 80px | 88px |
Generated from design/tokens/tanrei.light.tokens.json, tokens/sys/measure.tokens.json
Many components read their heights from these steps, and the ones that read one step stay as tall as each other at every control height: the Button’s small, medium and large read the small, medium and large steps. The ladder itself has no floor, because extra-small is for things nobody presses, such as a tag or a keyboard shortcut.
tanrei.sys.target.minimum is the least height at which anything a person presses is drawn, and the least width of an icon-only control. Every height of a pressable box or row is derived with it as a floor, so no size draws one lower. It is the developer’s value: no dial scales it, since a floor that shrank with what it floors would be no floor.
In the default system the minimum is 36, for a pointer and for a finger alike. The Button’s heights show it at work: a value in parentheses is what the size and the control height give, and the height before it is what the minimum holds the button at.
| Token | dial.control.height 36px | dial.control.height 40px | dial.control.height 44px | dial.control.height 48px | dial.control.height 56px |
|---|---|---|---|---|---|
--tanrei-comp-button-container-height-small | 36px (28px) | 36px (32px) | 36px | 40px | 48px |
--tanrei-comp-button-container-height-medium | 36px | 40px | 44px | 48px | 56px |
--tanrei-comp-button-container-height-large | 52px | 56px | 60px | 64px | 72px |
Generated from design/tokens/tanrei.light.tokens.json, tokens/comp/button.tokens.json
Two more values say how large an area a press is taken from: sys.target.touch under a finger and sys.target.pointer under a fine pointer. Both are the minimum by default, so one value sets all three. A system that follows a platform’s guideline sets them higher; then a control that stands alone takes a press from that larger area, past what it draws, and a row that touches its neighbours is drawn that high. A mark drawn smaller than the target, such as a checkbox’s box or a small chip, keeps its size and extends its hit area to the target. What each shipped system sets:
| Design system | minimum | touch | pointer |
|---|---|---|---|
tanrei | 36px | 36px | 36px |
cupertino | 28px | 44px | 28px |
m3-like | 32px | 48px | 44px |
Generated from tokens/systems/*.system.json, design/tokens/<system>/tanrei.light.tokens.json
The build checks every system: none of the three under 24px (WCAG 2.5.8), touch and pointer never under the minimum, the minimum never above the control height, and no floored height under the minimum. A product’s own layer that sets a target under 24px is told so as a warning; a target area under the minimum, or a minimum above the control height, is refused in every system.
Both are tokens a layer sets with a reason:
"tokens": {
"tanrei.dial.control.height": { "$value": { "value": 32, "unit": "px" }, "reason": "A tool used all day with a mouse: controls and rows lower." },
"tanrei.sys.target.minimum": { "$value": { "value": 32, "unit": "px" }, "reason": "Used with a mouse; 32 is the least we draw." }
}On the web the heights are CSS expressions of the dials, so setting --tanrei-dial-control-height on the root element moves every height that follows it at once, without a new build. In Theme Studio, the Size row holds the control height, the size unit and the minimum target.
A size is set where the components stand. On the web, a button group’s size, once set, is the size of every Button in it that sets none of its own:
<tanrei-button-group size="small">
<tanrei-button variant="outlined">Cancel</tanrei-button>
<tanrei-button variant="filled">Publish</tanrei-button>
<tanrei-button variant="text" size="medium">Details</tanrei-button>
</tanrei-button-group>- A component’s own size wins. The third Button above is medium.
- Only a size that is set is passed down. A group without a
sizepasses none, so each Button in it is drawn at its own default, medium, or at the size a container around the group sets; where containers are nested, the nearest one that sets a size decides. - A size the component does not have becomes its nearest one along the ladder, extra-small, small, medium, large, extra-large, the larger of two as near.
- A button group and a toolbar draw nothing of their own by their size. Their gaps, corners and dividers stay those of their variant, around items of the height they are drawn at.
A component drawn at a size its container gives follows the ladder and the minimum as it does at a size of its own. Changing the container’s size, or moving a component into or out of it, draws it at its new size at once.
Three containers pass the size set on them to what they hold:
- A button group, to its Buttons.
- A toolbar, to its Buttons and buttons with menu, in a group or not, and to its overflow button.
- A list, to its list rows.
These components take the size of the nearest of those containers where they set none of their own, and are medium where no container sets one: the Button, the button with menu, the copy button and the list row, and, drawing every row or part they own at it, the list, the tree view, the accordion, the table of contents, the description list and the table.
The size stops there. The accordion, the description list and the table pass none on to what you place in them: a Button in a table cell keeps its own size, or takes the size of the containers around the table. And some components take none from a container at all:
- A menu, including a context menu and the menus of a menu bar, the view of a search, and the list of a select or a combobox. Each opens over the page, apart from the controls around it, so a small toolbar does not shrink the menu a Button in it opens. A menu and a search are medium unless they set their own
size; the options of a select or a combobox follow the size of its box. - A Select, a Number input, a Text input or a Slider in a toolbar, each of which keeps the size you give it.
- A timeline, whose size is the size of its text.