Icons
One icon set per design system, one weight, and one rule — outlined when unselected, filled when selected.
Tanrei’s default icons are Material Symbols, Rounded, at weight 300. Like the text faces, the font is referenced by name and not bundled: a product loads it.
How an icon is drawn is a small group of tokens. The icon box comes in four sizes, sys.icon.extra-small, small, medium and large, of which medium is the default, and the font’s optical size follows the box. What the shipped systems resolve them to:
| Design system | extra-small | small | medium | large |
|---|---|---|---|---|
tanrei | 16px | 20px | 24px | 32px |
cupertino | 16px | 20px | 24px | 32px |
m3-like | 16px | 20px | 24px | 32px |
Generated from tokens/systems/*.system.json, design/tokens/<system>/tanrei.light.tokens.json
ref.typeface.icon- The icon font. Material Symbols Rounded: a variable font whose weight and fill are set from sys.icon.
sys.icon.family- The icon font by selection. A variable icon font (Material Symbols) is one family and tells selected from unselected with its FILL axis; a static icon font tells them apart with two families (Material Icons Outlined / Material Icons). Both default to ref.typeface.icon.
sys.icon.weight- The stroke weight of every icon (the `wght` axis of the icon font).
sys.icon.fill- The fill of an icon by selection (the `FILL` axis of the icon font): 0 is outlined, 1 is filled.
Generated from tokens/ref/typeface.tokens.json, tokens/sys/measure.tokens.json
Unselected is outlined. Selected is filled. Always. A navigation item, a tab, a toggle, a chip, a favourite: the icon stays the same glyph and only its fill changes with the state. Filled and outlined icons are never mixed for decoration, and never chosen by hand — on the web the fill follows the state of the control the icon sits in.
Fill follows selection
import '@tanrei/web/icons.css';<button aria-pressed="true"><span class="tanrei-icon" aria-hidden="true">favorite</span> Favourite</button>.tanrei-icon reads aria-pressed, aria-selected, aria-checked and aria-current on any ancestor (on a Tanrei control, which moves them to data-aria-*, it reads data-aria-pressed, data-aria-selected, data-aria-checked and data-aria-current), or data-selected on the icon or an ancestor (data-selected="false" opts one icon out). Give an icon aria-hidden="true" when text next to it says the same thing, and the control an accessible name when it does not.
The name can also be given in data-icon, with the element left empty:
<span class="tanrei-icon" data-icon="folder"></span>The glyph is the same, but its name is no longer text on the page: it is not in textContent or innerText, not in what people copy, and not in the accessible name of the control around it. Use it wherever the name would otherwise be read as text, such as a row in a menu or a list, a table cell, or text a test compares. Size, selection and right-to-left mirroring work exactly as they do for the text form. Keep aria-hidden="true" where the text beside the icon says the same thing: Firefox before 128 still reads the name into the accessible name.
On the native platforms the same values arrive with the design system (system.icon), together with a small helper that turns selected and a size into what the font needs. Tanrei does not ship an icon component yet.
The icon set belongs to the design system, so a layer can change it. What the shipped systems resolve to:
| Design system | family.unselected | family.selected | weight | fill.unselected | fill.selected |
|---|---|---|---|---|---|
tanrei | Material Symbols Rounded | Material Symbols Rounded | 300 | 0 | 1 |
cupertino | Material Symbols Rounded | Material Symbols Rounded | 300 | 0 | 1 |
m3-like | Material Symbols Outlined | Material Symbols Outlined | 400 | 0 | 1 |
Generated from tokens/systems/*.system.json, design/tokens/<system>/tanrei.light.tokens.json
An icon font tells a selected icon from an unselected one in one of two ways, and the tokens cover both. A selected icon always takes family.selected and fill.selected; which of the two actually changes what is drawn depends on the set.
A variable icon font, such as Material Symbols, is a single family with a FILL axis. Both family tokens point at ref.typeface.icon by default, so re-pointing that one token changes the set, and fill.unselected / fill.selected tell the states apart. This is all of what m3-like writes:
"tokens": {
"tanrei.ref.typeface.icon": { "$value": ["Material Symbols Outlined"], "reason": "Material Design 3 draws Material Symbols in the Outlined style." },
"tanrei.sys.icon.weight": { "$value": 400, "reason": "Material Symbols default weight in Material Design 3." }
}A static icon font has no axes. It ships the outlined and the filled drawings as two separate families, so the layer names one for each state:
"tokens": {
"tanrei.sys.icon.family.unselected": { "$value": ["Material Icons Outlined"], "reason": "Acme uses the static Material Icons set: outlined when unselected." },
"tanrei.sys.icon.family.selected": { "$value": ["Material Icons"], "reason": "Acme uses the static Material Icons set: filled when selected." },
"tanrei.sys.icon.weight": { "$value": 400, "reason": "A static icon font has one weight; 400 is what Material Icons is drawn at." }
}The fill and weight tokens stay as they are. A static font ignores the axes, so they do no harm, and a component does not need to know which kind of set is active. This layer is the repository’s own test fixture (packages/tokens-build/test/fixtures/acme.system.json).
Tanrei decides how an icon is drawn, not which icons exist. Sets name their glyphs differently, and a set may lack a glyph another one has. A product that changes its icon set checks the names it uses. A symbol set that is not a font, such as SF Symbols, cannot be named by a family token; that is filed in the mimicry-gaps registry as platform-symbol-sets.
React Native’s <Text> cannot set font-variation axes, so with a variable icon font FILL never reaches the glyph and an icon looks the same in both states. To keep the rule there, use two static families as above, or draw the icons as SVG.
The icon helpers of the four native packages are being moved to the family-per-state model now; until a package’s README describes it, expect that package to read a single family.
The product loads the icon font, and only the part of it that it draws: the whole Material Symbols Rounded file holds every glyph at every value of its four axes, 5.4 MB. tanrei build prints what to cut it down to, for the product’s own system:
- The glyph names Tanrei’s components may draw by themselves: a chevron, a check, the cross of a close button… The list comes from the glyphs the specs name and the web components’ code declares. Add the names your own screens use.
- The axis values the system draws icons at.
FILLspans the two fill tokens, outlined and filled.wghtspanssys.icon.weightandsys.icon.mark.weight, the heavier weight of a control’s own mark, such as the check in a checkbox.opszspanssys.icon.optical-size.minand.max, the optical sizes the font draws, between which an icon box’s size is kept.GRADstays at 0: no token moves it.
| Design system | weight | mark.weight | optical-size.min | optical-size.max |
|---|---|---|---|---|
tanrei | 300 | 500 | 20 | 48 |
cupertino | 300 | 300 | 20 | 48 |
m3-like | 400 | 400 | 20 | 48 |
Generated from tokens/systems/*.system.json, design/tokens/<system>/tanrei.light.tokens.json
Because the values belong to the system, a layer that changes a weight changes what the font is cut down to: take them from your own build. On the web, the Web guide shows how to load the font both ways, from Google Fonts with icon_names= or from a file you cut down with fontTools, and how to keep icons from showing their names in letters while it loads. This site does the same: its icon font is cut down, when the site is built, to the names its components and pages draw.