# Tanrei > Tanrei is one design system for Web, SwiftUI, Jetpack Compose, Flutter and React Native. Its sources of truth are design tokens in the DTCG format and a platform-neutral spec for each component: each platform's tokens, the documentation's tables and these files are generated from them, and each platform implements the specs. This file holds the spec of every component the default design system, Tanrei (`tanrei`), ships, as Markdown. The index is https://tanrei.chnotchy.com/llms.txt; a component Tanrei does not ship is not here. ## Accordion > Content that a row shows and hides in place: one item is a single disclosure, several are a set whose items open by themselves or one at a time; each header is a button with a label, an optional glyph, second line and short value, and a chevron that turns; as rows on the surface or bounded by one hairline, ruled by a line or parted by a gap, with room for reading or drawn closer among controls. - Category: Containment - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/accordion/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/accordion.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/accordion`). - React: `Accordion` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-accordion` | lagging | | SwiftUI | `TanreiAccordion` | planned | | Jetpack Compose | `TanreiAccordion` | planned | | Flutter | `TanreiAccordion` | planned | | React Native | `Accordion` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `exclusive` (prop) | `exclusive` | `isExclusive` | `exclusive` | `exclusive` | `exclusive` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `accordion`: The column that holds the items. It draws nothing of its own in the plain look and adds no space around the items; in the outlined look with a line between the items it carries the one edge around them all. It has no role and no name. - `item`: One header and the content it shows and hides (an item of the item kind). Open or closed by itself; in the outlined look with a gap between the items it carries an edge of its own. - `container`: An item's header: the row across the item's width that opens and closes it. One button. It carries hover, focus and press and is the hit area; it has no fill at rest in the default system. - `icon` (optional): A glyph of the system's icon set at the start of the header, by name. Decorative, and the same open and closed. - `label`: The item's name and the header's accessible name. Plain text unless the product gives a heading; it wraps and is never cut. - `supporting-text` (optional): A line under the label that says what the item holds, quieter than the label. It wraps. - `trailing-text` (optional): A short value before the chevron, readable without opening the item: a count, the present value of what the item holds. One line. - `chevron`: The icon set's expand_more at the end of the header, turned half a turn while the item is open: the only mark of open and closed. Hidden from assistive technology, which is given the state in words. - `content`: What the item shows while open, under its header and inset to the header's first part: the product's content, from one sentence to fields, a table or another accordion. Not drawn, not focusable and not exposed while the item is closed, and still part of the document where the platform has one. - `outline` (optional): The outlined look's edge: one hairline with rounded corners around the whole accordion, or around each item where the items are parted by a gap. - `divider` (optional): A hairline across the accordion between two items, where the items are ruled by a line. - `focus-ring`: Gap-then-ring indicator shown for keyboard focus of a header, drawn inside the header's row. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `plain`, `outlined` | `"plain"` | `variant` | How the accordion stands on its surface. plain: rows on the surface, with nothing around them; for content in the flow of a page or a panel. outlined: bounded by one hairline with rounded corners; for a set that should read as one block among others, and on a surface where rows alone would be lost. A design system may add values. | | `size` | `enum`: `small`, `medium` | `"medium"` | `size` | How much room a header takes, in a list's and a tree view's words: its least height, its paddings, its text styles, its glyphs and the space under an open item's content. medium (a header at the control height, 40 in the default system, with a 16 label: as tall as a navigation drawer's row and the Buttons beside the accordion) is for a page a person reads: the questions of a help page, the sections of a long form. small (a 36 header with a 14 label, a small navigation drawer row's, held at the minimum target) is for a panel among controls: settings, an inspector, a card. Its heights follow the system's height ladder at either size. While it is not set the accordion is drawn at the size its nearest container sets (ACC-37), and at medium where none does. A design system may add values. | | `separation` | `enum`: `auto`, `divider`, `gap` | `"auto"` | `separation` | How an item is told from the item next to it. divider: one hairline between them; in the outlined look the items share one edge. gap: empty space and no line; in the outlined look each item has an edge of its own. Auto takes comp.accordion.separation, the design system's answer (divider in the default system). | | `exclusive` | `boolean` | `false` | `exclusive` | Whether opening an item closes the one that was open, so that at most one item of this accordion is open. False, the default, lets every item open and close by itself: a reader may compare two answers, and nothing moves that they did not touch. True is for items that exclude each other (the steps of one choice). An open item can always be closed again, leaving none open. | ### Item: `item` One header and the content it shows and hides. The fixture's content is the text of its content. Names: Web `details`, SwiftUI `TanreiAccordionItem`, Jetpack Compose `TanreiAccordionItem`, Flutter `TanreiAccordionItem`, React Native `AccordionItem`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | `""` | Its name, drawn in its header and used as the header's accessible name. Plain text, never a heading; the label slot takes its place where the product needs a heading of its own level or inline content. Required unless the label slot is filled. | | `supportingText` | `string` | `""` | A line under the label that says what the item holds ("Email, push and the weekly digest"), read as the header's description. Empty draws the label alone. | | `trailingText` | `string` | `""` | A short value before the chevron that can be read without opening the item: a count, the present value. One line; read after the supporting text as the header's description. | | `icon` | `string` | `""` | The name of a glyph in the system's icon set, drawn at the start of the header. Decorative. | | `open` | `boolean` | `false` | Whether its content is shown under its header. Set by the product for an item that starts open; the web sets it itself when the user opens or closes the item, and a controlled platform leaves it to the caller. | | `disabled` | `boolean` | `false` | Makes its header unavailable: it keeps its place and its open, draws its disabled look, cannot be toggled and leaves the focus order. The content of an open disabled item stays shown and as usable as the product made it. | | Event | Description | | --- | --- | | `toggle` | The item opened or closed: by the user from its header, by the accordion closing it for another (exclusive), or by the platform's search finding text in it; carries its new open state. Emitted exactly once per change, when the change begins. | | Slot | Description | | --- | --- | | `label` | The product's own label content in place of the label prop: text with inline content (a code span, a tag), or a heading of the level the page's outline needs. The accordion draws it in the label's style and changes neither its role nor its level. No control. | | `default` | The content: text, or the product's own blocks (paragraphs, fields, a table, any component, another accordion). The accordion insets it and gives it no style. | ### States `enabled`, `disabled`, `hovered`, `focused`, `pressed` ### Accessibility - Role: `button` - Labeling: Each header is a button named by its label (or by the text of the label slot's content), described by its supporting text and then its trailing text, with the expanded or collapsed state; its icon and chevron are hidden. A label given as text is plain text; a heading in the label slot keeps its level. An open item's content follows its header in reading order and has no role or name of its own. The accordion has no role and no name. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves focus to each header that is not disabled, in order, and through the focusable content of each open item after its header. Every header is its own stop; the accordion is not one. | | Enter or Space | On a header, opens or closes its item. Focus stays on the header. | | Right arrow / Left arrow (mirrored in right-to-left layouts) | On the header of a closed item, the arrow toward the end of the line opens it; on the header of an open item, the arrow toward the start closes it. Elsewhere the keys are the platform's. As on a navigation drawer's group row. | | Up arrow / Down arrow / Home / End | Nothing of the accordion's: they scroll the page as they do anywhere. Focus does not rove between headers. | - An accordion is a set of disclosures, not a tree and not tabs: a header is a button with an expanded state that shows or hides what follows it, and every header stays its own tab stop. This is the model of a navigation drawer's groups, on purpose: a group in a drawer and an item in content answer the same keys in the same way, and a person learns it once. One tab stop with roving arrow keys would make a long page of content behave like a single widget and take the arrow keys from the page. - WCAG 1.3.1 (info and relationships): the accordion does not decide whether a label is a heading. Most labels are names of a fold in a panel and should stay text. Where the items are the sections of a page that people navigate by heading (the questions of a help page), the product gives a heading of the right level in the label slot. Some assistive technology reads a heading inside a button as the button's name only; where the outline must not depend on that, the product puts the heading before a single-item accordion instead. - The content is not a region. Naming every item's content as a landmark fills the list of regions with entries a person did not ask for; six items make six regions. A product whose single disclosure is a main part of its page may give its own content element the region role and the label's name. - Closed content costs a press to read and cannot be seen at a glance. Do not close what most people need, do not hide a form's required fields or its errors in a closed item, and when a form is refused, open the item that holds the first error before moving focus to the field: the accordion does not open an item because something inside it is invalid. - exclusive moves the page: opening one item closes another, and what the reader was looking at goes. The accordion keeps the activated header where it is (ACC-14), which removes the worst of it; even so, keep exclusive for items that exclude each other. A person who wants two answers side by side cannot have them. - Where the platform's own search can reach closed content (the web's find-in-page), a match opens the item (ACC-16), so closing content does not hide it from someone who looks for its words. Native platforms have no such search: there, text in a closed item is found only by the product's own search, which sets the item's open. - A header holds no control (ACC-3). A switch, a menu button or a link beside the label would be a control inside a button: unreachable or ambiguous for assistive technology, and a press on it would also toggle the item. An action that belongs to an item goes into its content, or beside the accordion. - WCAG 2.5.8 (target size): a header is the whole row and at least the touch target high at both sizes; rows that touch do not share or extend hit areas (ACC-19). - WCAG 2.1.1 (keyboard) and 4.1.2 (name, role, value): closing an item by a press on its open content (ACC-36) is a convenience for a pointer only. The header is the one control, reached by the keyboard and named with its expanded state; the content gains no role, no focus stop and no announcement, so nothing is offered to a pointer that the keyboard and assistive technology do not already have through the header. An open item is one target, as a whole clickable card is (the maintainers' decision, 2026-10-13): the region that answers a press is the region that looks it — the pointer cursor over it, the hovered and pressed states drawn on the whole item, and keyboard focus ringed around the whole item, so that hover, press and focus all show the same one target, never a header and a content styled alike. This follows the clickable-card practice: the whole card is the target's area while the controls inside it keep their own press (Bootstrap, "Stretched link"), and the pointer cursor is set by the script, since without it the style would deceive (Inclusive Components, "Cards") — without the script the content shows no pointer and no state. Where the pointer is over a control in the content, that control is the target: it keeps its own cursor and states and the item shows none, as a nested button in a card answers alone. WCAG 2.4.7, 2.4.11 and 2.4.13 (focus visible, not obscured, appearance): the ring around an open item is the system's focus ring of the same widths and colors, inside the item's edge and drawn over its content, so nothing in the item, no neighbouring item, outlined edge or scrolling ancestor covers or cuts it, and it encloses a larger area than the header's. What a press must not be is kept from the same practice: a press that ends a text selection, or that is a drag, is not taken (that card pattern tells a selection by the press's length; the accordion tells it by the selection itself and by the slop). - WCAG 1.4.1 (use of color): open and closed are told by the chevron's turn and by the expanded state, never by color; the header keeps its colors when open. Disabled is told by the faded header and by the disabled state. - WCAG 1.4.3 and 1.4.11 (contrast) in the default system: the label is on-surface and the supporting text, trailing text, icon and chevron are on-surface-variant, on the surface the accordion stands on; each is held to 4.5:1 on every surface role by the token invariants. The edge and the lines are decorative: every header is told as a button by its chevron and its states. - Forced colors (ACC-27): the edge and the lines take the text color and the states the platform's own; nothing about open and closed rested on a color. - Web: the items are the product's own `
` elements with a `` each, in the document, inside ``. They open and close, keep their place in the tab order, are found by search in the page and are read, translated and printed as the page's content before any script runs and without it; what the script adds is listed in the platform notes. Before the element is defined, and without script, the stylesheet already draws the whole look, so nothing moves when the element is upgraded. - How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves. ### Behaviour Requirements in EARS form, each with its stable id. - **ACC-1** THE accordion SHALL lay out its items in one column, in the order given, each as wide as the accordion, and the accordion as wide as the layout it is placed in gives it: in a page, in a card, in a dialog, in a panel and in another item's content alike, with its start edge on the start edge of what is around it. It SHALL bring no outer space of its own (PRS-15: the space between it and its neighbours is its container's), SHALL have no minimum width, no maximum width and no height of its own, and SHALL NOT scroll: it is as tall as its headers and its open content, and content that cannot shrink scrolls inside its own box. An accordion of one item is a single disclosure and SHALL differ in nothing from an item of a set. - **ACC-2** THE accordion SHALL draw each item as a header and, WHILE the item is open, its content below the header (ACC-8). A header is one row across the item's whole width, at least as high as its size gives (comp.accordion.container.height.medium for medium and comp.accordion.container.height.small for small) and growing with its text, padded at its start and end by comp.accordion.container.padding-inline.medium for medium and comp.accordion.container.padding-inline.small for small and above its first line and below its last by comp.accordion.container.padding-block.medium for medium and comp.accordion.container.padding-block.small for small. Inside it SHALL lay out, from the start: the icon, where the item has one (ACC-5); the text, a column that takes the remaining width and holds the label (ACC-3) and under it the supporting text (ACC-4); the trailing text, where it has one (ACC-4); and the chevron (ACC-6); with comp.accordion.container.gap between each two of them. THE accordion SHALL centre the icon, the trailing text and the chevron on the label's first line and keep them there however tall the text grows, and any height a header has beyond its text SHALL be shared equally above and below it. - **ACC-3** THE accordion SHALL draw an item's label in the text style of its size (comp.accordion.label.typescale.medium for medium and comp.accordion.label.typescale.small for small) and the label color of its variant (comp.accordion.plain.label.color for plain, comp.accordion.outlined.label.color for outlined); the label SHALL wrap and SHALL never be cut. WHERE the item's label slot holds content THE accordion SHALL draw that content in the label's place, style and color instead of the label, and SHALL change neither its role nor its level: a label given as text is plain text and never a heading, and a label the product gives as a heading stays a heading of the level the product gave it, drawn as every other label is. The label slot SHALL hold text, inline content or a heading and no control: IF it holds a link, a button or a field THE accordion SHALL still render it and in debug builds report that a header is one button and holds no other. THE accordion SHALL set the label's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them. - **ACC-4** WHILE an item's supportingText is not empty THE accordion SHALL draw it under the label, in the text style of its size (comp.accordion.supporting-text.typescale.medium for medium and comp.accordion.supporting-text.typescale.small for small) and the supporting-text color of its variant (comp.accordion.plain.supporting-text.color, comp.accordion.outlined.supporting-text.color); it SHALL wrap and SHALL never be cut, and the header SHALL grow to hold it. WHILE an item's trailingText is not empty THE accordion SHALL draw it on one line between the text and the chevron, in the text style of its size (comp.accordion.trailing-text.typescale.medium for medium and comp.accordion.trailing-text.typescale.small for small) and the trailing-text color of its variant (comp.accordion.plain.trailing-text.color, comp.accordion.outlined.trailing-text.color); it SHALL NOT wrap, and WHILE it would take more than half of the header's inner width it SHALL be cut at the end of its own direction with an ellipsis, so that the label always keeps at least half. - **ACC-5** WHILE an item's icon is not empty THE accordion SHALL draw that glyph of the system's icon set at the start of the header, in a box of comp.accordion.icon.size.medium for medium and comp.accordion.icon.size.small for small, in the icon color of its variant (comp.accordion.plain.icon.color, comp.accordion.outlined.icon.color), with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, and SHALL keep it from assistive technology. WHILE icon is empty THE accordion SHALL draw no glyph and keep no room for one: the label starts at the start padding. The icon SHALL be the same glyph whether the item is open or closed. - **ACC-6** THE accordion SHALL draw a chevron at the end of every header: the icon set's expand_more in a box of comp.accordion.chevron.size.medium for medium and comp.accordion.chevron.size.small for small, in the chevron color of its variant (comp.accordion.plain.chevron.color, comp.accordion.outlined.chevron.color), drawn as ACC-5 draws a glyph, turned half a turn WHILE the item is open, and kept from assistive technology, which is given the item's state in words (ACC-24). The chevron SHALL be the only thing about a header that shows whether its item is open: the header's container, label, texts and icon SHALL be the same open and closed. A disabled item SHALL keep its chevron. - **ACC-7** THE accordion SHALL draw an item's open as the state of that item alone: WHILE open is true its content is shown under its header, and WHILE open is false its content is not drawn, takes no space, cannot take focus and is not exposed to assistive technology. WHEN the accordion first appears it SHALL draw every item as its open says, in its first frame, without the motion of ACC-13 and without emitting toggle. A closed item's content SHALL stay what it was: on a platform that keeps what it does not draw (the web, where the content stays in the document, a field in it keeps its value and is still sent with its form) THE accordion SHALL NOT remove, rebuild or reset it when the item closes or opens; on a platform that builds only what is drawn, the content is built again when the item opens, and state that must outlive a close is the product's to hold. - **ACC-8** WHILE an item is open THE accordion SHALL draw the content of its default slot under its header, inset at its start and end by the header's inline padding (comp.accordion.container.padding-inline.medium for medium and comp.accordion.container.padding-inline.small for small), so that it starts under the first part of the header, with no space above it and comp.accordion.content.padding-block-end.medium for medium and comp.accordion.content.padding-block-end.small for small below it. The content is the product's: THE accordion SHALL give it no text style and no color, which it takes from where the accordion stands, SHALL add no style to anything inside a component placed in it (PRS-16), and SHALL neither cut it nor limit its height. The content SHALL be held whole by the item: a margin of its first or last part is space inside the content, under the header and above the space below the content, and SHALL NOT reach out of the item. WHILE the item is open it is one target (ACC-36), and its hovered, focused and pressed states are the whole item's: THE accordion SHALL draw the container color of that state under the content as under the header (ACC-17) and SHALL give the content the state's opacity, and SHALL change nothing else about it — not its box, its text style or its color. - **ACC-9** WHILE variant is plain THE accordion SHALL draw no edge and no fill of its own: its headers are rows on the surface it stands on, in the colors of the plain look (comp.accordion.plain.container.color and the plain tokens ACC-3 to ACC-6 name). WHILE variant is outlined THE accordion SHALL draw an edge comp.accordion.outline.width wide in comp.accordion.outline.color with corners comp.accordion.outline.shape, inside the size of what it bounds and without moving anything in it — around the whole accordion WHILE its separation is divider, and around each item WHILE it is gap (ACC-10) — SHALL clip the headers' containers, their state layers and the content to that edge's corners, and SHALL draw its headers in the colors of the outlined look (comp.accordion.outlined.container.color and the outlined tokens ACC-3 to ACC-6 name). The variant SHALL change the edge and these colors and nothing else. - **ACC-10** THE accordion SHALL tell an item from the item next to it as its separation names: WHILE separation is auto, as comp.accordion.separation names, which follows sys.behavior.separation unless a design system sets it apart; WHILE separation is divider or gap, as that value names, whatever the tokens say. WHILE it is divider THE accordion SHALL draw one line of comp.accordion.divider.thickness in comp.accordion.divider.color across its whole width between every two items that follow each other, under the first one's content WHILE that item is open and under its header WHILE it is closed, without adding to an item's height, and SHALL draw no line above the first item or below the last. WHILE it is gap it SHALL leave comp.accordion.item.gap of empty space between every two items that follow each other, SHALL draw no such line, and SHALL leave no such space above the first item or below the last. WHEN separation, or the token it follows, changes THE accordion SHALL draw the other form at once, without animation, keeping every item's open; WHEN separation names a value the accordion does not define it SHALL treat it as auto and in debug builds report the unknown value. A platform that cannot draw a choice SHALL fall back to the first value, divider, and state that in its README. - **ACC-11** WHEN the user activates the header of an item that is not disabled by pointer, touch, Enter or Space THE accordion SHALL emit that item's toggle exactly once with its new open state, and on the web SHALL set the item's open itself (a controlled platform leaves it to the caller). WHEN focus is on the header of a closed item and the user presses the arrow key toward the end of the line (Right in a left-to-right layout) THE accordion SHALL open the item in the same way, and on the header of an open item the arrow key toward the start SHALL close it; the arrow key that would do neither, and every other key, SHALL be left to the platform. THE accordion SHALL NOT move focus from one header to another by an arrow key: every header is a stop of its own in the focus order, as a navigation drawer's group rows are. Activating a header SHALL NOT move focus, and focus SHALL stay on the header while its item opens and closes. - **ACC-12** WHILE exclusive is true THE accordion SHALL keep at most one of its own items open: WHEN an item opens, by the user's act, by the product setting its open or by ACC-16, THE accordion SHALL close the item that was open, emitting that item's toggle exactly once with false and on the web setting its open itself (a controlled platform leaves it to the caller), in the same motion as the one that opens (ACC-13). An open item SHALL still close by its own header, leaving none open. The items of an accordion placed inside an item's content SHALL NOT count: each accordion keeps its own. WHEN the accordion first appears, or exclusive becomes true, with more than one item open THE accordion SHALL draw the first of them in order open and the others closed, on the web setting their open itself, and in debug builds report that an exclusive accordion was given several open items. WHILE exclusive is false every item SHALL open and close by itself. - **ACC-13** WHEN an item's open changes THE accordion SHALL reveal or hide its content from the header downward, the item growing or shrinking in height and everything after it moving with its lower edge, and SHALL turn the chevron, over comp.accordion.motion.disclosure-duration with comp.accordion.motion.disclosure-easing, at once where motion is reduced. The content SHALL be laid out once, at the width and height it has when shown, and the motion SHALL only change how much of it is seen: its lines SHALL NOT wrap again, its parts SHALL NOT be resized and nothing in it SHALL be measured again from frame to frame. The item's height SHALL go from its height at rest before the change to its height at rest after it with no jump at the start or at the end, whatever margins the content's first and last parts have. Content that is being hidden SHALL stay drawn until the motion ends and SHALL leave the focus order and assistive technology when the motion begins. WHEN open changes again before the motion ends THE accordion SHALL go on from where the motion is toward the new state, without a jump. toggle SHALL be emitted when the change begins, not when the motion ends. - **ACC-14** WHEN items open and close in answer to the user's act on a header THE accordion SHALL keep that header where it is in the view, as far as the scrolling of what holds it allows, and move only what follows it: IF another item above it closes at the same time (ACC-12) THE accordion SHALL hold the activated header's place while the content above it goes, so that the row under the pointer or the finger does not move away from it. It SHALL NOT scroll for any other reason: an item that opens SHALL NOT be scrolled into view, and its content MAY reach below the view's edge. - **ACC-15** WHEN an item closes while keyboard focus is inside its content THE accordion SHALL move focus to that item's header or, WHILE the item is disabled, leave focus to the platform's default; WHEN it closes while focus is elsewhere it SHALL NOT move focus. - **ACC-16** WHERE the platform can search the text of what is shown and reports a match that lies in content it does not draw, or goes to a place inside such content (on the web, the browser's find-in-page and a link to a fragment of the page), WHEN the match or the place is inside a closed item THE accordion SHALL open that item, and every closed item of an accordion that holds it, at once and without the motion of ACC-13, SHALL emit each one's toggle exactly once with true, SHALL apply ACC-12 to each, and SHALL leave bringing the match into view to the platform; it SHALL do so for a disabled item too, whose header is unavailable and whose content is still part of the page. On a platform that has no such search or cannot report such a match, a closed item's content is not found, and THE accordion SHALL NOT open anything for it. - **ACC-17** WHILE an item's header is hovered, keyboard-focused or pressed THE accordion SHALL render that header's container, label, supporting text, trailing text, icon, chevron and opacity from the component tokens of its variant in the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. Hover and press over any part of the header's row SHALL answer on the whole container. WHILE the item is open THE accordion SHALL draw these states on the whole item, which is one target (ACC-36): the item's container — under the header and the content, to the item's edges — takes the state's container color and the header's parts its colors, whether the pointer is over the header or over the content where a press would close the item (ACC-36); over a descendant of the content that takes a press itself, the item SHALL show no hovered state of its own. The edge and the lines SHALL NOT change under a pointer, a press or focus. - **ACC-18** WHEN an item's header receives keyboard focus THE accordion SHALL show the focus ring inside the header's container, following comp.accordion.container.shape, while the item is closed, and WHILE it is open around the whole item, which is one target (ACC-36) — inside the item's edge, around the header and the content together, following the item's corners (the outlined look's at the set's corners, none elsewhere) — so that neither a neighbouring item, an outlined edge nor a scrolling ancestor cuts it, without animation; focus gained by pointer or touch SHALL NOT show it. - **ACC-19** WHERE a header is lower than the minimum target THE accordion SHALL make its container at least sys.target.touch tall for touch input and sys.target.pointer tall for fine pointers, because rows that touch cannot extend a hit area over each other; a platform that cannot tell the input type SHALL use sys.target.touch. The whole row, from the item's start edge to its end edge, its paddings, icon, texts and chevron included, SHALL be the header's hit area; WHILE the item is open, its content, down to the item's lower edge, SHALL be part of the item's hit area too: the open item is one target, as ACC-36 says. - **ACC-20** WHILE an item's disabled is true THE accordion SHALL render its header's container, label, supporting text, trailing text, icon, chevron and opacity from the disabled component tokens of its variant, SHALL NOT emit its toggle for a press, a key or a touch, SHALL NOT make its header focusable and SHALL expose the header as disabled. The item SHALL keep its place and its open: a disabled item that is open still shows its content, which stays as usable as the product made it, and the product MAY still set its open. A header that draws no fill at rest SHALL draw none while disabled. - **ACC-21** WHEN an item's header is pressed by pointer, touch, Enter or Space THE accordion SHALL show its pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. - **ACC-22** WHILE an item's header is pressed THE accordion SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer, clipped to the container, from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole header and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, supporting text, trailing text, icon, chevron and opacity still come from the pressed tokens. Under none every part stays with the state under the press. WHILE the item is open the press is the whole item's (ACC-36), by its header or its content: overlay paints the pressed container color on the whole item, ripple grows the layer over the whole item from the point of contact (from the item's center for a key), and the pressed opacity applies to the content as to the header. The ripple grows over comp.accordion.motion.feedback-duration with comp.accordion.motion.state-easing, fades over comp.accordion.motion.state-duration with comp.accordion.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **ACC-23** THE accordion SHALL ease its headers' container corners and the outlined look's corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show a header's keyboard focus as sys.behavior.focus-style names (ring or glow), around the header while its item is closed and around the whole item while it is open (ACC-18); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. - **ACC-24** THE accordion SHALL expose each item's header as one button named by its label (the text of the label slot's content where the product gave one), described by its supporting text and then its trailing text, with its expanded or collapsed state, the disabled state where it applies, and its icon and chevron hidden; and SHALL expose an open item's content after its header in reading order, as the content it is. On the web the header is the summary of a details element, which the browser exposes as a button with the expanded state; on Apple platforms a button whose value is expanded or collapsed, as a disclosure group reads; on Android the expanded state with the expand and collapse actions; in Flutter the expanded semantics flag; in React Native accessibilityState.expanded. THE accordion SHALL NOT make an item's content a landmark or a named region, and the accordion itself SHALL have no role and no name: a page with several items would otherwise list each of them among its regions. WHILE an item's label is empty and its label slot holds nothing THE accordion SHALL still render it, and in debug builds report that its header has no accessible name. - **ACC-25** WHEN an item opens or closes THE accordion SHALL let the header's changed state be the only thing assistive technology is told: it SHALL announce nothing itself, SHALL have no live region, and SHALL NOT move keyboard or screen-reader focus into the content. - **ACC-26** WHILE the text size is enlarged THE accordion SHALL grow its label, its supporting text and its trailing text with it, keep its paddings and gaps, wrap the label and the supporting text, and grow each header in height; it SHALL keep the icon's and the chevron's boxes at their token sizes, both still centred on the label's first line (ACC-2), SHALL cut nothing but a trailing text as ACC-4 says, SHALL set no fixed height, SHALL lose no content when the reader raises line height, paragraph spacing, letter spacing or word spacing, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %. - **ACC-27** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE accordion SHALL draw the outlined look's edge and the lines of ACC-10 in the platform's text color; its labels, texts, icons and chevrons in that text color; a disabled header in the platform's color for disabled text; and a header's hover, press and focus in the platform's own colors for a button and for focus, with the focus ring still inside the header. Open and closed SHALL still be told apart by the chevron's turn, which no color carries. - **ACC-28** WHERE the layout direction is right-to-left THE accordion SHALL mirror the order of a header's parts and apply its paddings by logical start and end: the icon at the right, the text after it, the trailing text and the chevron at the left; the content SHALL be inset by the same paddings. The arrow keys of ACC-11 SHALL follow the direction: Left opens and Right closes. The chevron's half turn SHALL be the same in both directions: a glyph that points down and then up has no mirrored form. A ripple SHALL still grow from the point of contact. - **ACC-29** THE accordion SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the accordion is shown THE accordion SHALL draw itself for the new direction at once, without a motion of its own, keeping every item's open and its focus. - **ACC-30** WHERE the layout direction is right-to-left THE accordion SHALL draw an item's icon mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size and color nor the order ACC-28 gives. THE accordion SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name. The chevron (expand_more, ACC-6) is not marked and is never mirrored. - **ACC-31** THE accordion SHALL lay out an item's label, its supporting text and its trailing text each as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right name, a number with its unit and a version keep their own order in a right-to-left layout and reorder nothing beside them; THE accordion SHALL still place each and align its lines by the layout direction, not by the text's own, and SHALL cut a trailing text that does not fit (ACC-4) at the end of its own direction. - **ACC-32** WHERE an item's content holds another accordion THE accordion SHALL treat it as content like any other: the inner accordion is laid out inside the item's inset (ACC-8), which is what shows its depth; it has its own variant, size, separation and exclusive, and the outer accordion passes it no size (ACC-37); its headers answer the keys of ACC-11 for its own items only; and WHEN the outer item closes and opens again the inner items SHALL be as their open said. IF accordions nest more than three levels deep THE accordion SHALL still render them, and in debug builds report the depth. - **ACC-33** WHILE the system's icon set cannot yet draw a glyph of the accordion (its font is still loading) THE accordion SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box, and SHALL draw the glyph once the set can; a header SHALL open and close its item all the same. - **ACC-34** WHEN variant, or the size the accordion draws (ACC-37), names a value that the active design system does not have THE accordion SHALL render with the default value (the default variant's or size's tokens), and in debug builds report the unknown value; a variant or a size a design system added SHALL be drawn from its tokens, as the core values are. - **ACC-35** IF the accordion has no items THE accordion SHALL draw nothing, take no space and expose nothing. IF an item has no content THE accordion SHALL still render its header, which opens onto nothing but the space under the content (ACC-8), and in debug builds report that the item shows and hides nothing. - **ACC-36** WHEN the content of an open item is pressed and released with the primary mouse button, a touch or a pen, without the pointer moving further than the platform's touch slop between the two, THE accordion SHALL close that item exactly as a press on its header does: one toggle with false, the motion of ACC-13 and the header kept where it is as ACC-14 says, with exclusive (ACC-12) closing nothing else. The item's whole frame is its hit area while it is open: the content from the item's start edge to its end edge and down to its lower edge, the space under the content (ACC-8) included, the way a whole card answers a press while the controls inside it keep their own. THE accordion SHALL NOT close the item IF the press lands on or inside something that answers a press itself — a link, a button, a field, a select, a label, a summary, an editable element, an element with a tab index, an element with a widget role, a custom element that takes focus, or an element to which the product gave the pointer cursor where the item's own is not (the pointer the item shows for itself does not count) — which keeps its own behaviour; IF the release ends a text selection, that is, the selection is not empty and lies in the item once the press is released; IF the pointer moved further than the slop (a drag, a scroll); IF a modifier key (Control, Command, Shift, Alt or Option) is held or a button other than the primary is used; IF the press is the second or a later press of a multiple click; WHILE the item is disabled (ACC-20); or IF the press lands inside an item of an accordion nested in the content: such a press belongs to the innermost item, so a press in a nested open item's content closes that item only, and a nested header toggles its own item only. For a pointer the open item is one target, as a whole clickable card is, and not a header and a content styled alike: WHILE a fine pointer is over the item where a press would toggle or close it — its header, or its content outside a descendant that takes a press itself — THE accordion SHALL show the hovered state on the whole item (ACC-17) and the pointer cursor; a press SHALL show the pressed state on the whole item (ACC-21, ACC-22); keyboard focus on the header SHALL be shown around the whole item (ACC-18). WHILE the pointer is over a descendant that takes a press itself, that descendant SHALL keep its own cursor, hover and press, and the item SHALL show neither its hovered state nor the pointer cursor. The content SHALL get no role, no name, no focus stop and no announcement: the header stays the one button with the expanded state, and the keyboard and assistive technology reach the item through it alone (ACC-11, ACC-24). WHERE the platform's content answers no press (on the web, without the element's script) the content SHALL show neither the pointer cursor nor a state. - **ACC-37** WHILE size is set THE accordion SHALL draw every header, and the space under every open item's content, at its own size, whatever a container sets; without its script it SHALL draw that size all the same. WHILE size is not set and a container around the accordion sets a size for what it holds — the nearest such container where several do — THE accordion SHALL draw at that size, its heights following the system's height ladder as at a size of its own, and at its nearest size where it has none of that name, in the order extra-small, small, medium, large, extra-large, the larger of two as near; WHILE no container around it sets one it SHALL draw medium. A container whose size is not set SHALL pass none, and the accordion SHALL pass none to what its items hold: their content is the product's (ACC-8), and an accordion nested in it takes the size of the containers around both (ACC-32). WHEN the size it draws changes — its own size set, changed or removed, a container's size set, changed or removed, or the accordion moved into or out of such a container — THE accordion SHALL draw the new size at once, without a motion, keeping every item's open and focus. - **ACC-38** WHEN the control height (dial.control.height) is N THE accordion's default header SHALL be N tall: a header of a medium accordion SHALL be drawn at comp.accordion.container.height.medium, which is sys.control.height.medium held at sys.target.minimum, and of a small accordion at comp.accordion.container.height.small, the small step; the header's block padding SHALL give up half of what its height loses below the control height's reference, so that one line of its label still fits, and the pointer and touch targets SHALL still hold a header up where they are taller (ACC-19). ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.accordion.…` → `--tanrei-comp-accordion-…`). #### `tanrei.comp.accordion` | Token | Type | Value | | --- | --- | --- | | `comp.accordion.separation` | `number` | `{tanrei.sys.behavior.separation}` | | `comp.accordion.container.height.medium` | `dimension` | `40px` | | `comp.accordion.container.height.small` | `dimension` | `36px` | | `comp.accordion.container.padding-block.medium` | `dimension` | `8px` | | `comp.accordion.container.padding-block.small` | `dimension` | `6px` | | `comp.accordion.container.padding-inline.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.accordion.container.padding-inline.small` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.accordion.container.gap` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.accordion.container.shape` | `dimension` | `{tanrei.sys.shape.corner.none}` | | `comp.accordion.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.heading-5}` | | `comp.accordion.label.typescale.small` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.accordion.supporting-text.typescale.medium` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.accordion.supporting-text.typescale.small` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.accordion.trailing-text.typescale.medium` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.accordion.trailing-text.typescale.small` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.accordion.icon.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.accordion.icon.size.small` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.accordion.chevron.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.accordion.chevron.size.small` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.accordion.content.padding-block-end.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.accordion.content.padding-block-end.small` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.accordion.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.accordion.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.accordion.outline.shape` | `dimension` | `{tanrei.sys.shape.corner.medium}` | | `comp.accordion.divider.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.accordion.divider.thickness` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.accordion.item.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.accordion.plain.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.accordion.plain.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.accordion.plain.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.plain.trailing-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.plain.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.plain.chevron.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.plain.state-layer.color` | `color` | `{tanrei.comp.accordion.plain.label.color}` | | `comp.accordion.outlined.container.color` | `color` | `{tanrei.comp.accordion.plain.container.color}` | | `comp.accordion.outlined.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.accordion.outlined.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.outlined.trailing-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.outlined.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.outlined.chevron.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.accordion.outlined.state-layer.color` | `color` | `{tanrei.comp.accordion.outlined.label.color}` | | `comp.accordion.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.large}` | | `comp.accordion.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.accordion.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` | | `comp.accordion.motion.disclosure-duration` | `duration` | `{tanrei.sys.motion.role.disclosure}` | | `comp.accordion.motion.disclosure-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.spatial}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.accordion...` for the variants `plain`, `outlined`, the states `hovered`, `focused`, `pressed`, `disabled` and the properties `container.color`, `label.color`, `supporting-text.color`, `trailing-text.color`, `icon.color`, `chevron.color`, `state-layer.color`. - `comp.accordion..` for the states `hovered`, `focused`, `pressed`, `disabled` and the properties `opacity`. ## App bar > Names the current screen at its top edge and holds the way back and the screen's actions — as many as its row has room for, the rest in an overflow menu or left out, as the product chooses — its bottom edge drawn as the edge of a region that stays (or, where the design system chooses, only once content scrolls under it). - Category: Navigation - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/app-bar/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/app-bar.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/app-bar`). - React: `AppBar` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-app-bar` | lagging | | SwiftUI | `TanreiAppBar` | lagging | | Jetpack Compose | `TanreiAppBar` | lagging | | Flutter | `TanreiAppBar` | lagging | | React Native | `AppBar` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `title` (prop) | `headline` | `title` | `title` | `title` | `title` | | `titleAlignment` (prop) | `titleAlignment` | `titleAlignment` | `titleAlignment` | `centerTitle` | `titleAlignment` | | `scrolled` (prop) | `scrolled` | `isScrolled` | `scrollBehavior` | `scrolledUnder` | `scrolled` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The bar across the top of the screen. Its color reaches under the system inset above it (status bar, camera cutout, window caption). - `navigation` (optional): The navigation item: one icon-only Button at the start (back, menu or close). The product's icon-only Button, not restyled by the bar. - `brand` (optional): The product's brand: one link to its first page (or one image), after the navigation item, in a cell as large as an icon button's. It draws one image, the symbol alone, the wordmark alone, the symbol and the wordmark side by side (lockup), or one of the two by the window's width (responsive). - `context` (optional): The product's context: one control after the brand (a workspace, a project, a design system), the product's own Button, not restyled by the bar. - `title`: The screen's name. In the top row for a small bar; under the top row for an expanded large bar, moving into the top row as it collapses. - `subtitle` (optional): One line under the title: context for it (an account, a status, when it was edited). - `actions` (optional): The action items: icon-only Buttons at the end, as many as the top row has room for (APB-26). The product's icon-only Buttons, not restyled by the bar. - `overflow-button` (optional): The more button: the bar's own icon-only Button after the actions still shown, which opens a Menu of the actions that did not fit. Drawn only while overflow is menu and some action did not fit. - `outline`: The bar's bottom edge. In the default system it is drawn at rest and while content is under the bar; dividerVisibility scroll draws it only once content has scrolled under the bar. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `size` | `enum`: `small`, `large` | `"small"` | `size` | Small puts the title in the one row the bar has; large gives the title a larger row of its own under the top row, which collapses into the top row as the content scrolls. One product uses small on most screens and large on its top-level ones. A design system may add values. | | `title` | `string` | `""` | `headline` | The screen's name, and the heading of the screen for assistive technology. | | `subtitle` | `string` | `""` | `subtitle` | One line under the title. Empty draws none. | | `titleAlignment` | `enum`: `start`, `center` | `"start"` | `title-alignment` | Where the title sits in the top row: after the navigation button, or centered on the bar. An expanded large bar's own title row always starts at the start. | | `brandHref` | `string` | `""` | `brand-href` | The address of the product's first page: the brand is a link to it. Empty draws the brand as an image that is not a link. | | `brandLabel` | `string` | `""` | `brand-label` | The product's name: the brand's one accessible name, whichever of its images is shown. Required wherever the bar has a brand. | | `brandLayout` | `enum`: `lockup`, `responsive` | `"lockup"` | `brand-layout` | How the brand's symbol and wordmark stand when the product gives both (APB-21): lockup sets them side by side, comp.app-bar.brand.lockup.gap apart and aligned as comp.app-bar.brand.lockup.alignment says; responsive shows the wordmark while the window is medium or wider and the symbol while it is compact, never both. One image, a symbol alone or a wordmark alone is shown as it is, at every width, under either value. | | `scrolled` | `boolean` | `false` | `scrolled` | Whether content lies under the bar. A scrolling view connected to the bar sets it (see platforms); a product without one sets it itself. It selects the bar's scrolled condition, and a large bar is drawn collapsed while it is true. | | `dividerVisibility` | `enum`: `auto`, `always`, `scroll` | `"auto"` | `divider-visibility` | When the bar's bottom edge is drawn. always: at rest and while content is under the bar, so that the edge of the screen's header stands still (an app shell's header, a screen whose content starts right under the bar). scroll: only while content lies under the bar, so that the line itself says the content has moved (the scrolled condition's edge alone). auto takes comp.app-bar.outline.visibility, the design system's answer (always in the default system). The bar's color and elevation follow scrolled under either choice. | | `overflow` | `enum`: `menu`, `hide` | `"menu"` | `overflow` | What becomes of the action items that do not fit in the top row (APB-26): menu moves them, from the end, into a Menu opened from a more button at the end (APB-28, APB-29); hide leaves them out of the bar, for actions the product also gives somewhere else (APB-30). The bar sets no limit on the number of actions either way: every action that fits is drawn. | | `overflowLabel` | `string` | `""` | `overflow-label` | The more button's accessible name ("More actions"), in the product's language. Never drawn. Empty takes the product's words. Needed whenever overflow is menu and the bar may be narrower than its actions. | ### Slots | Slot | Description | | --- | --- | | `navigation` | Holds the navigation item: one icon-only Button at the start. | | `brand` | The brand as one image: a product's single logo file, drawn comp.app-bar.brand.image.height high. Takes the place of brand-symbol and brand-wordmark where both are given. | | `brand-symbol` | The brand's symbol: comp.app-bar.brand.symbol.size high alone, or while the window is compact under brandLayout responsive; comp.app-bar.brand.lockup.symbol.size high (the wordmark's height) beside the wordmark in a lockup. | | `brand-wordmark` | The brand's wordmark, drawn comp.app-bar.brand.wordmark.height high: alone at every width, after the symbol in a lockup, or while the window is medium or wider under brandLayout responsive. | | `context` | Holds one control of the product's context after the brand: a Button, or a Button that opens a Menu, that says and changes the workspace, the project or the design system the screen is in. The product's own control, not restyled by the bar. | | `actions` | Holds the action items: icon-only Buttons at the end, in reading order, with no limit on their number. Those that do not fit leave from the end, into the overflow menu or out of the bar as overflow says (APB-26). | ### Item: `navigation` The one icon-only Button at the start of the top row (back, menu or close): a Button of the text variant and the medium size with an icon and no label, unless the product sets otherwise, placed in the navigation slot, which the bar lays out and does not restyle. It is a Button. Names: Web `tanrei-button`, SwiftUI `TanreiButton`, Jetpack Compose `TanreiButton`, Flutter `TanreiButton`, React Native `Button`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `label` | `string` | `""` | `label` | Its accessible name ("Back"), as the Button's label. Required. | | Event | Description | | --- | --- | | `click` | The button was activated, as the Button's click. | | Slot | Description | | --- | --- | | `icon` | Its glyph, as the Button's icon slot. A fixture item's content is this glyph. | ### Item: `action` An icon-only Button at the end of the top row, in reading order, as many as the row has room for: a Button of the text variant and the medium size with an icon and no label, unless the product sets otherwise, placed in the actions slot, which the bar lays out and does not restyle. It is a Button. Names: Web `tanrei-button`, SwiftUI `TanreiButton`, Jetpack Compose `TanreiButton`, Flutter `TanreiButton`, React Native `Button`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `label` | `string` | `""` | `label` | Its accessible name ("Search"), as the Button's label. Required. | | `overflow` | `enum`: `auto`, `never` | `"auto"` | — | Whether the bar may take this action out of the top row when there is no room for it (APB-26): never keeps it, and the actions before it leave instead. Read by the bar to place the item. | | Event | Description | | --- | --- | | `click` | The button was activated, as the Button's click. | | Slot | Description | | --- | --- | | `icon` | Its glyph, as the Button's icon slot. A fixture item's content is this glyph. | ### States `enabled` ### Accessibility - Role: `none` - Labeling: The title is the screen's heading (a level 1 heading on the web unless the product sets another level). The subtitle is read after it. The navigation and action items, and the control in context, are named by their own labels. The brand is one link to the product's first page named by brandLabel (the product's name), whichever of its images is shown; its images are hidden from assistive technology. The more button is named by overflowLabel or the product's words ("More actions"), and exposed as a button that opens a menu, with its expanded state. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab | Moves focus to the navigation item, then to the brand's link, then to the control in context, then through the action items shown and to the more button where it is drawn; the bar itself is not a tab stop. An action that is out is not a stop. | | Enter or Space (on the more button) | Opens the Menu of the actions that are out, with focus on its first item; the Menu's own keys move through it, and Escape closes it and returns focus to the more button. | - The app bar has no role of its own and takes no input: its buttons are the product's icon-only Buttons, which meet the minimum target themselves (BTN-5). The bar is not a landmark, because only the product knows whether it is its page's banner; a product that wants one wraps the bar in its own header element. - The title is truncated rather than wrapped even at 200% text size: the bar's rows grow with the text, but a bar of several lines would push the screen's content away. The full title stays available to assistive technology. - Where both titles of a large bar are partly visible, only the expanded one is exposed, so the heading is never read twice. - The bar sets no limit on the number of actions: as many as fit are drawn, and the rest are in the more button's menu, each with its label, or, under overflow hide, left out of the bar. A hidden action is out of the tab order and of the accessibility tree, so what it does must be reachable elsewhere at that width (APB-30). ### Behaviour Requirements in EARS form, each with its stable id. - **APB-1** WHILE scrolled is false THE app bar SHALL fill its container with comp.app-bar.flat.container.color, raise it by comp.app-bar.flat.container.elevation and draw its bottom edge comp.app-bar.outline.width thick: in comp.app-bar.scrolled.outline.color WHILE its divider visibility (APB-18) is always, so that the edge stands still whether or not content lies under the bar, and in comp.app-bar.flat.outline.color WHILE it is scroll. - **APB-2** WHILE scrolled is true THE app bar SHALL fill its container with comp.app-bar.scrolled.container.color, raise it by comp.app-bar.scrolled.container.elevation and draw its bottom edge comp.app-bar.outline.width thick in comp.app-bar.scrolled.outline.color, under either divider visibility (APB-18). - **APB-3** WHEN scrolled changes THE app bar SHALL change its container color, elevation and bottom edge over comp.app-bar.motion.condition-duration with comp.app-bar.motion.condition-easing, and at once where motion is reduced; WHILE its divider visibility (APB-18) is always the bottom edge SHALL NOT change. - **APB-4** THE app bar SHALL span the full width of its parent and lay out a top row at least comp.app-bar.container.height.small high: the navigation item comp.app-bar.container.padding-inline from the start edge, the title block, and the action items comp.app-bar.container.padding-inline from the end edge, with comp.app-bar.container.gap between them and comp.app-bar.actions.gap between two actions, each vertically centered in the row; a navigation item SHALL go to the start and action items to the end wherever they stand among the items; WHILE there is no navigation item the title block SHALL start comp.app-bar.title.inset from the start edge, and WHILE there are no action items it SHALL end comp.app-bar.title.inset from the end edge. Right-to-left layouts SHALL mirror the order. - **APB-5** THE app bar SHALL draw a title in the top row on one line in comp.app-bar.title.typescale.small and comp.app-bar.title.color, and WHILE subtitle is not empty the subtitle on one line below it in comp.app-bar.subtitle.typescale.small and comp.app-bar.subtitle.color, the two vertically centered as a block; each SHALL be truncated at the end with an ellipsis when it does not fit. THE app bar SHALL set the title's letter-spacing, in every size, by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them. - **APB-6** WHILE titleAlignment is center THE app bar SHALL center the top row's title block on the bar's full width and narrow it equally on both sides, truncating its text, so that it never overlaps the navigation or actions slots, and SHALL center its text; WHILE titleAlignment is start THE app bar SHALL start the title block after the navigation slot (or at comp.app-bar.title.inset) with its text start-aligned. - **APB-7** WHILE size is large and the bar is expanded THE app bar SHALL be at least comp.app-bar.container.height.large high, SHALL draw no title in its top row, and SHALL draw below the top row the title in comp.app-bar.title.typescale.large and, WHILE subtitle is not empty, the subtitle in comp.app-bar.subtitle.typescale.large, both starting comp.app-bar.title.inset from the start edge, each on one line truncated at the end, the block ending comp.app-bar.container.padding-block-end above the bar's bottom edge. - **APB-8** WHILE size is large and a scrolling view is connected THE app bar SHALL shrink by the distance the content has scrolled from its top, one for one, from its expanded height to comp.app-bar.container.height.small, the expanded title block moving up with the bar's bottom edge and clipped under the top row; the top row's title SHALL be invisible while the expanded title is wholly visible, fully visible once the bar has collapsed, and in between fade in linearly with the part of the expanded title that is covered. WHEN the content scrolls back toward its top THE app bar SHALL expand the same way. - **APB-9** WHERE a scrolling view is connected THE app bar SHALL take scrolled from it: true while any content lies under the bar (for a large bar, only once it has fully collapsed) and false when the content is at its top. WHILE size is large and scrolled is true THE app bar SHALL be drawn fully collapsed; WHERE nothing is connected and scrolled is false a large app bar SHALL stay expanded. - **APB-10** THE app bar SHALL extend its container under the top system inset (status bar, camera cutout, window caption) and SHALL place its content below that inset and inside the left and right insets, so that its color reaches the screen's top edge while no content sits under a system bar or cutout. - **APB-11** THE app bar SHALL NOT restyle its navigation and action items: each SHALL render as the icon-only Button it is, from its own tokens, and keep its own semantics, and the app bar SHALL NOT be focusable itself, so that focus moves from the navigation item to the action items in reading order, and then to the more button where it is drawn (APB-28). A glyph of an item that the system's icon set marks as mirrored (a navigation item's arrow_back) SHALL be mirrored in a right-to-left layout by the item's own icon helper (BTN-19): that is the icon's own behaviour, not a restyling by the app bar. - **APB-12** THE app bar SHALL expose title as a heading and subtitle as text read after it, and SHALL expose the title only once WHILE size is large: the expanded title while any of it is visible, the top row's title once the bar has collapsed. - **APB-13** WHILE title is empty THE app bar SHALL draw no title block (an expanded large bar then has an empty title row) and SHALL expose no heading; IF the app bar holds more than one navigation item THE app bar SHALL still render them, and in debug builds report that a bar has one navigation button. - **APB-14** WHEN size names a value that the active design system does not have THE app bar SHALL render with the default value's tokens, and in debug builds report the unknown value. - **APB-15** WHILE the text size is enlarged THE app bar SHALL grow its rows to hold the title and subtitle lines (its heights are minimums), SHALL keep each on one line truncated at the end, and SHALL NOT scale the navigation and action items it holds. - **APB-16** THE app bar SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the app bar is shown THE app bar SHALL draw itself for the new direction at once, without a motion of its own, keeping its size and the scroll state it follows. - **APB-17** THE app bar SHALL lay out its title and its subtitle as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE app bar SHALL still place each and align its lines by the layout direction, not by the text's own, and SHALL cut a title or a subtitle that does not fit (APB-5, APB-7) at the end of its own direction, so that a left-to-right label in a right-to-left layout loses its right end and never its beginning. - **APB-18** THE app bar SHALL draw its bottom edge (APB-1, APB-2) as its dividerVisibility names: WHILE dividerVisibility is auto, as comp.app-bar.outline.visibility names, which follows sys.behavior.divider-visibility unless a design system sets the app bar apart; WHILE dividerVisibility is always or scroll, as that value names, whatever the tokens say. WHEN dividerVisibility, or the token it follows, changes THE app bar SHALL draw the other form at once, moving no part and keeping the scroll position and focus; WHEN dividerVisibility names a value the app bar does not define THE app bar SHALL treat it as auto and in debug builds report the unknown value. A platform that cannot draw a choice SHALL fall back to the first value, always, and state that in its README. - **APB-19** WHERE the product gives the app bar a brand (an image in brand, brand-symbol or brand-wordmark) THE app bar SHALL place it at the start of the top row, after the navigation item at comp.app-bar.actions.gap from it, or comp.app-bar.container.padding-inline from the start edge WHILE no navigation item is drawn, with the title block after it at comp.app-bar.container.gap; the brand SHALL take a cell at least the minimum target and a medium icon-only Button high and wide (the navigation item's cell, APB-11), padded at its start and end by half that cell less comp.app-bar.brand.symbol.size, its images centred on the row's centre line, so that a symbol stands where an icon button's icon stands and a wordmark keeps that inset from the cell's edges. Right-to-left layouts SHALL mirror the order. - **APB-20** THE app bar SHALL draw the image in brand comp.app-bar.brand.image.height high, the symbol comp.app-bar.brand.symbol.size high and the wordmark comp.app-bar.brand.wordmark.height high, each as wide as its own proportions make it, and SHALL give the brand comp.app-bar.brand.color, which an image drawn in the current color takes and an image of its own colors keeps. WHILE the brand is a lockup THE app bar SHALL draw the symbol and then the wordmark in one row, comp.app-bar.brand.lockup.gap apart, aligned in the row's block axis as comp.app-bar.brand.lockup.alignment names (center, start or end). - **APB-21** WHERE the brand holds one image, a symbol alone or a wordmark alone THE app bar SHALL show it at every window width. WHERE it holds both a symbol and a wordmark, WHILE brandLayout is lockup THE app bar SHALL show both as a lockup (APB-20), and WHILE brandLayout is responsive THE app bar SHALL show the wordmark WHILE the window class is medium or expanded and the symbol WHILE it is compact, never both: the window class of the app shell the bar stands in, or, outside one, the window's width against sys.breakpoint.medium. WHEN the window class changes THE app bar SHALL show the other at once, without a motion of its own, the brand's link and its focus unchanged. - **APB-22** THE app bar SHALL expose the brand as one link to brandHref named by brandLabel — or, WHILE brandHref is empty, as one image named by brandLabel — between the navigation item and the action items in reading order, and SHALL hide the brand's images from assistive technology, so that the product's name is read once whichever arrangement is shown. THE brand's link SHALL be a stop in the tab order and SHALL draw the focus indicator around its cell, in the shape comp.app-bar.brand.shape. - **APB-23** IF brandLayout names a value the app bar does not define THE app bar SHALL treat it as lockup and in debug builds report it; IF brand holds an image together with brand-symbol or brand-wordmark THE app bar SHALL show the image in brand alone and in debug builds report the others; IF the bar has a brand and brandLabel is empty, or a brand slot holds more than one image, THE app bar SHALL still draw what it holds and in debug builds report what is missing or extra. - **APB-24** WHILE the brand is a lockup THE app bar SHALL draw the symbol comp.app-bar.brand.lockup.symbol.size high, which is the wordmark's height (comp.app-bar.brand.wordmark.height) unless a design system sets it apart, so that the symbol and the wordmark stand at one height; a symbol shown alone keeps comp.app-bar.brand.symbol.size. - **APB-25** WHERE the product puts a control in context THE app bar SHALL place it at the start of the top row after the brand, at comp.app-bar.actions.gap from the brand's cell (from the navigation item WHILE no brand is drawn, and comp.app-bar.container.padding-inline from the start edge WHILE neither is), vertically centred in the row, with the title block after it at comp.app-bar.container.gap; SHALL NOT restyle it, as APB-11 says of the navigation and action items; and SHALL keep it in reading order after the brand and before the title block and the action items. Right-to-left layouts SHALL mirror the order. - **APB-26** THE app bar SHALL draw every action item that fits in the top row, and SHALL set no limit on their number. The actions fit WHILE the row holds, beside them and at their own sizes, the navigation item, the brand's cell and the control in context, and the title block as wide as its title and its subtitle need on one line in the top row's text roles (APB-5) — for a large bar whether or not the top row draws its title now (APB-8), so that no action moves as the bar collapses — with the paddings and gaps APB-4 names, the title block centred on the bar WHILE titleAlignment is center (APB-6), and the more button WHILE overflow is menu and an action is out (APB-28). WHEN the actions do not fit THE app bar SHALL take them out from the end, in reverse reading order and one at a time, skipping every action whose overflow is never and every element of the actions slot that is not a Button, until what remains fits; WHEN what remains still does not fit THE app bar SHALL truncate the title as APB-5 and APB-6 say, and SHALL NOT shrink or take out the navigation item, the brand or the control in context. Right-to-left layouts SHALL mirror the order (APB-4): the actions leave from the end of the reading order, at the left. - **APB-27** WHEN the room the top row has, the size of one of its items, its title or subtitle, or the action items change THE app bar SHALL decide again which actions fit, as APB-26 says, bringing actions back in reading order as soon as they fit, so that which actions are shown depends only on the room and the items, never on the widths the bar had before. - **APB-28** WHILE overflow is menu and at least one action is out (APB-26) THE app bar SHALL draw the more button after the last action still shown, comp.app-bar.actions.gap from it: an icon-only Tanrei Button of the text variant and the medium size showing the glyph more_horiz, named by overflowLabel or the product's words, exposed as a button that opens a menu, with its expanded state while the menu is open; WHILE every action is shown, or overflow is hide, THE app bar SHALL draw no more button. The more button SHALL be a stop in the tab order after the actions shown. - **APB-29** WHEN the more button is activated by pointer, touch, Enter or Space THE app bar SHALL open a Tanrei Menu anchored to it, placed bottom-end, holding the actions that are out, in reading order: each action as a menu item with its label and its glyph as the leading icon, disabled while it is; a toggle as a checkbox item with its selected state; an action that is a link (it has an href) as a link item to the same destination and target; and an action that opens a Menu as a submenu item named by its label, holding that Menu's items. Activating a row SHALL do exactly what activating the action does — the same click (and change), once, from that action — and close the menu, which returns focus to the more button; WHEN the actions that are out change while the menu is open THE app bar SHALL close it. - **APB-30** WHILE overflow is hide THE app bar SHALL draw nothing in place of an action that is out: neither drawn nor focusable nor exposed to assistive technology, it SHALL stay in the page with its state and its listeners, and come back as APB-27 says. Reaching what a hidden action does is the product's responsibility: hide is for an action the product also gives somewhere the person can reach at that width (a drawer, a page's footer, a settings page), and the app bar SHALL NOT report one that is not. - **APB-31** WHEN an action that has keyboard focus goes out (APB-26) THE app bar SHALL move focus, without scrolling the page, to the more button WHILE overflow is menu; and WHILE overflow is hide to the nearest action still shown before it in reading order, else the nearest after it, else the control in context, the brand's link or the navigation item, the last of them that takes focus, so that focus never falls to the page. - **APB-32** THE app bar SHALL decide which actions are shown before the first frame that draws them, and after a change APB-27 names before the next frame, from sizes measured then — each action's while it is drawn, kept while it is out — so that no frame draws an action that then leaves or a more button that then goes away; it SHALL show and hide them at once, without a motion of its own, and deciding SHALL NOT change the room it decides from, so that it never measures again because of its own decision. - **APB-33** WHEN overflow names a value the app bar does not define THE app bar SHALL treat it as menu and in debug builds report the unknown value; WHEN an action's overflow names a value other than never THE app bar SHALL treat it as auto. IF overflow is menu, an action is out and the more button has no name (overflowLabel is empty and the product's words have none) THE app bar SHALL still draw the more button and open its menu, and in debug builds report the missing word. - **APB-34** WHERE the platform shows the product's markup before the component runs (the web, before its element is defined) THE app bar SHALL take, from its first paint, the block size it will have once it runs, so that nothing under it moves when it does: the top system inset (APB-10), and a top row comp.app-bar.container.height.small high, or as high as the cell of an item it holds (APB-11, APB-19) or as the title and, WHILE the title is not empty, the subtitle need on their lines in comp.app-bar.title.typescale.small and comp.app-bar.subtitle.typescale.small (APB-5, APB-15) where that is more; WHILE size is large and the bar will be drawn expanded (APB-9: scrolled is false, or a scrolling view is connected, at its top as a page is when it loads) the title row under it as well: comp.app-bar.container.height.large less comp.app-bar.container.height.small, or as high as the title and the subtitle need in comp.app-bar.title.typescale.large and comp.app-bar.subtitle.typescale.large with comp.app-bar.container.padding-block-end under them where that is more (APB-7). Until it runs THE app bar SHALL fill its container with the container color of its condition (APB-1, APB-2) and SHALL show nothing of what its slots hold, because a glyph is a name until its Button draws it. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.app-bar.…` → `--tanrei-comp-app-bar-…`). #### `tanrei.comp.app-bar` | Token | Type | Value | | --- | --- | --- | | `comp.app-bar.container.height.small` | `dimension` | `64px` | | `comp.app-bar.container.height.large` | `dimension` | `120px` | | `comp.app-bar.container.padding-inline` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.app-bar.container.padding-block-end` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.app-bar.container.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.app-bar.actions.gap` | `dimension` | `{tanrei.sys.target.spacing}` | | `comp.app-bar.brand.symbol.size` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.app-bar.brand.wordmark.height` | `dimension` | `40px` | | `comp.app-bar.brand.image.height` | `dimension` | `{tanrei.comp.app-bar.brand.wordmark.height}` | | `comp.app-bar.brand.lockup.symbol.size` | `dimension` | `{tanrei.comp.app-bar.brand.wordmark.height}` | | `comp.app-bar.brand.lockup.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.app-bar.brand.lockup.alignment` | `number` | `0` | | `comp.app-bar.brand.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.app-bar.brand.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.app-bar.title.typescale.small` | `typography` | `{tanrei.sys.typescale.heading-4}` | | `comp.app-bar.title.typescale.large` | `typography` | `{tanrei.sys.typescale.heading-1}` | | `comp.app-bar.title.inset` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.app-bar.title.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.app-bar.subtitle.typescale.small` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.app-bar.subtitle.typescale.large` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.app-bar.subtitle.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.app-bar.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.app-bar.outline.visibility` | `number` | `{tanrei.sys.behavior.divider-visibility}` | | `comp.app-bar.flat.container.color` | `color` | `{tanrei.sys.color.surface}` | | `comp.app-bar.flat.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.app-bar.flat.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.app-bar.scrolled.container.color` | `color` | `{tanrei.sys.color.surface}` | | `comp.app-bar.scrolled.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.app-bar.scrolled.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.app-bar.motion.condition-duration` | `duration` | `{tanrei.sys.motion.role.state.large}` | | `comp.app-bar.motion.condition-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.app-bar...` for the variants `flat`, `scrolled`, the states and the properties `container.color`, `container.elevation`, `outline.color`. ## App shell > Frames a page or an app: places a header, the navigation, the main content, an aside and a footer, decides from the window's width how each of them is shown, and lets a keyboard reach the content in one step; it draws the frame and none of what stands in it. - Category: Containment - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/app-shell/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/app-shell.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/app-shell`). - React: `AppShell` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-app-shell` | lagging | | SwiftUI | `TanreiAppShell` | planned | | Jetpack Compose | `TanreiAppShell` | planned | | Flutter | `TanreiAppShell` | planned | | React Native | `AppShell` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `footerHidden` (prop) | `footerHidden` | `isFooterHidden` | `footerHidden` | `footerHidden` | `footerHidden` | | `navigationOpen` (prop) | `navigationOpen` | `isNavigationPresented` | `navigationOpen` | `navigationOpen` | `navigationOpen` | | `asideLabel` (prop) | `asideLabel` | `asideLabel` | `asideLabel` | `asideSemanticLabel` | `asideLabel` | | `windowClassChange` (event) | `windowclasschange` | `onWindowClassChange` | `onWindowClassChange` | `onWindowClassChanged` | `onWindowClassChange` | | `navigationOpenChange` (event) | `navigationopenchange` | `isNavigationPresented` | `onNavigationOpenChange` | `onNavigationOpenChanged` | `onNavigationOpenChange` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The frame itself: the whole window (or the whole page), filled with the product's surface color. It carries no state and takes no input. - `skip-link` (optional): A Link the product gives ("Skip to content") that the shell keeps out of sight until the keyboard reaches it, then shows in a small raised box at the top start corner of the window. The first thing the keyboard reaches; following it moves focus to the main region. - `announcement` (optional): A strip across the top of the frame, above the header, for a notice that concerns the whole product (a callout the product places there: an outage, a new version, a page that is not translated). - `header` (optional): The region across the top that names the product or the screen and holds its search and its actions: the product's app bar. The page's banner landmark. - `menu-button` (optional): An icon-only Button the product puts in its header and marks as the shell's — or, in a frame whose header region is empty, gives in the menu-button slot, where it stands alone in the header's place and stays at the top of the window while the page scrolls, with no band around it (APS-34). The shell shows it in every window class (with menuButtonPlacement drawer, only while the navigation has no place in the layout). It opens and closes the navigation over the content, and where the navigation stands beside the content shows, hides or collapses it. - `navigation` (optional): The region at the start edge that holds the product's destinations: a navigation drawer. Beside the main content in a wide window, its column of icons in a narrower one, and over the content in a narrow one — below the header, which stays in view and usable. - `main`: The content the page is for, and the page's one main landmark. Inset from the frame by a gutter and, by default, no wider than a readable width. - `aside` (optional): Content that supports the main content: an outline of the page, details of the selected thing, related links. Beside the main content at the end edge in a wide window, above or below it in a narrower one. A complementary landmark. - `footer` (optional): The region at the end of the page for what belongs to the whole site: its links, its legal line, its language and theme controls. The page's content-information landmark. Shown while the product fills it and has not hidden it (footerHidden). - `navigation-bar` (optional): The place at the bottom edge for a navigation bar, shown only in a narrow window, for a product whose three to five top-level destinations stay in reach of the thumb. - `outline` (optional): The hairline the shell draws between two regions that touch, where the system parts things with a line and the region's own component draws none: above the footer, and at the edge of an aside that is not a side sheet. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `scroll` | `enum`: `page`, `main` | `"page"` | — | What scrolls. page: the whole page scrolls in the window, the header stays at the top (headerPosition) and the navigation and the aside stay in view beside the content; the default, because it is what find-in-page, anchors, the back button's return to where the reader was, and a phone browser's collapsing bars are built for. main: the frame is exactly as tall as the window and only the main region scrolls inside it, for an app whose panes scroll apart from each other (a mail client, an editor). | | `headerPosition` | `enum`: `sticky`, `static` | `"sticky"` | `header-position` | Whether the header stays at the top of the window while the page scrolls (sticky) or scrolls away with it (static: an article that should have the whole window). Ignored while scroll is main, where the header never moves. | | `mainWidth` | `enum`: `contained`, `full` | `"contained"` | `main-width` | contained: the main region's content is no wider than the shell's readable width and is centred in the room the region has, for pages that are read. full: it takes all the room inside the gutters, for a table, a board, an editor. | | `asideOrder` | `enum`: `after`, `before` | `"after"` | `aside-order` | Where the aside stands in reading and focus order, and so where it is drawn when it is not beside the main content. after: it follows the main content and is drawn below it (related links, details). before: it precedes the main content and is drawn above it (an outline of the page, which is of use only before the page is read). Beside the main content it is drawn at the end edge either way. | | `footerHidden` | `boolean` | `false` | `footer-hidden` | Whether the footer is left out of the frame although the product fills it: a screen that is a task rather than a page of the site (a checkout, a sign-in, an editor, a full-window map) keeps the site's footer markup and shows none. While true the footer takes no space, draws no line, is no landmark and has no stop in focus order, exactly as an empty footer region. The footer is shown only while the product fills the footer slot and this is false: footerHidden never makes a footer of an unfilled slot. | | `separation` | `enum`: `auto`, `divider`, `gap` | `"auto"` | `separation` | How regions that touch are told apart. auto takes the design system's choice through comp.app-shell.separation; divider draws the one hairline; gap draws nothing and leaves the regions' own spaces. It concerns only the edges the shell draws: a component in a region that has an edge of its own (an app bar, a navigation drawer, a side sheet) keeps it. | | `navigationOpen` | `boolean` | `false` | `navigation-open` | Whether the navigation is open: presented over the content — below the header — while it has no place of its own in the layout (or only its column), and shown beside the content while it stands there even where a person hid it. The menu button asks for true and, while it is true, for false; beside the content it asks for false as it hides the navigation and for true as it shows it again (NVD-106); closing the navigation makes it false. A change of the window's class keeps it. | | `menuButtonPlacement` | `enum`: `header`, `drawer` | `"header"` | `menu-button-placement` | Where the one control that shows and hides the navigation lives. header: the menu button in the header, in every window class — it opens and closes the navigation over the content where the navigation has no place (or only its column), and where it stands beside the content hides it and shows it again (NVD-106); the default. drawer: the navigation drawer's own menu button (its first header button) collapses and expands it where it has a place, and the header's menu button is shown only where the navigation has none. WHILE the header region is empty the menu button of the menu-button slot is shown as drawer shows it, whatever this says (APS-34). | | `asideLabel` | `string` | `""` | `aside-label` | Names the aside for assistive technology, in the product's language ("On this page"). Required where the aside is filled and what it holds does not name itself (a side sheet is named by its headline). | ### Events | Event | Description | | --- | --- | | `windowClassChange` | The shell decided the window's class for the first time, or the window's width changed it; carries compact, medium or expanded. A product switches what follows the class and has no setting of its own for it: a search's presentation, a side sheet's variant, the form of an outline. | | `navigationOpenChange` | The navigation asks to be presented over the content or to be put away: the menu button was activated while it was closed (true), or the open navigation closed — by its scrim, Escape, the platform's back, a drag, a destination that was activated, the menu button (false); and beside the content, the menu button hid a navigation that was open (false) or showed it again (true). A change of the window's class emits none. Carries the value asked for. | ### Slots | Slot | Description | | --- | --- | | `default` | The main region: the page's content. A fixture's content string is plain text. | | `skip-link` | The skip link: a standalone Link whose destination is the main region, with the product's words ("Skip to content"). More than one may be given ("Skip to navigation"); each is shown while it has focus. | | `announcement` | The notice above the header: a callout the product places, drawn across the frame's width. | | `header` | The header: the product's app bar, with its search and its actions, and the menu button in its navigation slot. | | `menu-button` | The menu button of a frame whose header region is empty: the menu-button item, which the shell places alone in the header's place and keeps at the top of the window (APS-34). Not shown while the header region holds something, where the menu button belongs in the header. A fixture gives it as its menu-button item, not as a string. | | `navigation` | The navigation: a navigation drawer, which draws each of the three presentations itself. Anything else is placed beside the content where the navigation has a place and is not shown where it has none. | | `aside` | The aside: the product's supporting content, or a side sheet. | | `footer` | The footer: the product's own layout of links, a legal line and controls. The shell gives it a place and an inset and no anatomy. | | `navigation-bar` | A navigation bar for the bottom edge of a narrow window. | ### Item: `menu-button` The one icon-only Button in the header — or, while the header region is empty, in the menu-button slot — that opens the navigation: a Button of the text variant and the medium size with the menu glyph and no label, unless the product sets otherwise, which the shell shows by menuButtonPlacement and does not restyle. It is a Button. Names: Web `tanrei-button`, SwiftUI `TanreiButton`, Jetpack Compose `TanreiButton`, Flutter `TanreiButton`, React Native `Button`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `label` | `string` | `""` | `label` | Its accessible name ("Menu"), as the Button's label. Required. | | Event | Description | | --- | --- | | `click` | The button was activated, as the Button's click. The shell answers it itself (APS-7); a product need not. | | Slot | Description | | --- | --- | | `icon` | Its glyph, as the Button's icon slot. A fixture item's content is this glyph. | ### States `enabled` ### Accessibility - Role: `none` - Labeling: The shell has no role and no name. Its regions are the page's landmarks: banner (the header), navigation (named by the label of the navigation drawer or the navigation bar it holds), main (exactly one, unnamed), complementary (the aside, named by asideLabel or by the side sheet's headline) and content information (the footer, while it is shown: an unfilled or hidden footer is no landmark). The skip link is named by its own text and the menu button by its label, both in the product's language: Tanrei ships no words. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves through the frame in reading order: the skip link, the announcement, the header (or, while the header region is empty, the menu button of the menu-button slot), the navigation, the main content and the aside in the order asideOrder gives, the footer, the navigation bar. The shell itself is not a stop. While the navigation is open over the content below the header, only the announcement, the header and the navigation have stops; in a frame without a header the open navigation is a modal drawer that keeps focus inside it. | | Enter, on the skip link | Moves focus to the main region and brings its top into view below the header. | | Enter or Space, on the menu button | Opens the navigation over the content, below the header (over the whole window in a frame without a header, APS-34), and moves focus into it; while it is open, closes it. Where the navigation stands beside the content, hides it and shows it again, the main content taking its room while it is hidden; focus stays on the menu button, which stays where it is. Escape in the open navigation closes it and returns focus to the menu button (the navigation drawer's own keys). | | / (a filterable drawer's chord, in a narrow window) | Opens the navigation over the content and moves focus to the drawer's filter field (APS-33). Where the drawer is shown, the drawer answers it. | - The shell takes no input: the skip link is a Link and the menu button an icon-only Button, and each meets the minimum target by its own spec (LNK-17, BTN-5). - The skip link is what lets a keyboard pass the header and the navigation in one step (WCAG 2.4.1); the landmarks let a screen reader do the same. Both are needed: a sighted keyboard user has no landmark list. - Focus is never hidden by the frame (WCAG 2.4.11): the scrolling view keeps the height of the sticky header and of the navigation bar clear when it brings a focused element into view (APS-17). - While the navigation is open over the content it is drawn below the header and stays the navigation landmark the expanded menu button controls; it is not a modal dialog, because the header stays usable and a dialog would tell assistive technology that everything else is inert. The regions under the scrim are made inert instead, so nothing that cannot be seen can be reached (the disclosure pattern for a site's navigation, with the covered content inert). - Reading order, focus order and the order of the markup are one order in every window class (APS-22), which is why the aside's place is a setting (asideOrder) and not something the layout rearranges by width. - Reflow (WCAG 1.4.10): at 320 points the frame is one column; the widths that decide the class grow with the text on the web (APS-2), so 200 % text in a 1280 window is laid out as a medium one. - A second navigation landmark is not an error: a navigation drawer, a navigation bar, breadcrumbs and a pagination each name themselves, and only one of the drawer and the bar is shown at a time unless the product keeps both. - On SwiftUI, Compose, Flutter and React Native there is no skip link: each platform's assistive technology moves between regions by its own gesture or rotor, and the shell marks the regions for it. ### Behaviour Requirements in EARS form, each with its stable id. - **APS-1** THE app shell SHALL fill the window with comp.app-shell.container.color, hand everything it holds comp.app-shell.content.color as the platform's inherited foreground, and place its regions in this order: the announcement across the top; the header across the top below it (WHILE the header region is empty, the menu button of the menu-button slot alone in its place, APS-34); then a row that holds the navigation at the start edge, the main region, and the aside at the end edge; the footer across the bottom of the page; and the navigation bar across the bottom edge of the window. A region that holds nothing, and the footer WHILE footerHidden is true (APS-31), SHALL take no space, draw nothing and add no landmark, and the regions beside it SHALL take its room. THE app shell SHALL draw no elevation and no corner of its own. - **APS-2** THE app shell SHALL give the window one of three classes by its width alone: compact WHILE the window is narrower than comp.app-shell.breakpoint.medium, medium WHILE it is at least that wide and narrower than comp.app-shell.breakpoint.expanded, and expanded WHILE it is at least comp.app-shell.breakpoint.expanded wide. It SHALL derive the class anew whenever the width changes, SHALL never store it, and SHALL NOT read the window's height, the device, the pointer or the orientation for it. WHERE the platform measures a window in a unit that grows with the reader's text size (the web's rem) the two widths SHALL be compared in that unit, so that enlarged text moves the frame to a narrower class before its columns become too narrow to read. - **APS-3** WHEN the app shell first decides the window's class, and WHEN a change of the window's width changes it, THE app shell SHALL emit windowClassChange exactly once with the class, and SHALL make the present class known to everything it holds through the platform's own channel for inherited values, so that a component inside it can follow the class without measuring the window itself. A change of width inside one class SHALL emit nothing. - **APS-4** THE app shell SHALL choose how the navigation is presented from the window's class: WHILE the class is expanded, beside the main region in the form the navigation drawer's expanded gives it (the standard presentation, NVD-53: its full form, its collapsed form, or — for a drawer a person hid there with the menu button, NVD-106 — no place at all, the main region taking its room); WHILE it is medium and what the navigation region holds has a collapsed form (a collapsible navigation drawer), as that collapsed form beside the main region, widening over the content WHILE navigationOpen is true (the column presentation); and otherwise with no place in the layout, presented over the content WHILE navigationOpen is true (the modal presentation). WHILE the header region holds something, the navigation presented over the content — in the column and in the modal presentation alike — SHALL be drawn inside the frame below the header, from the header's bottom edge (from the window's top edge WHILE a static header has scrolled out of view) to the window's bottom edge, and its scrim SHALL cover only that part of the frame, so that the header is never covered or dimmed (APS-7, APS-32); WHILE the header region is empty it SHALL be drawn as APS-34 says. A navigation drawer in the region SHALL be drawn in each presentation exactly as a responsive drawer draws it (NVD-53 to NVD-55), and the two SHALL never disagree, because comp.app-shell.breakpoint.medium and comp.app-shell.breakpoint.expanded and the two widths that drawer reads alias the same window classes of the system (sys.breakpoint.medium, sys.breakpoint.expanded). WHILE the presentation is modal and the region holds something that cannot present itself over the content THE app shell SHALL NOT show it, SHALL keep it from focus and from assistive technology, and in debug builds SHALL report that the navigation of a narrow window needs a navigation drawer. - **APS-5** WHILE the navigation has a place in the layout THE app shell SHALL put it at the start edge of the row, as wide as what it holds draws itself (a navigation drawer's width in its present form) and never wider than the room the row leaves it — the window (its width as the page has it: less a scrollbar that takes room in it) less the main region's least width (its start and end insets, APS-8, and sys.target.touch between them) and less the aside WHILE the aside stands beside the main region (APS-9: comp.app-shell.aside.width, or a side sheet's own width as it is drawn, APS-10) — even where what it holds asks for more (a navigation drawer's least width included, NVD-97), so that neither the main region nor the aside is pushed past the window's end and the page never scrolls sideways (WCAG 1.4.10); THE app shell SHALL give the main region all the room that is left, and SHALL add no padding, fill or edge to it. WHEN that room changes (the window's width, an aside added or removed, a side sheet sliding in or out) the navigation SHALL be held to it in every frame it is drawn, with no motion of its own beyond what changes the room. WHILE scroll is page THE app shell SHALL keep the navigation in view while the page scrolls — from below the header WHILE the header is sticky, from below the menu button WHILE a frame without a header shows it (APS-34), else from the top of the window, to the window's bottom edge — and what it holds SHALL scroll inside that height by itself (NVD-61), never the page with it. WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll) the navigation SHALL stay where it is: only the page's content moves with the pull. WHILE a person changes the width of a navigation drawer the navigation holds (NVD-98 to NVD-101) THE app shell SHALL give the main region the room that is left in every frame the width changes, the main region moving with no motion of its own, and SHALL keep the reader at the same place in the main content as far as the new width allows, as APS-23 does when the class changes. - **APS-6** WHILE menuButtonPlacement is header and the navigation region holds a navigation drawer THE app shell SHALL show the menu button where the product put it in the header in every window class and every presentation, whether the navigation is open or not. WHILE menuButtonPlacement is drawer THE app shell SHALL show it only WHILE the presentation is modal, and WHILE it is standard and the drawer is responsive and either has no collapsed form, whether it is shown or hidden, or is hidden there (NVD-106): a drawer with no collapsed form has no menu button of its own (NVD-37), so the control that shows it SHALL stay to hide it again, in the same place, and the control that hid a drawer SHALL stay to show it again; in the column presentation, and in the standard one for a collapsible drawer that is shown, the drawer's own menu button (NVD-37) stands for it. WHEN an activation of the menu button shows or hides a drawer beside the content THE app shell SHALL leave focus on the menu button, which stays where it is. WHERE that activation shows a collapsible drawer again and so takes the menu button away (WHILE menuButtonPlacement is drawer, or the header region is empty), THE app shell SHALL move focus that was on it to the drawer's own menu button (NVD-37), or else to the main region. WHILE the header region is empty THE app shell SHALL show the menu button of the menu-button slot as APS-34 says, whatever menuButtonPlacement says. WHILE the navigation region holds something other than a navigation drawer THE app shell SHALL show the menu button only WHILE the presentation is modal, where APS-4 reports it. WHILE the navigation region is empty, and wherever this sentence does not show it, THE app shell SHALL NOT show the menu button, SHALL keep it from focus and from assistive technology, and SHALL give its place to what is beside it. WHEN menuButtonPlacement names a value the app shell does not define it SHALL be treated as header. THE app shell SHALL NOT restyle the menu button: it SHALL render as the icon-only Button it is, from its own tokens, with its own press, focus ring and minimum target, and its glyph SHALL stay the same while the navigation is open — its expanded state, not its picture, tells that it is. - **APS-7** WHEN the menu button is activated THE app shell SHALL ask the navigation drawer in the navigation region for what the drawer's own menu button asks (NVD-37), in every presentation: WHILE the presentation is standard, to hide the navigation where it is shown there and to show it again where it is hidden (NVD-106), whatever its form — the drawer applies it and reports it with standardHiddenChange, and THE app shell SHALL emit navigationOpenChange exactly once WHERE navigationOpen changes with it (false as a drawer that was open is hidden, true as one is shown) and make navigationOpen follow the drawer's open; the main region SHALL take the room the hidden navigation leaves, the drawer's slide resizing it, and nothing SHALL be made inert; WHILE it is column or modal and navigationOpen is false, to open — THE app shell SHALL then emit navigationOpenChange exactly once with true and become open (by setting navigationOpen itself on the web, through its binding where navigationOpen is one, and by the product setting it elsewhere), and the drawer SHALL present itself over the content below the header (APS-4, NVD-19) — over the whole window WHILE the header region is empty (APS-34) — taking focus; and WHILE navigationOpen is true, to close (NVD-20). WHILE the navigation is open over the content below the header THE app shell SHALL keep the announcement and the header as they are — drawn, reachable by pointer and keyboard and exposed to assistive technology, never inert — and SHALL make every other region inert to pointer, touch, keyboard and assistive technology (the skip link, the main region, the aside, the footer and the navigation bar), keeping the page from scrolling under the scrim as a modal layer does (MDL-2). WHEN the open navigation begins to close (NVD-20, NVD-21) THE app shell SHALL at once emit navigationOpenChange exactly once with false, navigationOpen SHALL become false the same way, and the regions it made inert SHALL stop being inert; focus moves as NVD-22 says, to the menu button where the menu button opened the navigation; its scrim is taken away at once (MOT-8), the drawer then leaves by its motion, and nothing SHALL change when that motion ends (NVD-22). THE app shell SHALL expose the menu button as expanded WHILE the navigation is open over the content, and in the standard presentation WHILE the drawer is shown there in either form, and as collapsed otherwise, controlling the navigation WHILE the navigation is shown — open over the content, or standing beside it in either form — and naming nothing WHILE it is not shown (modal and closed, or hidden beside the content), so that the button never names an element that is not exposed. WHEN the menu button hides or shows the navigation beside the content, focus SHALL stay on it (APS-6), and focus that was in the drawer SHALL move to it (NVD-106). A change of the window's class SHALL NOT change navigationOpen and SHALL emit no navigationOpenChange; WHILE the navigation stands beside the content and navigationOpen is true THE app shell SHALL make nothing inert, and WHEN the navigation is presented over the content again WHILE navigationOpen is true it SHALL make the regions under the scrim inert as an opening does (NVD-54 moves focus). - **APS-8** THE app shell SHALL inset the main region's content from the region's start and end by the gutter of the window's class — comp.app-shell.gutter.compact, comp.app-shell.gutter.medium or comp.app-shell.gutter.expanded — and from its top and bottom by comp.app-shell.main.padding-block, except, WHILE scroll is page, on a side where an aside stands above or below it, where the two share comp.app-shell.aside.gap instead (APS-9). WHILE mainWidth is contained the content SHALL be no wider than comp.app-shell.main.max-width and SHALL be centred in the room the region has inside its gutters; WHILE mainWidth is full it SHALL take all of that room. THE main region SHALL never be wider than the room the row leaves it: content that cannot shrink (a table, a line of code) SHALL scroll inside its own box (PRS-15), and SHALL NOT widen the frame or make the page scroll sideways. WHILE the navigation region holds a navigation drawer that draws its resize handle beside its end edge (NVD-96) THE app shell SHALL inset the content of the main region, and of an aside stacked in its column, from the region's start by the greater of the gutter and the handle's target across that edge (sys.target.pointer for a fine pointer, sys.target.touch for touch or where the input type cannot be told, HDL-5), so that the target lies over that inset alone and a press meant for the main content never reaches the handle (WCAG 2.5.8); WHILE the drawer draws no handle (resizable false, or the drawer not beside the content) the gutter alone SHALL inset it. - **APS-9** WHILE the window's class is expanded THE app shell SHALL place the aside beside the main region at the end edge of the row, comp.app-shell.aside.width wide, its content inset by comp.app-shell.aside.padding-inline at the start and the end and by comp.app-shell.main.padding-block at the top and the bottom, so that its first line stands level with the main content's; WHILE scroll is page it SHALL keep the aside in view while the page scrolls, as APS-5 says of the navigation, and the aside SHALL scroll inside that height by itself when its content is taller, and SHALL stay where it is WHEN the window's scrolling view is pulled past its start or its end. WHILE the class is medium or compact THE app shell SHALL place the aside in the main region's column, with the main region's gutters and, WHILE mainWidth is contained, its width and centring: above the main content WHILE asideOrder is before and below it WHILE asideOrder is after, comp.app-shell.aside.gap from it, scrolling with it. WHILE scroll is page that space SHALL take the place of the main region's inset on that side (APS-8) and SHALL be shared by the two regions, which meet in its middle, where the line of APS-18 stands: neither region's box SHALL reach into the other's, so that a press, a fill the product gives the main region and the outline assistive technology draws around a landmark keep to their own region. - **APS-10** WHERE the aside holds a component that takes its own width in the layout and draws its own edge (a standard side sheet, SSH-1 and SSH-7) THE app shell SHALL give the aside that component's width in place of comp.app-shell.aside.width, SHALL add no inset to it and SHALL draw no edge beside it; WHERE it holds a component that presents itself over the content (a modal side sheet) the aside SHALL take no space in any class. THE app shell SHALL NOT change the variant of what the aside holds: a product that wants a sheet beside the content in an expanded window and over it in a narrower one sets the sheet's variant from windowClassChange. - **APS-11** WHILE scroll is page THE app shell SHALL place the footer after the row of the navigation, the main region and the aside, across the frame's whole width, so that it is reached at the end of the page and the navigation and the aside stop staying in view where it begins; WHILE scroll is main THE app shell SHALL keep the footer at the bottom of the frame, below the row and above the navigation bar, always in view. THE app shell SHALL inset the footer's content by the gutter of the window's class (APS-8) at the start and the end and by comp.app-shell.footer.padding-block at the top and the bottom, and SHALL lay out nothing inside it: the footer's columns, links and controls are the product's. - **APS-31** WHILE footerHidden is true THE app shell SHALL NOT show the footer, whatever the footer slot holds: the footer SHALL take no space, draw no line (APS-18), add no landmark (APS-21) and have no stop in focus order (APS-22), the regions beside it SHALL take its room, and WHILE scroll is page the navigation and the aside SHALL stay in view to the end of the page (APS-5, APS-9). WHILE footerHidden is false THE app shell SHALL show the footer exactly while the product fills the footer slot (APS-1, APS-11): it SHALL NOT draw a footer, or expose a content-information landmark, for a slot the product left unfilled. WHEN footerHidden changes THE app shell SHALL draw the new arrangement at once, without a motion of its own, SHALL keep what the footer slot holds as the product gave it, and IF keyboard focus is in the footer as it is hidden SHALL move focus to the main region. - **APS-32** THE app shell SHALL draw each region in a stacking order of its own, so that nothing a region holds — whatever level its own stacking order (a z-index) gives it — is drawn over another region: WHILE scroll is page THE app shell SHALL draw the header and the navigation bar over every other region, the footer included, while the page scrolls under them, and SHALL draw the footer over the navigation and the aside. WHILE the navigation is presented over the content below the header (APS-4, APS-7) THE app shell SHALL draw the navigation and its scrim over the main region, the aside, the footer and the navigation bar and under the announcement and the header, within the frame's own stacking order and not in the platform's layer for overlays, so that the header is never covered or dimmed. WHILE the skip link has keyboard focus THE app shell SHALL draw it over every region (APS-19). THE app shell SHALL itself be one stacking order within the page, so that no level of its parts competes with what the product draws outside the frame. What stands over the whole frame — a menu, a popover, a tooltip, a snackbar, a dialog, a sheet, a modal drawer the app shell does not hold — SHALL be drawn above it by the platform's own layer for overlays, never by a level within a region. - **APS-12** WHILE the announcement region holds something THE app shell SHALL place it across the frame's whole width above the header, with no inset of its own, in every class; WHILE scroll is page the announcement SHALL scroll away with the page and a sticky header SHALL then rest at the top of the window, and WHILE scroll is main it SHALL stay above the header. WHEN what the announcement holds is removed or closes (a callout whose open becomes false) THE app shell SHALL give its room back at once. - **APS-13** WHILE the window's class is compact and the navigation-bar region holds something THE app shell SHALL keep it at the bottom edge of the window across the frame's whole width, over the bottom system inset as the bar itself lays out (NVB-18), in view while the page scrolls, and SHALL end the page, or the frame, above it so that nothing is covered by it; WHILE the class is medium or expanded THE app shell SHALL NOT show the navigation-bar region, SHALL keep it from focus and from assistive technology, and SHALL give it no space. THE app shell SHALL NOT choose between the bar and the navigation for the product: a product whose bar is its navigation in a compact window gives no menu button. - **APS-14** WHILE scroll is page THE app shell SHALL be at least as tall as the window and as tall as its content, SHALL let the window's own scrolling view scroll the page, and SHALL make no region a scrolling view except the navigation and the aside where APS-5 and APS-9 keep them in view; so that the platform's find-in-page, a link to a place in the page, the return to where the reader was, and a browser's collapsing bars work as they do on a page without a shell. - **APS-15** WHILE scroll is main THE app shell SHALL be exactly as tall as the window, less the on-screen keyboard where one covers it, SHALL keep the announcement, the header, the footer and the navigation bar in place, and SHALL make the main region the one scrolling view of the frame, reachable and scrollable from the keyboard, with the aside scrolling inside its own height WHILE it is beside the main region and with the main region WHILE it is above or below it. THE window itself SHALL NOT scroll. - **APS-16** WHILE scroll is page and headerPosition is sticky THE app shell SHALL keep the header at the top of the window, above the main region, the navigation and the aside, while the page scrolls under it, and SHALL keep it there WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll): the content moves with the pull and the header does not; WHILE headerPosition is static the header SHALL scroll away with the page. THE app shell SHALL NOT fill, raise or edge the header: an app bar in it draws its own scrolled condition from the scrolling view it is connected to (APB-9), which is the window WHILE scroll is page and the main region WHILE scroll is main. - **APS-17** THE app shell SHALL hold the height of what it keeps over the top of the scrolling view — a sticky header's present height, measured again whenever the header changes size, and nothing WHILE headerPosition is static — and SHALL make it known to the scrolling view and to everything it holds, so that a heading or any other place a link or the address moves the view to (PRS-23), and an element that takes keyboard focus, come to rest below the header and never under it; likewise for the navigation bar's height at the bottom; WHILE scroll is main nothing stands over the scrolling view, and those distances are nothing. THE app shell SHALL also make known, whatever scroll is, to what is drawn over the page (a snackbar, SNK-13, SNK-35) how far it reaches over the top of the window — to the bottom edge of the header, or of the menu button of a frame without a header, WHILE that stays in view (WHILE scroll is main it never moves, below an announcement too) — and over its bottom (the navigation bar's height WHILE the bar is shown), so that such a surface stands clear of them. A heading's own space before it (PRS-6) is added to that distance by the prose, not by the shell. - **APS-18** WHILE separation is auto THE app shell SHALL part its regions as comp.app-shell.separation names, and WHILE separation is divider or gap as that value says, whatever the token says: divider draws a line comp.app-shell.outline.width thick in comp.app-shell.outline.color along the footer's top edge, along the start edge of an aside that stands beside the main region, and between the main content and an aside that stands above or below it, in the middle of comp.app-shell.aside.gap; gap draws no line and leaves the same spaces. The lines SHALL take no room of their own. THE app shell SHALL draw no line beside a region whose component draws its own edge (APS-10, APS-16) and none around the navigation, the announcement or the navigation bar. WHEN separation names a value the app shell does not define it SHALL be treated as auto. - **APS-19** WHILE the skip-link region holds a Link THE app shell SHALL make it the first element the keyboard reaches in the frame, before the announcement and the header, SHALL draw nothing of it while it does not have keyboard focus and still keep it in the focus order and exposed to assistive technology, and WHILE it has keyboard focus SHALL draw it comp.app-shell.skip-link.offset from the top and the start edges of the window, inside the system insets, above every region and every sticky part: in a box filled with comp.app-shell.skip-link.container.color and raised by comp.app-shell.skip-link.container.elevation, with corners comp.app-shell.skip-link.container.shape eased by sys.shape.corner-smoothing, padded by comp.app-shell.skip-link.container.padding-inline and comp.app-shell.skip-link.container.padding-block, its text in comp.app-shell.skip-link.label.typescale; the Link SHALL keep its own color, underline, focus ring and states (LNK-1). The box SHALL appear and go at once, without motion, and SHALL move no other part of the frame. - **APS-20** WHEN the skip link is followed THE app shell SHALL move keyboard focus to the main region itself — not to the first control in it — and bring the region's top into view below the header (APS-17) at once, without a scrolling motion, so that the next Tab reaches the first focusable element of the content and a screen reader starts reading there; the main region SHALL take focus only this way and SHALL NOT be a stop of the Tab order. - **APS-21** THE app shell SHALL expose each filled region as the landmark it is: the header as the page's banner, the navigation and the navigation bar as what they hold expose (a navigation landmark named by its own label), the main region as the page's one main landmark, the aside as a complementary landmark named by asideLabel (or by what it holds, where that names itself), and the footer as the page's content information; the announcement, the skip link and the menu button of the menu-button slot SHALL add no landmark. IF the frame holds no main region, or more than one, or an aside that has no name, THE app shell SHALL still lay out what it holds, and in debug builds SHALL report it. - **APS-22** THE app shell SHALL NOT be focusable and SHALL move focus through its regions in reading order, the same in every class and in either layout direction: the skip link, the announcement, the header (WHILE it is empty, the menu button of the menu-button slot, APS-34), the navigation, the aside WHILE asideOrder is before, the main region's content, the aside WHILE asideOrder is after, the footer, the navigation bar. A region that is not shown (APS-4, APS-6, APS-13, APS-31), and WHILE the navigation is open over the content below the header a region the app shell makes inert (APS-7), SHALL have no stop in that order. THE app shell SHALL NOT keep focus inside any region: WHILE the navigation is open over the content below the header, Tab and Shift+Tab SHALL move through the announcement, the header and the navigation in that order and on to what the platform has beyond the frame, and never reach what lies under the scrim. Only an overlay that stands over the whole frame (APS-32) holds focus inside itself. - **APS-23** WHEN the window's class changes THE app shell SHALL draw the new arrangement of every region but the navigation at once, without a motion of its own, and SHALL let the navigation drawer move from its place in the old presentation to its place in the new one by the drawer's own motion (NVD-54), drawn over the main region where the two overlap while it moves; SHALL keep scroll, headerPosition, mainWidth, asideOrder, footerHidden, separation and menuButtonPlacement as they are, and navigationOpen (APS-7, NVD-54); SHALL keep the reader at the same place in the main content as far as the new arrangement allows; and IF keyboard focus is on something the new arrangement does not show (a navigation bar's destination, a menu button that menuButtonPlacement drawer hides) SHALL move it to the main region, unless the navigation it holds has already moved it (NVD-54). WHERE motion is reduced the navigation SHALL take its new place as MOT-6 says, its change of size at once. - **APS-24** WHERE the app shell is rendered before the window's width is known or before its own code runs (a page rendered on a server) THE app shell SHALL already be laid out for the window's class by the platform's layout alone — every region in its place, the regions that the class does not show taking no space, the skip link first and working — SHALL present nothing over the content, SHALL make nothing inert, and SHALL emit no event until the class is decided; its own code SHALL then add only what layout cannot: the events, the menu button's opening of the navigation, and the measured distance of APS-17, without moving anything that was already drawn. WHERE a navigation drawer in the navigation region is rendered before its own code runs THE app shell SHALL give it, in an expanded window, the place it will take once its code runs: its expanded width held as NVD-97 holds it (the width the product gave it, between its least and its greatest width); its collapsed column (comp.navigation-drawer.collapsed.container.width.medium, or .compact WHILE density is compact) WHILE it is collapsible and expanded is false or its variant is modal (NVD-30); and no space WHILE it is responsive, standardHidden is true and open is false (NVD-106). - **APS-25** WHILE the text size is enlarged THE app shell SHALL keep its gutters and insets, let every region grow with its text, and SHALL need no scrolling in two directions at any width down to 320 points: in a compact window the frame is one column, the main region never narrower than the window less two gutters, and only a block that scrolls in its own box (APS-8) scrolls sideways. THE app shell SHALL NOT fix the height of any region. - **APS-26** WHERE the platform's forced-colors or increased-contrast mode replaces the product's colors THE app shell SHALL let the system's colors fill its frame, SHALL draw the lines of APS-18 in the system's text color WHILE they are drawn, and SHALL draw an edge comp.app-shell.outline.width thick in the system's text color around the skip link's box, because the mode removes the fill and the elevation that set it apart. - **APS-27** THE app shell SHALL extend its fill under every system inset (status bar, camera cutout, home indicator, window caption) and SHALL keep the main region's, the aside's and the footer's content inside the start, end and bottom insets; the header, the navigation and the navigation bar lay themselves out over the insets at their own edges (APB-10, NVD-25, NVB-18), and the app shell SHALL NOT inset them a second time. - **APS-28** THE app shell SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the app shell is shown THE app shell SHALL draw itself for the new direction at once, without a motion of its own, keeping the window's class, navigationOpen and the reader's place in the content. WHERE the layout direction is right-to-left the navigation SHALL stand at the right edge and the aside at the left, the skip link's box at the top right, the menu button where the header puts its start, and the lines of APS-18 on the mirrored edges; the order of APS-22 SHALL NOT change, and nothing a region holds SHALL be mirrored by the shell. - **APS-29** WHEN scroll, headerPosition, mainWidth or asideOrder names a value the app shell does not define THE app shell SHALL render with that prop's default, and in debug builds report the unknown value. - **APS-30** THE app shell SHALL NOT restyle, resize or re-order what the product puts in a region beyond the place and the insets this spec gives, SHALL NOT decide which page is shown, follow a link, load anything, remember anything beyond its own lifetime (which page, how far a region was scrolled, whether the navigation was collapsed, how wide a person made it) or set the document's title or language; and SHALL NOT scroll anything with motion: every movement it causes (APS-17, APS-20, APS-23) is at once, whether or not motion is reduced. - **APS-33** WHILE the navigation region holds a navigation drawer whose filterable is true and whose filterShortcut holds exactly one chord, and either the navigation's presentation is modal and navigationOpen is false or it is standard and the drawer is hidden there (NVD-106), WHEN the person presses that chord anywhere in the window — read as SRC-38 reads a chord and with its exceptions (a press something else has taken, a key repeating while held, an input-method composition and, for a chord without mod, ctrl or alt, focus in an element that takes text) — THE app shell SHALL keep the press from doing anything else, open the navigation as an activation of the menu button does (APS-7: navigationOpenChange with true; where the drawer is hidden beside the content, its standardHidden becoming false), and ask the drawer to focus its filter (NVD-88), so that focus is in the drawer's filter field once it is open. WHILE the drawer is shown — beside the main region, or as its column — the drawer answers the chord itself (NVD-87) and THE app shell SHALL NOT. THE app shell SHALL bind no other key for the navigation. - **APS-34** WHILE the header region is empty THE app shell SHALL take the menu button from the menu-button slot and SHALL show it only where APS-6 shows the menu button WHILE menuButtonPlacement is drawer, whatever menuButtonPlacement says — WHILE the navigation's presentation is modal, and WHILE it is standard and the drawer is responsive and either has no collapsed form, whether it is shown or hidden, or is hidden there (NVD-106): in the column presentation, and in the standard one for any other navigation, the navigation stands at the start edge from the top of the frame, below the announcement, to the window's bottom edge (APS-5), and a navigation drawer's own menu button (NVD-37) stands for the shell's. WHILE it is shown THE app shell SHALL place the menu button alone in the header's place — below the announcement, at the start edge of the frame — inset from the top of that place and from the frame's start edge by the gutter of the window's class (APS-8) and kept inside the system insets, SHALL draw no band, fill, edge or elevation around it, and SHALL begin the navigation, the main region and the aside below it, so that the button that shows a drawer beside the content stays in the same place, never covered by the drawer, to hide it again. WHILE scroll is page THE app shell SHALL keep the menu button at the top of the window, the gutter from its top edge, while the page scrolls under it — once an announcement above it has scrolled away (APS-12) — whatever headerPosition says, SHALL draw it over every other region as it draws a sticky header (APS-32), and SHALL keep it where it is WHEN the window's scrolling view is pulled past its start or its end (the platform's overscroll): only the content moves with the pull. WHILE scroll is main it SHALL stay in its place above the main region. THE app shell SHALL hold the gutter above the menu button and its height as what it keeps over the top of the scrolling view, as APS-17 holds a sticky header's, so that an anchor's target and a focused element come to rest below it. The menu button SHALL add no landmark and no region (APS-21), SHALL be reached in the header's place in the order of APS-22, and SHALL keep its keys; activating it SHALL open and close the navigation, or show and hide a drawer beside the content, as APS-7 says, focus staying on it where the drawer stands beside the content as APS-6 says. WHILE the navigation is open over the content THE app shell SHALL let the navigation drawer present itself as it does outside a frame that has a header (NVD-19): over the whole window from its top edge to its bottom edge, its scrim over the menu button and every region, keeping focus inside it and making what lies behind it inert while it is open, and returning focus to the menu button when it closes (NVD-22). WHILE the header region holds something THE app shell SHALL NOT show what the menu-button slot holds, SHALL keep it from focus and from assistive technology, and in debug builds SHALL report that the menu button of a frame with a header belongs in the header. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.app-shell.…` → `--tanrei-comp-app-shell-…`). #### `tanrei.comp.app-shell` | Token | Type | Value | | --- | --- | --- | | `comp.app-shell.container.color` | `color` | `{tanrei.sys.color.surface}` | | `comp.app-shell.content.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.app-shell.breakpoint.medium` | `dimension` | `{tanrei.sys.breakpoint.medium}` | | `comp.app-shell.breakpoint.expanded` | `dimension` | `{tanrei.sys.breakpoint.expanded}` | | `comp.app-shell.gutter.compact` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.app-shell.gutter.medium` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.app-shell.gutter.expanded` | `dimension` | `{tanrei.sys.space.space400}` | | `comp.app-shell.main.max-width` | `dimension` | `768px` | | `comp.app-shell.main.padding-block` | `dimension` | `{tanrei.sys.space.space400}` | | `comp.app-shell.aside.width` | `dimension` | `240px` | | `comp.app-shell.aside.padding-inline` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.app-shell.aside.gap` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.app-shell.footer.padding-block` | `dimension` | `{tanrei.sys.space.space400}` | | `comp.app-shell.separation` | `number` | `{tanrei.sys.behavior.separation}` | | `comp.app-shell.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.app-shell.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.app-shell.skip-link.container.color` | `color` | `{tanrei.sys.color.surface-container-high}` | | `comp.app-shell.skip-link.container.elevation` | `shadow` | `{tanrei.sys.elevation.level3}` | | `comp.app-shell.skip-link.container.shape` | `dimension` | `{tanrei.sys.shape.corner.small}` | | `comp.app-shell.skip-link.container.padding-inline` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.app-shell.skip-link.container.padding-block` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.app-shell.skip-link.offset` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.app-shell.skip-link.label.typescale` | `typography` | `{tanrei.sys.typescale.label}` | ## Avatar > Stands for a person, or for a team or a project, by a small picture, by initials or a glyph where there is no picture, in a round or a square box of three sizes; several are shown as one overlapping group that counts the ones it does not draw. A picture, never a control. - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/avatar/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/avatar.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/avatar`). - React: `Avatar` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-avatar` | lagging | | SwiftUI | `TanreiAvatar` | planned | | Jetpack Compose | `TanreiAvatar` | planned | | Flutter | `TanreiAvatar` | planned | | React Native | `Avatar` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `src` (prop) | `src` | `url` | `model` | `image` | `source` | | `label` (prop) | `label` | `name` | `name` | `name` | `name` | | `decorative` (prop) | `decorative` | `isDecorative` | `decorative` | `decorative` | `decorative` | | `overflowLabel` (prop) | `overflowLabel` | `overflowLabel` | `overflowDescription` | `overflowSemanticLabel` | `overflowAccessibilityLabel` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The square box of the avatar's size, clipped to a circle or to a rounded square, with a quiet fill that shows behind the initials, the glyph, a picture that is still loading and the transparent parts of a picture. It carries no state: nothing about it answers a pointer, a press or focus. - `image` (optional): The picture the product names by its address, filling the box and clipped to its shape. Drawn once it has loaded. - `label` (optional): The initials the product gives, drawn at the centre of the box where there is no picture to show. A picture of a name, not text to be read: the name is the avatar's label. - `icon` (optional): The fallback glyph, at the centre of the box, where there is neither a picture nor initials: the glyph the product names, or the system's own (a person for a circle, a neutral mark for a square). - `group` (optional): Several avatars drawn as one row in which each lies a little over the one before it, with a gap around each so that two pictures are read as two. The group gives its avatars their size and shape. - `overflow` (optional): The last box of a group that does not draw all its members: an avatar-sized box in the fallback's colors holding a plus sign and the number of members not drawn. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `src` | `string` | `""` | `src` | The address of the picture. Empty, or a picture that has not loaded or cannot be loaded, draws the fallback: initials where the product gave some, otherwise a glyph. | | `label` | `string` | `""` | `label` | The name of the person or the thing the avatar stands for, in full ("Ada Lovelace", "Design team"). Not drawn: it is the avatar's accessible name while decorative is false. In the group form it is the group's name ("Reviewers"). | | `initials` | `string` | `""` | `initials` | The one or two characters drawn where there is no picture ("AL", "山"). The product makes them: which characters stand for a name depends on its writing system and its order, which the avatar cannot know. Never read by assistive technology. | | `decorative` | `boolean` | `false` | `decorative` | True hides the avatar from assistive technology, for an avatar that stands beside the same name in visible text (a byline, a list row, a comment's header), so the name is read once. False, for an avatar that stands alone, exposes it as an image named by label. Ignored for the members of a group. | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Small (24) stands beside one line of text: a byline, a table cell, a mention. Medium (40) is a list row's or a comment's avatar. Large (56) heads a person's own page or card. A group gives its size to every member. A design system may add values. | | `shape` | `enum`: `circle`, `square` | `"circle"` | `shape` | Circle is a person. Square, a rounded square, is something that is not one person: a team, a project, an organisation, a bot. A group gives its shape to every member. A design system may add values. | | `max` | `number` | `0` | — | Group form only. The most boxes the group draws, the overflow box included; 0 draws every member. A whole number of 2 or more: with more members than this, the group draws one fewer member than max and then the overflow box. | | `total` | `number` | — | — | Group form only. How many members there are, where the product gives the group fewer than exist (the first five of a team of two hundred). Null counts the members given. | | `overflowLabel` | `string` | `""` | — | Group form only. What assistive technology reads for the overflow box: the whole sentence in the product's language, with one place, {count}, which the group fills with the number of members not drawn ("{count} more", "ほか{count}人"). Written once as the product's words, it serves every group. A sentence that is right for every number, or a prop set per count where the language needs another form for one. Empty reads the product's words; with neither, the drawn text ("+12"). | ### Slots | Slot | Description | | --- | --- | | `icon` | The fallback glyph: a glyph of the system's icon set, by name, drawn through the platform's icon helper where there is neither a picture nor initials. Empty draws the system's own fallback glyph. | ### Item: `member` One avatar of a group: an avatar with its own picture, name, initials and glyph, drawn at the group's size and shape. It is a Avatar. Names: Web `tanrei-avatar`, SwiftUI `TanreiAvatar`, Jetpack Compose `TanreiAvatar`, Flutter `TanreiAvatar`, React Native `Avatar`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `src` | `string` | `""` | `src` | The address of the member's picture. | | `label` | `string` | `""` | `label` | The member's name. Always exposed in a group: the names are what the group says. | | `initials` | `string` | `""` | `initials` | The member's initials, drawn where there is no picture. | ### States `enabled` ### Accessibility - Role: `img` - Labeling: An avatar that stands alone is an image named by label, the full name of the person or the thing, whatever it draws; the initials, the glyph and the picture's address are never read. An avatar beside the same name in visible text is decorative and hidden. A group is a group named by its label, holding one named image for each member it draws and, last, the overflow's text (overflowLabel, or the drawn count). Inside a link or a Button, the avatar's label is part of that element's name. - Minimum target size: yes - Not interactive: the avatar takes no input and no focus (AVT-7), so there is no target to size and minimumTarget holds trivially. An avatar that is pressed is inside a link or a Button, and that element meets the minimum target by its own spec; a small (24) avatar alone in a link needs the link's target, not its own box, to be large enough. - Decorative or named is the product's decision and cannot be seen from the avatar: beside "Ada Lovelace" in text a named avatar would be read as "Ada Lovelace, image, Ada Lovelace". The rule the docs page gives: if deleting the avatar loses a name, it is named; otherwise it is decorative. - The name is the name, not a description of the picture: "Ada Lovelace", never "Photo of Ada Lovelace" and never the initials. - Contrast in the default system: the initials, the count and the glyph are on-surface-variant on surface-container-highest, a pair the token invariants hold to 4.5:1 for secondary content on every surface tone. The fill against the surface around it is not held to a ratio: the avatar is not a control, and what it says is its name. - A picture brings its own colors, which the avatar does not check. A picture with a pale edge on a pale surface loses its outline; the avatar draws no ring around a picture, so a product whose pictures are often pale chooses the square or gives the surface behind them a tone. - A badge on an avatar (AVT-12) says that something is waiting, in the badge's one color and with the badge's label in words. Presence (online, away, busy) is a status that a color alone would carry; say it in words beside the name, with a tag where it needs a mark. - Forced colors (AVT-13): every fallback gains an edge in the text color; pictures are left alone. - A group's overflow box is text, not a control. Where the people it counts matter (who else can see this), the product lists them: a link or a Button beside the group that opens the full list. ### Behaviour Requirements in EARS form, each with its stable id. - **AVT-1** THE avatar SHALL draw a square box whose side is the container size of its size (comp.avatar.container.size.small for small, comp.avatar.container.size.medium for medium, comp.avatar.container.size.large for large), with the corners of its shape (comp.avatar.container.shape.circle for circle, comp.avatar.container.shape.square for square), never larger than half the box's side (a circle where the value is sys.shape.corner.full) and eased by sys.shape.corner-smoothing, filled with comp.avatar.container.color, and SHALL clip everything it draws to that shape. THE avatar SHALL lay itself out inline with the text or the row it is placed in, as one unbreakable box that the layout neither stretches nor shrinks, and SHALL draw no edge and no elevation. - **AVT-2** THE avatar SHALL draw exactly one of three things at the centre of its box (and two only for the cross-fade in which its picture arrives, AVT-4), the first of these that it has: the picture src names, once that picture has loaded (AVT-3, AVT-4); else initials, where initials is not empty (AVT-5); else a glyph (AVT-6). THE avatar SHALL never draw an empty box, a broken-picture mark or the picture's address, and SHALL NOT make initials out of label. - **AVT-3** WHILE the picture of src has loaded THE avatar SHALL draw it over the whole box, scaled so that it covers the box with its proportions kept and its centre on the box's centre, clipped to the box's shape, over comp.avatar.container.color (which shows through the picture's transparent parts), and SHALL draw neither initials nor a glyph. THE avatar SHALL NOT mirror, tint or otherwise change the picture in any layout direction or scheme. - **AVT-4** WHILE src is not empty and its picture has not yet loaded THE avatar SHALL draw its fallback (AVT-2) in the box, at the avatar's full size, so that nothing changes place when the picture arrives; WHEN the picture has loaded THE avatar SHALL fade it in over the fallback while the fallback fades out beneath it, one cross-fade of opacity over comp.avatar.motion.picture-duration on comp.avatar.motion.picture-easing (sys.motion.role.state.default and sys.motion.easing.state), in which nothing changes place or size; reduced motion keeps it, as a change of opacity is not motion (MOT-6). WHERE the picture loads while the avatar draws its first frames (MOT-3), or the platform already holds it when the avatar asks for it (in its memory of the pictures it has loaded), THE avatar SHALL draw it at once, in the fallback's place. IF the picture cannot be loaded THE avatar SHALL keep the fallback, SHALL NOT ask for the picture again by itself, and in debug builds SHALL report the address that failed. WHEN src changes THE avatar SHALL draw the fallback at once, until the new picture has loaded and fades in. WHILE src is empty THE avatar SHALL ask for nothing. - **AVT-5** WHERE the avatar draws initials THE avatar SHALL set them on one line at the centre of the box, in the text style of its size (comp.avatar.label.typescale.small for small, comp.avatar.label.typescale.medium for medium, comp.avatar.label.typescale.large for large) and in comp.avatar.label.color, as the product wrote them: it SHALL NOT change their case, and SHALL draw no more than the first two characters as a reader counts them (grapheme clusters), reporting in debug builds a value that is longer. THE avatar SHALL lay the initials out as text of their own direction, isolated from the text around the avatar, and SHALL keep them from assistive technology. - **AVT-6** WHERE the avatar draws a glyph THE avatar SHALL draw the glyph of its icon slot, or, where the slot is empty, the system's fallback glyph for its shape (person for circle, category for square), in a box of the icon size of its size (comp.avatar.icon.size.small for small, comp.avatar.icon.size.medium for medium, comp.avatar.icon.size.large for large) at the centre of the avatar, in comp.avatar.icon.color, with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, and SHALL keep it from assistive technology. - **AVT-7** THE avatar SHALL NOT take pointer, touch or keyboard input, SHALL NOT take focus or be a stop in the focus order, and SHALL NOT change anything it draws under a pointer, a press or focus: it has no hovered, focused, pressed, selected or disabled state, draws no state layer, no ripple and no focus indicator, and emits no event. - **AVT-8** WHERE the avatar is placed inside an element that takes input (a link, a Button, a list item, a chip, a card that is pressed as a whole) THE avatar SHALL let input over it reach that element, SHALL stay as it is drawn while that element is hovered, focused or pressed (the state and the focus indicator are drawn by that element, on its own container), and SHALL NOT become a second target inside it; WHILE decorative is false THE avatar SHALL add its label to that element's content in reading order, so that a link or a Button that holds an avatar and nothing else is named by the avatar's label. An avatar that leads somewhere or opens something is that composition: the avatar has no destination and no action of its own. - **AVT-9** WHILE decorative is false and label is not empty THE avatar SHALL be exposed to assistive technology as one image named by label, whether it draws a picture, initials or a glyph, and SHALL expose nothing else: not the initials, not the glyph's name, not the picture's address, and not its size or shape. WHILE decorative is true THE avatar SHALL expose nothing. IF decorative is false, label is empty and the product gives it no name (AVT-24) THE avatar SHALL expose nothing and in debug builds report that an avatar has no name. - **AVT-10** WHEN label, initials, the icon slot's glyph, size or shape changes THE avatar SHALL draw and expose the new value at once, without a motion, and SHALL NOT announce the change by itself. - **AVT-11** WHILE the text size is enlarged THE avatar SHALL keep its box at the container size of its size and its glyph at the size of AVT-6, and SHALL let its initials, and a group's count (AVT-17), follow their text style as it grows, no larger than the glyph's box of the same size (comp.avatar.icon.size.small for small, comp.avatar.icon.size.medium for medium, comp.avatar.icon.size.large for large), so that they still stand whole inside the box: an avatar is a picture and is enlarged with the page, not with the text, as a glyph's box is, while the letters it holds grow as far as the box leaves room for them. - **AVT-12** WHERE the avatar is the anchor of a badge THE avatar SHALL be drawn exactly as it is without one: its square box is the anchor's bounds, the badge is placed by that box's top-end corner and drawn outside the avatar's clip (BDG-1, BDG-3, BDG-7), and the badge's label is added to the avatar's description after its name (BDG-8). THE avatar SHALL have no dot, count or status of its own. - **AVT-13** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE avatar SHALL draw an edge sys.border.hairline wide in the platform's text color inside its box, following its shape, and its initials or its glyph in that text color, so that a fallback whose fill the mode removes is still a bounded mark; THE avatar SHALL leave a picture's own colors as they are. - **AVT-14** THE avatar SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the avatar is shown THE avatar SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows. A single avatar is the same in both directions but for its glyph (AVT-15): its picture is never mirrored and its initials keep their own order (AVT-5). - **AVT-15** WHERE the layout direction is right-to-left THE avatar SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place nor its size, color and fill. THE avatar SHALL NOT mirror a glyph itself, and SHALL NOT mirror its picture or its initials. - **AVT-16** WHERE the avatar is given members THE avatar SHALL be a group: it SHALL draw its members in one row that does not wrap, in the order they are given from the start edge, each as an avatar of the group's size and shape with that member's own picture, initials or glyph (AVT-2 to AVT-6), and SHALL ignore its own src, initials, icon slot and decorative. Each box after the first SHALL lie over the end of the one before it by the overlap of the group's size (comp.avatar.group.overlap.small for small, comp.avatar.group.overlap.medium for medium, comp.avatar.group.overlap.large for large) and be drawn above it, and every box SHALL be surrounded, outside its own edge and following its shape, by a gap comp.avatar.group.outline.width wide in comp.avatar.group.outline.color that takes no room in the layout. THE group SHALL be as wide as its boxes less their overlaps, and as high as one box. - **AVT-17** WHILE the group has more members than max and max is 2 or more THE group SHALL draw the first max less one members and then, as its last box, an overflow box: a box of the group's size and shape filled with comp.avatar.container.color, placed and surrounded as a member is (AVT-16), holding on one line, in the label style of the group's size (AVT-5) and comp.avatar.label.color, a plus sign followed by the number of members not drawn. WHILE max is 0, or the group has no more members than max, THE group SHALL draw every member and no overflow box, unless total says more exist (AVT-18). THE overflow box SHALL take no input and SHALL NOT be a control: showing the members it counts is the product's, beside the group. - **AVT-18** WHILE total is greater than the number of members the group is given THE group SHALL count as not drawn every member up to total, and SHALL draw the overflow box with that number after the members it draws: where the members given fit within max less one, or max is 0, all of them are drawn before it. THE group SHALL write the number in the current locale's digits with no grouping separator, SHALL draw 99 followed by a plus sign in place of a number above 99, at every size, so that the box never holds more than three characters (the exact number stays in overflowLabel, AVT-19), and SHALL lay the sign and the number out as one left-to-right run isolated from the text around it, so that the plus sign stays before the digits in a right-to-left layout. - **AVT-19** THE group SHALL be exposed to assistive technology as one group named by its label, holding in order one image for each member it draws, each named by that member's label whatever decorative says, and then, where it draws an overflow box, one text: overflowLabel — from the instance's prop or, WHILE that is empty, from the product's words of the key avatarGroupOverflowLabel — with its place {count} filled by the number of members not drawn, in the current locale's digits with no grouping separator and never cut at 99 as the drawn text is (AVT-18); else the drawn text. Another text between braces, and a brace that opens or closes nothing, SHALL be read as written and reported in debug builds; a sentence without {count} SHALL be read as written and reported in debug builds, because it does not say how many. THE gaps SHALL be kept from assistive technology. IF the group's label is empty THE group SHALL expose its members without a group's name and in debug builds report that a group has no name; IF a member's label is empty THE group SHALL expose nothing for that member and in debug builds report it. - **AVT-20** WHERE the layout direction is right-to-left THE group SHALL lay its row out from the right: the first member is at the right, each following box lies over the left end of the one before it and above it, and the overflow box is the leftmost; the order assistive technology reads SHALL stay the order given. - **AVT-21** WHEN the group's members, max, total, size or shape change THE group SHALL draw and expose the new row at once, without a motion, and SHALL NOT announce the change by itself. - **AVT-22** WHEN size or shape names a value that the active design system does not have THE avatar SHALL render with the default value's tokens, and in debug builds report the unknown value. IF max is 1, negative or not a whole number THE group SHALL draw as for 0 and in debug builds report it; IF total is not null and is less than the number of members given, negative or not a whole number THE group SHALL count the members given and in debug builds report it. - **AVT-23** IF the avatar is a group and every member has been removed THE group SHALL draw nothing, take no space and expose nothing. IF max, total or overflowLabel is set on an avatar that has no members THE avatar SHALL ignore it and in debug builds report it. - **AVT-24** WHERE the platform has ARIA attributes (the web), an avatar's host and a group's host carries its role (AVT-9, AVT-19) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE avatar SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name and SHALL NOT be reported as having none in debug builds (AVT-9, AVT-19). WHILE an avatar's label is empty and decorative is false (or it is a member of a group) a name the product gives so SHALL make it one image named by that name, as AVT-9 says of its label: an image the product names is a named image. WHILE an avatar is decorative and not a member, or a group has no members (AVT-23), it exposes nothing, and THE avatar SHALL hold them as well, giving them back when it is exposed again. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE avatar SHALL take it away. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.avatar.…` → `--tanrei-comp-avatar-…`). #### `tanrei.comp.avatar` | Token | Type | Value | | --- | --- | --- | | `comp.avatar.container.size.small` | `dimension` | `24px` | | `comp.avatar.container.size.medium` | `dimension` | `40px` | | `comp.avatar.container.size.large` | `dimension` | `56px` | | `comp.avatar.container.shape.circle` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.avatar.container.shape.square` | `dimension` | `{tanrei.sys.shape.corner.small}` | | `comp.avatar.container.color` | `color` | `{tanrei.sys.color.surface-container-highest}` | | `comp.avatar.label.typescale.small` | `typography` | `{tanrei.sys.typescale.caption}` | | `comp.avatar.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.avatar.label.typescale.large` | `typography` | `{tanrei.sys.typescale.heading-3}` | | `comp.avatar.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.avatar.icon.size.small` | `dimension` | `{tanrei.sys.icon.extra-small}` | | `comp.avatar.icon.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.avatar.icon.size.large` | `dimension` | `{tanrei.sys.icon.large}` | | `comp.avatar.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.avatar.motion.picture-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` | | `comp.avatar.motion.picture-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.avatar.group.overlap.small` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.avatar.group.overlap.medium` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.avatar.group.overlap.large` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.avatar.group.outline.width` | `dimension` | `{tanrei.sys.border.thick}` | | `comp.avatar.group.outline.color` | `color` | `{tanrei.sys.color.surface}` | ## Badge > Marks an icon, a navigation item or an avatar with a dot or a small count to show that something is waiting. - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/badge/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/badge.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/badge`). - React: `Badge` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-badge` | lagging | | SwiftUI | `TanreiBadge` | lagging | | Jetpack Compose | `TanreiBadge` | lagging | | Flutter | `TanreiBadge` | lagging | | React Native | `Badge` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `label` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The pill that holds the count: at least as wide as it is high, so a single digit sits in a circle. - `dot` (optional): The container's form when there is no count: a small circle with no label. - `label` (optional): The count, or the capped count followed by a plus sign. - `outline`: A ring outside the dot or the pill that separates the badge from what it overlaps. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `count` | `number` | — | `count` | How many things are waiting. Null draws the dot (something is new, the number is unknown or unimportant); 0 draws nothing; above 0 draws the number. | | `max` | `number` | `999` | `max` | The largest count shown as it is; a larger one shows as max followed by a plus sign (999+). | | `label` | `string` | `""` | `label` | What assistive technology reads after the anchor's own name ("3 unread"). With no label, the displayed count is read; a dot needs one. | ### Slots | Slot | Description | | --- | --- | | `default` | The anchor the badge sits on, which it needs: an icon, an icon-only Button, a navigation item or an avatar. Its first element is the anchor; a badge with no element to sit on draws nothing (BDG-16). In fixtures the anchor is the glyph of the system's icon set that the fixture's content names, drawn at the icon size sys.icon.medium in the color on-surface-variant; its accessible name is that glyph name ("mail"), and the badge adds the fixture's label to it as its value ("mail, 3 unread"). | ### States `enabled` ### Accessibility - Role: `none` - Labeling: The badge has no role or name of its own. label (or, without one, the displayed count) becomes part of the anchor's accessible description, so the anchor is announced as, for example, "Inbox, button, 3 unread". The drawn number is hidden, so it is never read twice. - Minimum target size: yes - Not interactive: the badge takes no input (BDG-7), so the minimum target is the anchor's and the badge never shrinks or covers it for input. - A dot conveys its meaning by color and position only, so a dot without a label fails for screen reader users (BDG-9); give it one ("new messages"). - Where the count must be announced when it changes (a live chat), the product uses a live region; the badge does not announce by itself (BDG-10). - A badge marks an anchor and never stands alone in a line or a row (BDG-16). A count that stands by itself, such as the count at the end of a navigation drawer's row, a tree view's row or a menu item, is text, read in its place as the row's own words: that component's trailing text. A word that names a state is a tag. - How the description reaches the anchor is each platform's idiom: the web sets it on the slotted anchor (an ID reference cannot cross the shadow root), Apple platforms append it to the anchor's accessibility value, Compose merges it into the anchor's semantics as a state description, Flutter adds it to the anchor's semantics value, React Native to its accessibility value. ### Behaviour Requirements in EARS form, each with its stable id. - **BDG-1** WHILE count is null THE badge SHALL draw a circle of diameter comp.badge.dot.size in comp.badge.container.color with no label, its center comp.badge.dot.offset inside the anchor's top-end corner on both axes; the dot is a circle whatever corners the container has. - **BDG-2** WHILE count is above 0 THE badge SHALL draw a container at least comp.badge.container.height high and at least as wide as it is high, with comp.badge.container.padding-inline on each side of its label and corners of comp.badge.container.shape, filled with comp.badge.container.color, and the label centered in comp.badge.label.typescale and comp.badge.label.color. - **BDG-3** WHILE count is above 0 THE badge SHALL place the center of the container's leading circle (a square of the container's drawn height at its start) comp.badge.container.offset inside the anchor's top-end corner on both axes, so that a longer count grows toward the end, away from the anchor. - **BDG-4** WHEN count is greater than max THE badge SHALL show max followed by a plus sign (999+ with the default max) instead of count, and SHALL otherwise show count in full. - **BDG-5** WHILE count is 0 THE badge SHALL draw nothing and expose nothing to assistive technology, and its anchor SHALL render and be announced as it would without a badge. - **BDG-6** THE badge SHALL draw comp.badge.outline.width of comp.badge.outline.color around the dot or the container, outside its edge, without changing the badge's size or position. - **BDG-7** THE badge SHALL NOT change its anchor's size or position, SHALL NOT take space in the layout (it may extend past the anchor's bounds), and SHALL NOT take pointer, touch or keyboard input: input over the badge reaches the anchor. - **BDG-8** THE badge SHALL hide its drawn dot and number from assistive technology and SHALL add label to its anchor's accessible description, so that the anchor is announced with its own name followed by label; WHILE label is empty and count is above 0 THE badge SHALL add the displayed text instead (for example 999+). - **BDG-9** WHILE count is null and label is empty THE badge SHALL still render, and in debug builds report that the dot tells assistive technology nothing. - **BDG-10** WHEN count or label changes THE badge SHALL update its anchor's accessible description and SHALL NOT announce the change by itself. - **BDG-11** WHERE the layout direction is right-to-left THE badge SHALL take the anchor's top-left corner as its top-end corner and grow toward the left, and SHALL isolate its label from the surrounding direction so that a capped count keeps its plus sign after the digits. - **BDG-12** THE badge SHALL format count and max with the current locale's digits and no grouping separator, and SHALL draw digits with tabular figures where the font has them, so that a changing count does not shift its neighbours. - **BDG-13** WHILE the text size is enlarged THE badge SHALL grow its container with its label, keep the center of the leading circle — a square of the grown container's height — at its placement, and keep the dot at comp.badge.dot.size. - **BDG-14** IF count is negative or not a number THE badge SHALL render as for 0; IF count is not a whole number THE badge SHALL use it rounded down; IF max is below 1 THE badge SHALL use its default of 999; in each case debug builds SHALL report the value. - **BDG-15** THE badge SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the badge is shown THE badge SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows and its state. - **BDG-16** IF the badge has no anchor THE badge SHALL draw nothing, take no space and expose nothing to assistive technology, whatever its count and label, and in debug builds report that a badge needs an anchor; WHEN an anchor is given to it THE badge SHALL draw itself on that anchor (BDG-1, BDG-3) and describe it (BDG-8) at once, and WHEN its anchor is taken away it SHALL give the anchor back its own description and draw nothing again. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.badge.…` → `--tanrei-comp-badge-…`). #### `tanrei.comp.badge` | Token | Type | Value | | --- | --- | --- | | `comp.badge.dot.size` | `dimension` | `6px` | | `comp.badge.dot.offset` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.badge.container.height` | `dimension` | `16px` | | `comp.badge.container.padding-inline` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.badge.container.offset` | `dimension` | `{tanrei.sys.space.space0}` | | `comp.badge.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.badge.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.badge.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.badge.label.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` | | `comp.badge.outline.color` | `color` | `{tanrei.sys.color.surface}` | | `comp.badge.outline.width` | `dimension` | `{tanrei.sys.border.thick}` | ## Bottom sheet > Shows supplementary content or a short task in a surface that rises from the bottom edge, either over the lower part of the content while the rest stays usable, or as a modal step that dims and blocks everything else until it is dismissed. - Category: Containment - Level: composed - Listing: default - Built from: Modal layer - Page: https://tanrei.chnotchy.com/components/bottom-sheet/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/bottom-sheet.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/bottom-sheet`). - React: `BottomSheet` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-bottom-sheet` | lagging | | SwiftUI | `tanreiBottomSheet` | lagging | | Jetpack Compose | `TanreiBottomSheet` | lagging | | Flutter | `TanreiBottomSheet` | lagging | | React Native | `BottomSheet` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `open` (prop) | `open` | `isPresented` | `visible` | `open` | `open` | | `dismissible` (prop) | `closedby` | `dismissible` | `dismissible` | `dismissible` | `dismissible` | | `handle` (prop) | `noHandle` | `handle` | `handle` | `showHandle` | `handle` | | `handleLabel` (prop) | `handleLabel` | `handleLabel` | `handleLabel` | `handleSemanticLabel` | `handleLabel` | | `inset` (prop) | `flush` | `inset` | `inset` | `inset` | `inset` | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | | `closable` (prop) | `closable` | `closable` | `closable` | `showCloseButton` | `closable` | | `closeLabel` (prop) | `closeLabel` | `closeLabel` | `closeLabel` | `closeButtonSemanticLabel` | `closeLabel` | | `close` (event) | `close` | `onClose` | `onClose` | `onClose` | `onClose` | | `detentChange` (event) | `detentchange` | `detent` | `onDetentChange` | `onDetentChanged` | `onDetentChange` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `scrim` (optional): The modal layer's scrim over everything behind a modal sheet (MDL-1). It blocks presses and, while the sheet is dismissible, a press on it asks the sheet to close. A standard sheet draws none. - `container`: The raised surface docked to the bottom edge of the area it covers, centred and no wider than its maximum width, its top corners rounded and its bottom corners square. Its color reaches under the bottom system inset. - `drag-handle` (optional): The control at the top of the sheet: a Handle without a value, always drawn, that carries hover, focus and press on its box, with the grip centred in it. Activating it moves the sheet between its two heights. - `drag-handle.grip` (optional): The Handle's line: the short rounded bar drawn in the handle's box that says the sheet can be dragged. - `header` (optional): The row below the drag handle's row (or at the top without one) that holds the headline and the close button. Drawn while headline is not empty or closable is true; it stays in place while the content scrolls. - `headline` (optional): What the sheet is about ("Share photo"), a heading. It names the sheet where label is empty. - `close-button` (optional): An icon-only Button of the size comp.bottom-sheet.close-button.size names (small in the default system) showing the close glyph at the end of the header, in the variant comp.bottom-sheet.close-button.variant names (tonal in the default system), as every host's close button is. The sheet places it and chooses its variant; everything else it reads from Button's own tokens. - `divider` (optional): A hairline across the sheet below the header: drawn whenever the header is in the default system, or only while the content is scrolled away from its top under dividerVisibility scroll. - `content`: Whatever the product puts in the sheet: a list of choices, a form, details. The sheet insets it (unless inset is false), clips it, hands it a content color and scrolls it; it does not lay it out. - `focus-ring` (optional): Gap-then-ring indicator around the drag handle's box, shown for keyboard focus. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `standard`, `modal` | `"modal"` | `variant` | Standard sits over the lower part of the content while the content above stays usable (a layout region); modal dims and blocks everything else and holds focus until it closes (a modal overlay). Both read the same container tokens: the scrim and the behaviour set them apart. Not a token axis. | | `open` | `boolean` | `false` | `open` | Whether the sheet is shown. The product opens it, and closes it in answer to close (or from its own controls); on SwiftUI, where it is a binding, the sheet writes false itself. | | `detent` | `enum`: `partial`, `full` | `"partial"` | `detent` | The height the sheet rests at while its content is taller than it: partial takes comp.bottom-sheet.container.partial-fraction of the area; full reaches up to comp.bottom-sheet.container.margin-block-start below the area's top. A sheet whose content is shorter than its partial height has one height, and detent changes nothing. The person moves between the two by dragging or with the drag handle (detentChange). | | `dismissible` | `boolean` | `true` | — | Whether a drag below the sheet's lowest height asks it to close and, for a modal sheet, whether Escape, the platform's back and a press on the scrim do too. Set it to false only when the person must finish the sheet's task with one of its own controls. | | `handle` | `boolean` | `true` | `no-handle` (turns it off) | Draws the drag handle at the top of the sheet. Without it the sheet can still be dragged by its padding and content (BSH-9), but a keyboard or switch user has no way to change its height, so leave it on for a sheet whose content can be taller than its partial height. | | `handleLabel` | `string` | `""` | `handle-label` | The drag handle's accessible name ("Resize sheet"); its expanded state is exposed with it. Required while the handle is interactive (BSH-11). | | `inset` | `boolean` | `true` | `flush` (turns it off) | Insets the content by comp.bottom-sheet.container.padding. Set it to false for content that pads itself or reaches the edges (a list whose rows carry their own padding). | | `label` | `string` | `""` | `label` | Names the sheet for assistive technology ("Share photo"): the modal dialog, or the standard sheet's region. Required unless headline names it. | | `headline` | `string` | `""` | `headline` | What the sheet is about ("Share photo"), drawn in its header (BSH-28). While label is empty it is the sheet's accessible name. | | `closable` | `boolean` | `false` | `closable` | Draws the close button at the end of the header (BSH-29). False by default: the drag handle and, for a modal sheet, the scrim are the sheet's ways out. Set it where a person who cannot drag needs one they can see — a standard sheet, or a sheet without a handle. | | `closeLabel` | `string` | `""` | `close-label` | The close button's accessible name ("Close sharing"). Required while closable is true. | | `dividerVisibility` | `enum`: `auto`, `always`, `scroll` | `"auto"` | `divider-visibility` | When the divider below the header is drawn. always: whenever the header is drawn, at rest as well as while the content is scrolled. scroll: only while the content is scrolled away from its top. auto takes comp.bottom-sheet.divider.visibility, the design system's answer (always in the default system). | ### Events | Event | Description | | --- | --- | | `close` | The sheet asks to be closed: its close button (BSH-29), a released drag below its lowest height, or for a modal sheet a press on the scrim, Escape or the platform's back. Carries which of these it was, named close, drag, scrim, escape or back (in the platform's casing). The close button asks whatever dismissible says; the others only while dismissible is true. | | `detentChange` | The person moved the sheet to its other height, by a drag or with the drag handle. Carries the new detent (partial or full). Not emitted when the product sets detent. | ### Slots | Slot | Description | | --- | --- | | `default` | The content. A fixture's content string is plain text, which takes sys.typescale.body in the content color (BSH-8). | ### States `enabled`, `hovered`, `focused`, `pressed` ### Accessibility - Role: `dialog` - Labeling: The sheet is named by label, or by its headline where label is empty: a modal dialog while variant is modal, a region while it is standard. The headline is a heading; the close button is named by closeLabel; the divider is decorative. The drag handle, while the sheet has two heights, is a button named by handleLabel with the expanded state (true at full height); at one height it is hidden. The grip is decorative. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves focus through the drag handle (while it is interactive), the close button (while closable is true) and the content's focusable elements, in that order. In an open modal sheet it wraps and never leaves the sheet; from a standard sheet it moves on to the content, and the sheet stays open. | | Enter or Space | On the drag handle, moves the sheet to its other height (partial or full). On the close button, asks the sheet to close (close, reason close). | | Escape | Asks an open modal sheet to close (close, reason escape) while dismissible is true; with stacked overlays, only the topmost. A standard sheet ignores it. | - Dragging is never the only way (WCAG 2.5.7): the drag handle changes the height with a single press or from the keyboard, and a modal sheet closes with Escape, back or a press on the scrim. A standard sheet, and a modal one whose dismissible is false, closes only by a drag, its close button or the product: set closable, or put a Close or Done button in its content. - The standard form is a layout region, although it covers the bottom of the content rather than pushing it aside: the person works in the content and in the sheet at once, so focus leaving it never closes it. The modal form is a modal overlay. - Web: the modal form is a native \ opened with showModal() inside the shadow root, so the rest of the page is inert and the sheet is in the top layer; ::backdrop draws the scrim. Its cancel event (Escape) is cancelled and becomes close with the reason escape; the product then sets open to false. The standard form is a region (a \
named by label) positioned at the bottom of its containing block. The `autofocus` attribute on a slotted element marks initial focus. - Where a platform presents the modal sheet in a window of its own (Compose's Dialog, React Native's Modal), the window's own dim and transition are switched off and Tanrei draws the scrim and the motion, so every platform draws the same color. - The sheet does not move or pad the content a standard sheet covers; a product whose content must stay visible above the sheet pads its scrolling content by the sheet's partial height. - How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves. ### Behaviour Requirements in EARS form, each with its stable id. - **BSH-1** WHEN open becomes true THE bottom sheet SHALL slide its container up to its height (BSH-6) from its own height below the bottom edge of the area it covers, whole and unscaled whatever sys.behavior.appearance says (a sheet slides from its edge) — WHILE variant is modal over the whole window on its modal layer, fading the layer's scrim in comp.bottom-sheet.scrim.color and comp.bottom-sheet.scrim.blur in behind it in step, over the same duration and curve (MDL-1, MDL-7); WHILE variant is standard over the bottom of the parent the product placed it in, with no scrim — over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing; WHEN open becomes false THE bottom sheet SHALL slide it down the same way out of view from wherever it is drawn, over comp.bottom-sheet.motion.exit-duration with comp.bottom-sheet.motion.exit-easing, WHILE variant is modal taking the scrim away at once (MOT-8) and keeping the container drawn until the slide ends; WHILE it leaves, in either variant, neither the container nor the scrim SHALL take pointer input, so that a press reaches what lies under them (MOT-7). A slide turned round SHALL go on from where it has got to. WHERE motion is reduced it SHALL only fade the container in and out in place without sliding, and the scrim in with it, over sys.motion.role.reduced, or appear and disappear at once on a platform whose reduced-motion setting removes every animation (Android's). WHEN a modal sheet is mounted with open true it SHALL appear without its motion while the document has not yet been first painted, and with it when it is mounted after that; a standard sheet mounted with open true SHALL appear in place without motion, being a layout region (BSH-4). - **BSH-2** WHILE variant is modal and the sheet is open THE bottom sheet SHALL make everything outside it inert, keep the content behind it from scrolling and keep focus inside it, as its modal layer does (MDL-2, MDL-4): a modal overlay. - **BSH-3** WHEN open changes from false to true THE bottom sheet SHALL move focus to the element in it that the product marked for initial focus (the platform's own mark, named in the platform notes) or, without one, to its container, so that assistive technology reads its label first; WHEN it closes while focus is inside it THE bottom sheet SHALL return focus to the element that had it when the sheet opened — or, WHERE a standard sheet opened under a modal surface it is not inside, to the element that had focus before that surface opened — or, where that element no longer exists or cannot take focus, to the platform's default for a closed overlay. Focus SHALL move when the sheet opens or closes, not when its motion ends. This holds for both variants (a modal sheet moves and returns focus as its modal layer does, MDL-3, MDL-5); a standard sheet mounted with open true SHALL NOT move focus, and a modal sheet mounted with open true SHALL move focus in as if it had just opened, because it makes everything behind it unfocusable and focus must be somewhere it can reach. - **BSH-4** WHILE variant is standard THE bottom sheet SHALL draw no scrim, SHALL NOT make anything inert, SHALL NOT keep focus inside it, SHALL let Tab and Shift+Tab move focus between it and the content it covers without closing it, and SHALL ignore Escape and the platform's back: a standard sheet is a layout region, not an overlay. The product places it over the content it covers, in a parent that holds both; the sheet SHALL dock to that parent's bottom edge, SHALL NOT resize or pad the content, and SHALL let presses on the part of the parent above it reach the content. - **BSH-5** WHILE dismissible is true, WHEN the user presses the scrim, presses Escape or uses the platform's back WHILE variant is modal, as its modal layer answers them (MDL-6), or releases a drag that asks to close (BSH-9) in either variant, THE bottom sheet SHALL emit close exactly once with the reason scrim, escape, back or drag, and SHALL then be closed: through its binding where open is one (SwiftUI), and by the product setting open to false where open is a plain value (web, Compose, Flutter, React Native). WHILE dismissible is false THE bottom sheet SHALL ignore these inputs and emit nothing for them (its close button, BSH-29, still asks); a press on the scrim SHALL still reach nothing behind it. - **BSH-6** THE bottom sheet SHALL be as tall as its drag handle's row, its header (BSH-28) and its content (with its insets), but no taller than its detent allows: WHILE detent is partial, comp.bottom-sheet.container.partial-fraction of the height of the area it covers; WHILE detent is full, that height less comp.bottom-sheet.container.margin-block-start. The area is the window below its top system inset for a modal sheet, and the parent the product placed it in for a standard sheet; WHILE the on-screen keyboard is shown the area SHALL end at the keyboard's top edge, so that the sheet sits on the keyboard and both heights are taken from the smaller area. The sheet has two heights only WHILE its content is taller than its partial height; otherwise it has one, and detent changes nothing. - **BSH-7** THE bottom sheet SHALL draw its container at the bottom edge of the area, as wide as the area but no wider than comp.bottom-sheet.container.max-width and centred in it, filled with comp.bottom-sheet.container.color, raised by comp.bottom-sheet.container.elevation, with its top corners rounded by comp.bottom-sheet.container.shape and its bottom corners square; it SHALL extend its color under the bottom system inset and keep its content above that inset, and WHILE the on-screen keyboard is shown it SHALL sit on the keyboard (BSH-6) with its content above it. - **BSH-8** THE bottom sheet SHALL lay out, top to bottom, the drag handle's row WHILE handle is true (BSH-12), the header WHILE there is one (BSH-28) and then its content. WHILE inset is true it SHALL inset the content by comp.bottom-sheet.container.padding from its start, end and bottom edges, and from its top edge WHILE handle is false and no header is drawn; WHILE inset is false the content SHALL reach the container's edges, below the handle's row and the header. It SHALL clip the content to the container's shape, SHALL hand it comp.bottom-sheet.content.color as the platform's inherited foreground (the web's inherited color, SwiftUI's foreground style, Compose's content color, Flutter's default text and icon style, React Native's Tanrei text context), and plain text given as content, where the platform must style it, SHALL take sys.typescale.body. - **BSH-9** WHEN the user drags the sheet vertically — by its handle's row, by the padding around its content, or by its content where BSH-10 lets the drag reach the sheet — beyond the platform's touch slop THE bottom sheet SHALL follow the finger or pointer, never above its full height; WHEN the drag is released it SHALL settle at the next height in the direction of a fling, or else at the height nearest to where it was released, over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing (at once where motion is reduced). A release below half of the sheet's lowest height, or a downward fling from its lowest height, SHALL ask to close WHILE dismissible is true (BSH-5, BSH-20); WHILE dismissible is false the sheet SHALL settle at its lowest height instead. A fling is a release faster than the platform's minimum fling velocity (Android's ViewConfiguration.getScaledMinimumFlingVelocity, Flutter's kMinFlingVelocity) or, where the platform names none (the web, SwiftUI, React Native), 0.5 points per millisecond; the touch slop is the platform's own (Android's ViewConfiguration.getScaledTouchSlop, Flutter's kTouchSlop) or, where the platform names none, 8 points. A release's velocity is the pointer's over its last moves: WHERE the pointer has not moved for longer than the time after which the platform's velocity tracker takes a pointer as stopped (40 milliseconds in Android's VelocityTracker, Jetpack Compose's VelocityTracker and Flutter's VelocityTracker) or, where the platform names none (the web, SwiftUI, React Native), 40 milliseconds before the release THE bottom sheet SHALL take the release as having no velocity, so that a drag that stops where it is wanted and is let go there is no fling, however fast it moved before it stopped. WHEN a drag ends at the height it did not start from THE bottom sheet SHALL set detent to it and emit detentChange exactly once with it. - **BSH-10** WHILE the content is taller than the room the sheet gives it THE bottom sheet SHALL scroll the content inside the container, below the handle's row, and SHALL let assistive technology and keyboard focus scroll it at either height; a drag upward on the content SHALL first raise the sheet to its full height and then scroll the content, and a drag downward on the content SHALL first scroll the content to its top and then lower the sheet. - **BSH-11** WHILE handle is true and the sheet has two heights THE bottom sheet SHALL make the drag handle one focus stop, a button named by handleLabel with the expanded state, true WHILE detent is full (its label and expanded, HDL-8), and WHEN the user activates it by pointer, touch, Enter or Space (its activate, HDL-7) THE bottom sheet SHALL move to its other height as BSH-9 settles and emit detentChange exactly once with the new detent; WHILE the sheet has one height the handle SHALL still be drawn at rest but SHALL NOT be focusable, pressable or exposed to assistive technology. WHILE the handle is interactive and handleLabel is empty it SHALL still render, and in debug builds report that the handle has no accessible name. - **BSH-12** WHILE handle is true THE bottom sheet SHALL draw at its top a row holding the drag handle — a Handle of axis vertical and size medium, with no value and revealed — centred across the sheet with comp.bottom-sheet.handle.margin-block above and below it, and SHALL give that Handle its own tokens in place of the Handle's: the box comp.bottom-sheet.handle.container-width wide and comp.bottom-sheet.handle.container-height high with comp.bottom-sheet.handle.container-shape corners (HDL-3), the grip — the Handle's line — comp.bottom-sheet.handle.grip-width long and comp.bottom-sheet.handle.grip-height thick (HDL-1), and the container, line and state-layer colors of each state from the drag-handle control (comp.bottom-sheet.drag-handle.container.color, comp.bottom-sheet.drag-handle.grip.color, comp.bottom-sheet.drag-handle.state-layer.color, and so on for each state), its opacity in each state, and comp.bottom-sheet.motion.state-duration, comp.bottom-sheet.motion.state-easing and comp.bottom-sheet.motion.feedback-duration as its motion; in the default system each of them aliases the Handle's own. The row SHALL stay in place while the content scrolls. - **BSH-13** WHILE the drag handle is hovered, keyboard-focused or pressed THE bottom sheet SHALL render the handle's box, grip and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered, and the grip at the Handle's length and thickness of a handle in use (HDL-4); focus gained by pointer or touch SHALL NOT select the focused state. A drag that starts on the handle SHALL keep it pressed while the sheet follows the drag, as a Handle is held for as long as a drag lasts (HDL-11). - **BSH-14** WHEN the drag handle receives keyboard focus THE bottom sheet SHALL show the focus ring around the handle's box without animation; focus gained by pointer or touch SHALL NOT show it. - **BSH-15** THE bottom sheet SHALL give the drag handle the Handle's hit area (HDL-5): at least sys.target.touch wide and high for touch input and sys.target.pointer for fine pointers, centred on its box, without changing its drawn size, and the Handle's vertical resize cursor; a platform that cannot tell the input type SHALL use sys.target.touch. Below its box the hit area SHALL reach no further than half of comp.bottom-sheet.handle.margin-block, the space between the box and what follows the row (HDL-5's cap), so that a press nearer the header or the content under the handle's row goes to them (BTN-5). A press on the rest of the handle's row drags the sheet as BSH-9 says. - **BSH-16** WHEN the drag handle is pressed by pointer, touch, Enter or Space THE drag handle SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner (HDL-11). - **BSH-17** WHILE pressed THE drag handle SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; grip and opacity still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.bottom-sheet.motion.feedback-duration with comp.bottom-sheet.motion.state-easing, fades over comp.bottom-sheet.motion.state-duration with comp.bottom-sheet.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **BSH-18** THE bottom sheet SHALL ease its container's top corners and the drag handle's box corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show the handle's keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. - **BSH-19** WHEN the drag handle's colors, or its grip's length and thickness, change between states THE bottom sheet SHALL animate them over comp.bottom-sheet.motion.state-duration with comp.bottom-sheet.motion.state-easing, and SHALL change them at once where motion is reduced. - **BSH-20** WHEN a released drag asks to close THE bottom sheet SHALL emit close (BSH-5), hold where the drag left it for one frame, and then slide out from there as BSH-1 says IF open has become false, or settle back at its lowest height as BSH-9 says IF open is still true (the product declined to close it). - **BSH-21** WHEN the product changes detent while the sheet is open THE bottom sheet SHALL move to the new height over comp.bottom-sheet.motion.enter-duration with comp.bottom-sheet.motion.enter-easing (at once where motion is reduced) and SHALL NOT emit detentChange; where detent is a plain value (web, Compose, Flutter, React Native), a height the person chose (BSH-9, BSH-11) SHALL stay until the product sets detent again, and where it is a binding (SwiftUI) the sheet SHALL write the new detent to it. - **BSH-22** THE bottom sheet SHALL expose its container, WHILE variant is modal, as a modal dialog named by label and, WHILE variant is standard, as a region named by label (a landmark on the web) — by the headline WHILE label is empty (BSH-28); WHILE label and headline are both empty it SHALL still render, and in debug builds report that it has no accessible name. The drag handle's grip, the Handle's line, SHALL be hidden from assistive technology; the handle itself is exposed only as BSH-11 says. - **BSH-23** WHEN a dialog, a menu or another modal sheet opens from a modal bottom sheet THE bottom sheet SHALL stay below it, become inert with the rest of the window, and on the other overlay's closing receive back the focus that overlay returns, as its modal layer does (MDL-8, MDL-9); Escape SHALL dismiss only the topmost overlay. WHEN two modal bottom sheets open in the same update, one after the other, THE bottom sheet SHALL stack them in the order they open, as if the later had opened from the earlier: focus SHALL go into the later one only, the later SHALL return focus on closing to the element the earlier moves focus to as it opens (BSH-3), and the earlier, closed after it, SHALL return focus to the element that had it before either opened. - **BSH-24** WHILE the text size is enlarged THE bottom sheet SHALL grow with its content up to the height its detent allows and scroll the content beyond it (BSH-10), grow its header with a headline that wraps, and SHALL NOT scale the drag handle, nor the close button beyond what the Button itself does. - **BSH-25** WHEN variant or detent names a value the bottom sheet does not define THE bottom sheet SHALL render with the default value, and in debug builds report the unknown value. - **BSH-26** WHEN the layout direction is right-to-left THE bottom sheet SHALL keep its container and its drag handle centred, and its content SHALL follow the layout direction. - **BSH-27** THE bottom sheet SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the bottom sheet is shown THE bottom sheet SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state, its height and its focus. - **BSH-28** WHILE headline is not empty or closable is true THE bottom sheet SHALL draw a header below the drag handle's row (or at the top of the container without one): a row at least comp.bottom-sheet.header.height high holding the headline from comp.bottom-sheet.container.padding after the start edge, in comp.bottom-sheet.headline.typescale and comp.bottom-sheet.headline.color, wrapping onto more lines rather than truncating and growing the row with it, exposed as a heading, and, WHILE closable is true, the close button ending comp.bottom-sheet.header.padding-inline-end before the end edge and comp.bottom-sheet.header.gap after the headline, both centred in the row; below it, a divider comp.bottom-sheet.divider.width thick in comp.bottom-sheet.divider.color across the sheet's full width WHILE dividerVisibility (or, for auto, comp.bottom-sheet.divider.visibility) is always, or is scroll and the content is scrolled away from its top, shown and hidden at once. The header SHALL NOT scroll with the content, and a drag on it SHALL move the sheet as a drag on the handle's row does (BSH-9). WHILE headline is not empty it SHALL name the sheet where label is empty. A dividerVisibility the sheet does not define SHALL be drawn as auto, and reported in debug builds. - **BSH-29** WHILE closable is true THE bottom sheet SHALL draw its close button as an icon-only Button of the size comp.bottom-sheet.close-button.size names showing the glyph close of the system's icon set and named by closeLabel, in the variant comp.bottom-sheet.close-button.variant names, given through the channel a Button reads from the component that places it, and otherwise unrestyled: it reads Button's own tokens, answers hover, focus and press as any Button does and keeps its own minimum target (BTN-5); WHEN the user activates it THE bottom sheet SHALL emit close exactly once with the reason close, in either variant and whatever dismissible says, and SHALL then be closed as BSH-5 says. WHILE closable is true and closeLabel is empty it SHALL still draw the button, and in debug builds report that the button has no accessible name. THE bottom sheet SHALL draw no close mark of its own. - **BSH-30** WHILE handle is false, dismissible is true and closable is false THE bottom sheet SHALL still render, and in debug builds report that it shows no way out a person can see: a drag, Escape and the scrim still close it, but nothing on screen says so to a person who cannot drag. - **BSH-31** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE bottom sheet SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its container (BSH-22) — its dialog WHILE variant is modal, its region otherwise — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label or headline is not empty it is the container's name (BSH-22), over a name given so; WHILE both are empty, a name given so is the container's name and SHALL NOT be reported as having none in debug builds. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE bottom sheet SHALL take it off that element. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.bottom-sheet.…` → `--tanrei-comp-bottom-sheet-…`). #### `tanrei.comp.bottom-sheet` | Token | Type | Value | | --- | --- | --- | | `comp.bottom-sheet.scrim.color` | `color` | `{tanrei.comp.modal-layer.scrim.color}` | | `comp.bottom-sheet.scrim.blur` | `dimension` | `{tanrei.comp.modal-layer.scrim.blur}` | | `comp.bottom-sheet.container.color` | `color` | `{tanrei.sys.color.surface-container-low}` | | `comp.bottom-sheet.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` | | `comp.bottom-sheet.container.shape` | `dimension` | `{tanrei.sys.shape.corner.large}` | | `comp.bottom-sheet.container.max-width` | `dimension` | `640px` | | `comp.bottom-sheet.container.margin-block-start` | `dimension` | `{tanrei.sys.space.space600}` | | `comp.bottom-sheet.container.partial-fraction` | `number` | `0.5` | | `comp.bottom-sheet.container.padding` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.bottom-sheet.content.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.bottom-sheet.header.height` | `dimension` | `64px` | | `comp.bottom-sheet.header.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.bottom-sheet.header.padding-inline-end` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.bottom-sheet.headline.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.bottom-sheet.headline.typescale` | `typography` | `{tanrei.sys.typescale.heading-5}` | | `comp.bottom-sheet.divider.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.bottom-sheet.divider.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.bottom-sheet.divider.visibility` | `number` | `{tanrei.sys.behavior.divider-visibility}` | | `comp.bottom-sheet.close-button.variant` | `number` | `1` | | `comp.bottom-sheet.close-button.size` | `number` | `0` | | `comp.bottom-sheet.handle.container-width` | `dimension` | `{tanrei.comp.handle.container.length.medium}` | | `comp.bottom-sheet.handle.container-height` | `dimension` | `{tanrei.comp.handle.container.breadth.medium}` | | `comp.bottom-sheet.handle.container-shape` | `dimension` | `{tanrei.comp.handle.container.shape}` | | `comp.bottom-sheet.handle.margin-block` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.bottom-sheet.handle.grip-width` | `dimension` | `{tanrei.comp.handle.line.length.medium}` | | `comp.bottom-sheet.handle.grip-height` | `dimension` | `{tanrei.comp.handle.line.thickness.medium}` | | `comp.bottom-sheet.drag-handle.container.color` | `color` | `{tanrei.comp.handle.standard.container.color}` | | `comp.bottom-sheet.drag-handle.grip.color` | `color` | `{tanrei.comp.handle.standard.line.color}` | | `comp.bottom-sheet.drag-handle.state-layer.color` | `color` | `{tanrei.comp.bottom-sheet.drag-handle.grip.color}` | | `comp.bottom-sheet.motion.state-duration` | `duration` | `{tanrei.comp.handle.motion.state-duration}` | | `comp.bottom-sheet.motion.state-easing` | `cubicBezier` | `{tanrei.comp.handle.motion.state-easing}` | | `comp.bottom-sheet.motion.feedback-duration` | `duration` | `{tanrei.comp.handle.motion.feedback-duration}` | | `comp.bottom-sheet.motion.enter-duration` | `duration` | `{tanrei.sys.motion.role.appear.sheet.enter}` | | `comp.bottom-sheet.motion.enter-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.enter}` | | `comp.bottom-sheet.motion.exit-duration` | `duration` | `{tanrei.sys.motion.role.appear.sheet.exit}` | | `comp.bottom-sheet.motion.exit-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.exit}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.bottom-sheet...` for the variants `drag-handle`, the states `hovered`, `focused`, `pressed` and the properties `container.color`, `grip.color`, `state-layer.color`. - `comp.bottom-sheet..` for the states `hovered`, `focused`, `pressed` and the properties `opacity`. ## Breadcrumbs > Shows where a page sits in a hierarchy of pages and leads back up it: the levels above as links, in order from the top, with the page itself last. - Category: Navigation - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/breadcrumbs/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/breadcrumbs.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/breadcrumbs`). - React: `Breadcrumbs` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-breadcrumbs` | lagging | | SwiftUI | `TanreiBreadcrumbs` | planned | | Jetpack Compose | `TanreiBreadcrumbs` | planned | | Flutter | `TanreiBreadcrumbs` | planned | | React Native | `Breadcrumbs` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | | `overflowLabel` (prop) | `overflowLabel` | `overflowLabel` | `overflowContentDescription` | `overflowSemanticLabel` | `overflowAccessibilityLabel` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `root`: The navigation landmark and, in it, one ordered list of the levels, from the top of the hierarchy to the page. On one line by default. - `container`: The shape behind a level that is a link, and behind the overflow button. It has no fill at rest and takes no room in the layout: it is where hover, focus and press are drawn. - `label`: A level's text, in the trail's text style. - `underline`: The line under the label of a level that is a link, in the label's color. When it is drawn is a choice (BRC-30): at rest in the default system, where it is what says that a level leads somewhere. The current page and a level without a destination have none. - `icon` (optional): A glyph of the system's icon set that the product names for a level (a house for the top), before the label or in its place. Decorative. - `separator`: The glyph chevron_right between two neighbouring levels, drawn by the trail. Decorative; mirrored in a right-to-left layout by the icon helper. - `overflow-button` (optional): An icon-only button showing more_horiz that stands where levels were taken out of a trail too long for its width, and opens a menu of them. - `menu` (optional): The menu of the levels that were taken out, in the trail's order: a Tanrei menu, opened from the overflow button. - `focus-ring`: The indicator shown for keyboard focus, around a link's or the overflow button's container. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `label` | `string` | `""` | `label` | The accessible name of the landmark ("Breadcrumbs"), in the product's language. Tanrei ships no words of its own. It tells this landmark from the page's other navigation, so it is required. | | `overflow` | `enum`: `collapse`, `wrap` | `"collapse"` | `overflow` | What a trail longer than its width does. collapse: it stays on one line and its middle levels go behind the overflow button, as many as the width asks for (BRC-9). wrap: every level stays in the trail, which runs over as many lines as it needs (BRC-15). | | `overflowLabel` | `string` | `""` | `overflow-label` | The accessible name of the overflow button ("Show hidden levels"), in the product's language. Required while overflow is collapse; ignored while it is wrap. | | `underline` | `enum`: `auto`, `always`, `hover`, `never` | `"auto"` | `underline` | When the levels that are links are underlined. always: at rest and in every state. hover: while a level is hovered, focused from the keyboard or pressed, and not at rest. never: in no state. Auto takes comp.breadcrumbs.underline.visibility, the design system's answer (always in the default system). It applies to every level of the trail. | ### Item: `item` One level of the hierarchy: a link to it, the page the person is on, or the name of a level that has no page. Names: Web `a`, SwiftUI `TanreiBreadcrumbsItem`, Jetpack Compose `TanreiBreadcrumbsItem`, Flutter `TanreiBreadcrumbsItem`, React Native `BreadcrumbsItem`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `label` | `string` | `""` | The level's name: the title of its page, as short as the product has it. It is the item's accessible name, drawn or not. | | `href` | `string` | `""` | The destination: an address as the platform's links take one. With one the level is a link; without one it is text — the current page, or a level that has no page of its own (BRC-3). | | `current` | `boolean` | `false` | The level is the page the person is on. Only the last item may be current. It is exposed as the current page and drawn heavier, without an underline; give it no href, so that it is text and not a link to where the person already is (BRC-4). | | `icon` | `string` | `""` | The name of a glyph of the system's icon set, drawn before the label ("home" for the top of the hierarchy). Empty: no glyph. | | `iconOnly` | `boolean` | `false` | Draws the glyph alone and keeps the label as the accessible name. Ignored while icon is empty. | | Event | Description | | --- | --- | | `click` | A level that is a link was activated by pointer, touch, Enter or assistive technology, in the trail or in the menu. It is emitted before the destination opens; a product that takes the navigation itself (a client-side router) cancels it (BRC-22). | ### States `enabled`, `hovered`, `focused`, `pressed` ### Accessibility - Role: `navigation` - Labeling: The landmark is named by label, which is required. Each level is named by its label, drawn or not (iconOnly); its glyph is decorative. The current page carries the current state; nothing is added to its name. The overflow button is named by overflowLabel, which is required while overflow is collapse, and says that it opens a menu. Separators are hidden from assistive technology. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab | Moves focus through the levels that are links and the overflow button, in the trail's order: each is a tab stop, as the links of a navigation region are. Text levels and levels behind the button are passed. | | Enter | Follows the focused link; on the overflow button, opens the menu. Space does what it does on any link (on the web it scrolls the page). | | Space | On the overflow button, opens the menu. | | Arrow keys, Home, End, Escape | In the open menu, as the menu's spec says: move among the hidden levels; Escape closes it and returns focus to the button. | - The current page is text by default, not a link. A link to the page a person is on leads nowhere, and adds a tab stop to every page of a product; as text it is still read in its place in the list, with the current state. A product that needs it to be a link (a page whose views change under one address) gives the item a destination, and it is then a link with the same look (BRC-4). A product whose page heading stands right under the trail may leave the current page out: the trail then ends at the parent, and no item is current. - In the default system a level that is a link is underlined, and the current page and a level without a page are not. That difference, with the heavier weight of the current page, is what tells them apart; color is not asked to (WCAG 1.4.1). The link color there is the primary's, which no scheme holds apart from the text color, so it could not. - A design system or a product may choose hover or never for the trail (BRC-30). A level that is a link is then told from a level that is text by its color, so the build holds the link color 3:1 apart from comp.breadcrumbs.label.color in every scheme where the choice is not always (an error in the default system, a warning in a product's layer). A trail whose every level above the current page is a link has no text level to be confused with, and the current page stays heavier; the check holds all the same, because one level without a page is enough. Forced colors draw the underline whatever was chosen (BRC-24). - The trail is a list of links in a landmark, not a toolbar: every link is a tab stop, and the arrow keys do nothing outside the menu. - Collapsing hides nothing from a person: every level taken out is in the menu, one press away, and the button says that it opens a menu. A trail that should never hide a level sets overflow to wrap. On the web the hidden levels' anchors stay in the document (BRC-13). - The last label is cut only when the button and it alone do not fit (BRC-14). The current page is usually the heading right under the trail, so the cut text is on the page in full; a product where it is not uses wrap. - The target. A level is a link that stands by itself, so its hit area is extended to sys.target without changing what is drawn (BRC-23), bounded halfway to its neighbours. Short labels beside each other keep the spacing WCAG 2.5.8 asks: a separator with its two gaps is 24 wide under the default system. - Text must remain readable at 200% text size: the trail grows with its text and collapses or wraps by the width it has; nothing has a fixed height (BRC-25). - Contrast in the default system: sys.color.link, on-surface and on-surface-variant are each held to 4.5:1 (7:1 in the high-contrast schemes) on every surface by the token invariants; the overflow glyph and the separators are on-surface-variant. The focus ring is held to 3:1 against every surface. - How a state looks is a value decision of the active design system (a state-layer mix in Tanrei, a dim or no hover at all elsewhere). The trail reads the state's tokens and never computes the effect itself. - A trail shows where a page is in the hierarchy, not the way a person came. A product that publishes the same hierarchy as structured data for search engines writes that itself, from the same items. ### Behaviour Requirements in EARS form, each with its stable id. - **BRC-1** THE breadcrumbs SHALL be one navigation landmark named by label that holds one ordered list of its items, in the order the product gave them — from the top of the hierarchy to the page — each a list item with its position in the list, and nothing else that assistive technology reads but the overflow button; WHILE label is empty THE breadcrumbs SHALL still render, and in debug builds report that the landmark has no accessible name. WHILE it has no item THE breadcrumbs SHALL draw nothing, take no room and expose no landmark. - **BRC-2** WHILE an item's href is a destination and its current is false THE breadcrumbs SHALL draw that level as the platform's own link to it (the web's anchor element in the document itself, not in a shadow root; SwiftUI's Link; on Compose, Flutter and React Native an element with the platform's link semantics whose address is opened by the platform's opener), so that whatever the platform gives a link — on the web its context menu, opening in a new tab or window, copying and dragging its address, the address shown before it is followed, a crawler that reads it, and a link that works before any script has run — is the platform's, and not the trail's to draw or to take over; it SHALL expose the link role, named by the item's label, and SHALL draw the label in comp.breadcrumbs.label.typescale and comp.breadcrumbs.item.content.color and, WHILE its underline is shown (BRC-30), with an underline comp.breadcrumbs.underline.width thick, comp.breadcrumbs.underline.offset below the text's baseline, in the label's color of its state, under the text only and not under a glyph. In the default system the underline is shown at rest and in every state: there, in a trail as in a sentence, the underline and not the color says that a level leads somewhere. - **BRC-3** WHILE an item has no destination and its current is false THE breadcrumbs SHALL draw that level as text — its label in comp.breadcrumbs.label.typescale and comp.breadcrumbs.label.color, with no underline and no container — which is not focusable, answers no hover, focus or press, has no role of its own and emits nothing: it names a level of the hierarchy that has no page. IF an item's href names a script to run rather than a place to go (the web's javascript: scheme) or cannot be read as an address by the platform THE breadcrumbs SHALL draw that level so too, and in debug builds report it. - **BRC-4** WHILE the last item's current is true THE breadcrumbs SHALL expose that level as the current page (on the web aria-current with the value page; on a platform without that state, the selected state) and SHALL draw its label in comp.breadcrumbs.current.content.color, with no underline, at the emphasized weight of its text style — that style's weight plus sys.typescale.emphasis.body — so that it is told from the levels above it by more than its color. WHILE that item has no destination it SHALL be text as BRC-3 says: not focusable, without states and without an event. WHILE it has a destination it SHALL be a link as BRC-2 says that keeps this look and answers hover, focus and press with the tokens of the current part. IF current is true on an item that is not the last THE breadcrumbs SHALL draw that item as if current were false, and in debug builds report it. - **BRC-5** THE breadcrumbs SHALL open a destination in the context the person is in and in no other, SHALL draw no mark for a new context and SHALL draw no state for a destination already visited: the levels of one hierarchy replace the page the person is on, and a level's colors say what it is and what state it is in. - **BRC-6** THE breadcrumbs SHALL draw one separator between every two neighbouring entries of the trail — levels and the overflow button alike — and none before the first or after the last: the glyph chevron_right of the system's icon set in a box comp.breadcrumbs.separator.size large, in comp.breadcrumbs.separator.color, comp.breadcrumbs.separator.gap from the entry on either side, centred on the line of the label beside it, drawn through the platform's icon helper with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max. A separator SHALL be hidden from assistive technology, SHALL be no part of a level's name, link or hit area, and SHALL keep its color in every state of the levels beside it. - **BRC-7** WHILE an item's icon names a glyph THE breadcrumbs SHALL draw it before the label in the reading direction, in a box comp.breadcrumbs.icon.size large, comp.breadcrumbs.container.gap from the label, centred on the label's line, in the color of the level's label and state, through the icon helper as BRC-6 draws a separator, hidden from assistive technology. WHILE iconOnly is also true THE breadcrumbs SHALL draw the glyph alone, with no label and no underline, its container a square one line of the trail's text high around it, and SHALL keep the item's label as its accessible name. WHILE an item's label is empty THE breadcrumbs SHALL still render it, and in debug builds report that the level has no name. - **BRC-8** WHILE overflow is collapse THE breadcrumbs SHALL set the trail on one line, each label on one line, as wide as its entries need and no wider than the layout gives it, aligned to the start, and SHALL NOT wrap or scroll it. - **BRC-9** WHILE overflow is collapse and the trail is wider than the width the layout gives it THE breadcrumbs SHALL take levels out of the trail and draw the overflow button once, in the place of the first level it took out: first the levels between the first and the last, beginning with the one next to the first and going on toward the last, each only if what is left still does not fit; then, if the first level, the button and the last level still do not fit, the first level as well, so that the button begins the trail. It SHALL NOT take out the last level, SHALL take out no more levels than the width asks for, and SHALL measure the trail with its separators and gaps, by the width it is given and not by the window's. - **BRC-10** THE breadcrumbs SHALL draw the overflow button as the glyph more_horiz of the system's icon set in a box comp.breadcrumbs.icon.size large, in comp.breadcrumbs.overflow.content.color, drawn as BRC-6 draws a separator, in a container that is a square one line of the trail's text high with corners comp.breadcrumbs.container.shape; it SHALL be one list item of the trail holding one focusable element with the button role, named by overflowLabel, that says it opens a menu and whether that menu is open, and WHILE overflowLabel is empty SHALL still render and in debug builds report that the button has no accessible name. WHILE no level is taken out THE breadcrumbs SHALL draw no overflow button. - **BRC-11** WHEN the user activates the overflow button by pointer, touch, Enter or Space THE breadcrumbs SHALL open a menu anchored to it, below it with the start edges aligned, that lists the levels taken out in the trail's order, each named by its label and showing its glyph where it has one: a level with a destination as an item that is a link to it, a level without one as a disabled item. What the menu draws, how focus enters it and moves in it, and how it closes are the menu's own (its spec's behaviours), and WHEN it closes without a level having been followed THE breadcrumbs SHALL return focus to the overflow button. - **BRC-12** WHEN the width the layout gives the trail, a label, the text size or the layout direction changes THE breadcrumbs SHALL decide again which levels are taken out, at once and without a motion of its own; a level that fits again SHALL return to its place in the trail. WHEN a level that holds keyboard focus is taken out THE breadcrumbs SHALL move focus to the overflow button, and WHEN the overflow button is removed while it holds focus or its menu is open THE breadcrumbs SHALL close the menu and move focus to the first level that returned. - **BRC-13** WHILE a level is taken out of the trail THE breadcrumbs SHALL keep it out of the list assistive technology reads and out of the focus order, reached through the menu alone; WHERE the platform's links are elements of a document (the web) THE breadcrumbs SHALL keep that level's link in the document, hidden, so that the whole trail is there for whatever reads the page as built and before any script has run. - **BRC-14** WHILE overflow is collapse and the overflow button with the last level alone is still wider than the width the layout gives, or the trail has one level that is, THE breadcrumbs SHALL cut that level's label with an ellipsis at the end of its own direction (BRC-28), keeping the button, the separator and a glyph whole; the full label SHALL remain what assistive technology reads. - **BRC-15** WHILE overflow is wrap THE breadcrumbs SHALL keep every level in the trail and draw no overflow button: it SHALL break the trail onto as many lines as it needs, comp.breadcrumbs.row-gap apart and aligned to the start, only after a separator, so that a separator ends a line and never begins one; a label longer than a line SHALL wrap where its language allows a break and, for a run with no such place, inside the run, and SHALL NOT be cut. - **BRC-16** WHILE a level that is a link or the overflow button is hovered, keyboard-focused or pressed THE breadcrumbs SHALL render its container, its content — the label with its underline and glyph, or the button's glyph — and its opacity from the component tokens of its part (item, current, overflow) in the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. The container SHALL be the box of the content, with corners comp.breadcrumbs.container.shape, and SHALL take no room and move nothing beside it. - **BRC-17** WHEN a level that is a link or the overflow button receives keyboard focus THE breadcrumbs SHALL show the focus ring around its container without animation — the system's focus indicator, sys.focus.offset from the container, sys.focus.outer-width wide in the focus-ring color, with the inner stroke of sys.focus.inner-width where the system has one — and, for a label that runs over several lines of a wrapped trail, around its part of each line; focus gained by pointer or touch SHALL NOT show it. - **BRC-18** WHEN a level that is a link is pressed by pointer, touch or Enter, or the overflow button by pointer, touch, Enter or Space, THE breadcrumbs SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. - **BRC-19** WHILE pressed THE breadcrumbs SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; content, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.breadcrumbs.motion.feedback-duration with motion.state-easing, fades over motion.state-duration with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **BRC-20** THE breadcrumbs SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. - **BRC-21** THE breadcrumbs SHALL change a level or the overflow button between its states over comp.breadcrumbs.motion.state-duration with comp.breadcrumbs.motion.state-easing, and at once where motion is reduced. - **BRC-22** WHEN the user activates a level that is a link in the trail by pointer, touch or Enter THE breadcrumbs SHALL emit that item's click exactly once and then open its href, unless the product cancelled that click, in which case it SHALL open nothing: the product's own router has taken the navigation. It SHALL NOT hold the navigation back for sys.motion.duration.press-hold. THE breadcrumbs SHALL NOT activate a link in the trail on Space, which on the web scrolls the page as it does on any link, and SHALL NOT show the pressed state for it; a level listed in the menu is the menu's link item, whose keys and activation are the menu's own (MNU-53, MNU-54: its click is emitted once and can be cancelled, the menu closes, then the destination opens, and Space activates it as it does every row of a menu); WHERE the platform gives its links other keys or gestures (on the web a modified or a middle click that opens a new tab, on Apple platforms a long press that previews) THE breadcrumbs SHALL leave them to the platform. - **BRC-23** WHERE the visual size of a level that is a link or of the overflow button is below the minimum target THE breadcrumbs SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size or the room it takes, on the axis of the trail no further than halfway to the entry beside it, and, WHILE the trail runs over several lines (BRC-15), across them no further than half comp.breadcrumbs.row-gap toward a line above or below that level, so that no two hit areas overlap; a platform that cannot tell the input type SHALL use sys.target.touch. - **BRC-24** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE breadcrumbs SHALL draw a level that is a link, with its underline and glyph, in the platform's link color, the current page, a level without a destination and the separators in its text color, the overflow button's glyph in its button text color, and the focus ring in its highlight color, and SHALL draw the underline of a level that is a link at rest, whatever underline and the tokens it follows say: the colors are then the person's, and nothing holds a link's color apart from a text level's. - **BRC-25** WHILE the text size is enlarged THE breadcrumbs SHALL grow with its text — its labels, its containers and its hit areas — keeping comp.breadcrumbs.separator.gap, comp.breadcrumbs.container.gap, comp.breadcrumbs.underline.width, comp.breadcrumbs.underline.offset, comp.breadcrumbs.row-gap and its glyphs at comp.breadcrumbs.icon.size and comp.breadcrumbs.separator.size, and SHALL decide again what fits (BRC-12). - **BRC-26** THE breadcrumbs SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the breadcrumbs is shown THE breadcrumbs SHALL draw itself for the new direction at once, without a motion of its own, keeping its focus and whether its menu is open. - **BRC-27** WHERE the layout direction is right-to-left THE breadcrumbs SHALL lay the trail out from the right — the top of the hierarchy at the right and the page at the left, a level's glyph at the right of its label, the menu opening with its right edge on the button's — and SHALL draw each separator mirrored left to right, pointing to the left, the way the trail reads: the icon helper mirrors it inside its own box because the system's icon set marks chevron_right as mirrored. It SHALL draw a level's own glyph mirrored exactly when the icon set marks that glyph's name or the product forces mirroring for that use, and unmirrored when the product forbids it. THE breadcrumbs SHALL NOT mirror a glyph itself, and the reading and focus order SHALL stay from the top of the hierarchy to the page. - **BRC-28** THE breadcrumbs SHALL lay out each label as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right name, a number with its sign or unit and a version keep their own order in a right-to-left layout and reorder nothing beside them; THE breadcrumbs SHALL still place the label by the layout direction, not by the text's own, and SHALL cut a label that does not fit (BRC-14) at the end of its own direction, so that a left-to-right label in a right-to-left layout loses its right end and never its beginning. - **BRC-29** WHEN overflow names a value the breadcrumbs does not have THE breadcrumbs SHALL behave as collapse, and in debug builds report the unknown value. - **BRC-30** THE breadcrumbs SHALL show the underline of every level that is a link as its underline prop names: WHILE underline is auto, as comp.breadcrumbs.underline.visibility names, which follows sys.behavior.link-underline unless a design system sets the trail apart; WHILE underline is always, hover or never, as that value names, whatever the tokens say. always draws the line at rest and in every state; hover draws none at rest and draws it WHILE the level is hovered, keyboard-focused or pressed, the line arriving and leaving with that state as BRC-16 renders it and moving no level; never draws none in any state, and hover, focus and press are still shown by the container, the label color and the focus ring. The links of the overflow menu are menu items and are never underlined. WHEN underline, or the token it follows, changes THE breadcrumbs SHALL draw the other form at once, keeping its focus and what it has collapsed; WHEN underline names a value the breadcrumbs does not define THE breadcrumbs SHALL treat it as auto and in debug builds report the unknown value. A platform that cannot draw a choice SHALL fall back to the first value, always, and state that in its README. - **BRC-31** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE breadcrumbs SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its navigation landmark (BRC-1) — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label is not empty it is the landmark's name, over a name given so; WHILE label is empty, a name given so is the landmark's name and SHALL NOT be reported as having none in debug builds. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE breadcrumbs SHALL take it off that element. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.breadcrumbs.…` → `--tanrei-comp-breadcrumbs-…`). #### `tanrei.comp.breadcrumbs` | Token | Type | Value | | --- | --- | --- | | `comp.breadcrumbs.container.shape` | `dimension` | `{tanrei.sys.shape.corner.extra-small}` | | `comp.breadcrumbs.container.gap` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.breadcrumbs.label.typescale` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.breadcrumbs.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.breadcrumbs.underline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.breadcrumbs.underline.offset` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.breadcrumbs.underline.visibility` | `number` | `{tanrei.sys.behavior.link-underline}` | | `comp.breadcrumbs.icon.size` | `dimension` | `{tanrei.sys.icon.extra-small}` | | `comp.breadcrumbs.separator.size` | `dimension` | `{tanrei.sys.icon.extra-small}` | | `comp.breadcrumbs.separator.gap` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.breadcrumbs.separator.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.breadcrumbs.row-gap` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.breadcrumbs.item.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.breadcrumbs.item.content.color` | `color` | `{tanrei.sys.color.link}` | | `comp.breadcrumbs.item.state-layer.color` | `color` | `{tanrei.comp.breadcrumbs.item.content.color}` | | `comp.breadcrumbs.current.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.breadcrumbs.current.content.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.breadcrumbs.current.state-layer.color` | `color` | `{tanrei.comp.breadcrumbs.current.content.color}` | | `comp.breadcrumbs.overflow.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.breadcrumbs.overflow.content.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.breadcrumbs.overflow.state-layer.color` | `color` | `{tanrei.comp.breadcrumbs.overflow.content.color}` | | `comp.breadcrumbs.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.compact}` | | `comp.breadcrumbs.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.breadcrumbs.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.breadcrumbs...` for the variants `item`, `current`, `overflow`, the states `hovered`, `focused`, `pressed` and the properties `container.color`, `content.color`, `state-layer.color`. - `comp.breadcrumbs..` for the states `hovered`, `focused`, `pressed` and the properties `opacity`, `container.shape`. ## Button > Lets people take an action, switch something on and off, go to a destination, or send or clear the form it stands in, with one tap or click — named by a label, an icon, or both. - Category: Actions - Level: base - Listing: default - Used in: Copy button, Chat composer - Page: https://tanrei.chnotchy.com/components/button/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/button.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/button`). - React: `Button` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-button` | lagging | | SwiftUI | `TanreiButton` | lagging | | Jetpack Compose | `TanreiButton` | lagging | | Flutter | `TanreiButton` | lagging | | React Native | `Button` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `destructive` (prop) | `destructive` | `role` | `destructive` | `isDestructiveAction` | `destructive` | | `iconPosition` (prop) | `iconPosition` | `iconPosition` | `iconPosition` | `iconAlignment` | `iconPosition` | | `toggle` (prop) | `toggle` | `isSelected` | `onCheckedChange` | `isSelected` | `toggle` | | `selected` (prop) | `selected` | `isSelected` | `checked` | `isSelected` | `selected` | | `disabled` (prop) | `disabled` | `disabled` | `enabled` | `onPressed` | `disabled` | | `busyLabel` (prop) | `busyLabel` | `busyLabel` | `busyLabel` | `busySemanticLabel` | `busyLabel` | | `href` (prop) | `href` | `destination` | `href` | `href` | `href` | | `targetLabel` (prop) | `targetLabel` | `targetLabel` | `targetLabel` | `targetSemanticLabel` | `targetLabel` | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | | `click` (event) | `click` | `action` | `onClick` | `onPressed` | `onPress` | | `change` (event) | `change` | `isSelected` | `onCheckedChange` | `onPressed` | `onSelectedChange` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The shape that holds the content, defines the visual bounds and carries hover, focus and press. A pill with a label; with an icon alone, as wide as it is high (a circle in the default system's corner) or at the narrow or the wide width of its size. - `label` (optional): Text that names the action. - `icon` (optional): A glyph of the system's icon set, at the leading or the trailing side of the label, or alone. Outlined when unselected, filled when selected. - `outline` (optional): The border of the outlined variant. - `focus-ring`: Gap-then-ring indicator shown for keyboard focus. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `filled`, `tonal`, `elevated`, `outlined`, `text` | `"filled"` | `variant` | Emphasis level; whether the action deletes or discards something is destructive, which every variant takes. Use one filled button per view for the main action; an icon-only text button is the quiet icon action of a toolbar or a row. A design system may add values. Default filled; a Button placed as a dialog's or a side sheet's action without a variant takes that host's (DLG-20, SSH-17), and a side sheet's close button takes comp.side-sheet.close-button.variant (SSH-5). | | `destructive` | `boolean` | `false` | `destructive` | Marks an action that deletes or discards something a person may not get back (Delete, Discard, Remove member): the button keeps its variant's emphasis and takes the error role's color in it — filled in the error color, tonal in its tonal container, and the error color for the label of an elevated, outlined or text button and the edge of an outlined one (BTN-40). Use it for that kind of action alone, never for emphasis. It adds a color, not a meaning: the label still says what the button does (BTN-42). A toggle has no destructive look: ignored while toggle is true (BTN-41). A link deletes nothing: ignored while href is not empty (BTN-43). | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Visual height: comp.button.container.height.\, never drawn below sys.target.minimum (36 / 40 / 56 under the default system, the small one held at the minimum), which is also an icon-only button's width at its default width. The hit area always meets the minimum target. While it is not set the button is drawn at the size its nearest container sets — a button group's or a toolbar's size (BTN-48) — and at medium where none does. A design system may add values. | | `width` | `enum`: `default`, `narrow`, `wide` | `"default"` | `width` | How wide an icon-only button is. default: as wide as it is high (36 / 40 / 56 under the default system). narrow: its glyph with a small inset on each side (28 / 32 / 32), for a tight row of icon actions. wide: 40 / 52 / 72, for the one action of a row that should weigh more. Ignored when the button has a label, and while fullWidth is true. The hit area meets the minimum target at every width. | | `fullWidth` | `boolean` | `false` | `full-width` | Makes the button take the whole width its container gives it, its content centred, at the height of its size (BTN-39): a form's only action on a narrow screen, the action at the foot of a card or a sheet. Ignored while a host lays the button out (a button group, a toolbar, or the actions of a dialog, a side sheet, a popover, a callout or an empty state), which gives it a width of its own (a button group's fullWidth for a row of them). | | `iconPosition` | `enum`: `leading`, `trailing` | `"leading"` | `icon-position` | Which side of the label the icon sits on, in the reading direction. Ignored when the button has no label or no icon. | | `toggle` | `boolean` | `false` | `toggle` | Makes the button a two-state control: activation switches selected, and assistive technology announces it as pressed or not pressed. A toggle takes no destination: href is ignored while toggle is true. | | `selected` | `boolean` | `false` | `selected` | Whether a toggle is on. Ignored unless toggle is true. | | `disabled` | `boolean` | `false` | `disabled` | Prevents interaction and removes the button from the focus order — unless focusableWhenDisabled keeps it there (BTN-38). A disabled button with a destination is not a link that can be followed (BTN-25); on the web a disabled submit button sends nothing, and still stops Enter from sending its form where it is the form's default button (BTN-32). | | `focusableWhenDisabled` | `boolean` | `false` | `focusable-when-disabled` | Keeps a disabled button in the focus order: it is drawn and exposed as disabled and refuses every activation, but a keyboard and a screen reader can still reach it, so that a person can learn why it does nothing (a tooltip, a description). For an action a person can make available — a send button while the message is empty. Ignored unless disabled is true (BTN-38). | | `busy` | `boolean` | `false` | `busy` | The action it started is under way: the button keeps its focus, its place in the focus order and its size, draws the loading indicator's arc in place of its label and icon, refuses every activation, and tells assistive technology through busyLabel (BTN-36, BTN-37). For a save or a send that takes a moment; it is not disabled, so focus stays where the person left it. | | `busyLabel` | `string` | `""` | `busy-label` | What assistive technology is told while the button is busy ("Saving"): announced once when it becomes busy and read after its name while it is. Tanrei ships no words of its own. Required while busy is true; ignored otherwise. | | `href` | `string` | `""` | `href` | The destination: an address as the platform's links take one (a URL; on the web a path or a fragment as well). Not empty, it makes the button a link and not a button: the link role, activated by pointer, touch or Enter and not by Space, opened by the platform as its own links are, and drawn exactly as the button it would otherwise be (BTN-22, BTN-23). Ignored while toggle is true: a control that holds a state is not a destination (BTN-26). | | `target` | `enum`: `same`, `new` | `"same"` | `target` | Where the destination opens. same: where the person is — the same tab on the web, the app's own handling of the address elsewhere. new: a new context — a new tab or window on the web, outside the current screen elsewhere — which a labelled button marks with the glyph open_in_new after its label and says through targetLabel (BTN-24). Ignored without href. | | `targetLabel` | `string` | `""` | `target-label` | What assistive technology reads after the link's name while target is new ("opens in a new tab"). Tanrei ships no words of its own, so the product gives them in its own language, as it gives a chip its removeLabel. Required while target is new; ignored otherwise. | | `label` | `string` | `""` | `label` | The accessible name, where it is more than what the button draws. Required for an icon-only button: an icon alone is not a name. Optional for a button that draws a label: left empty, the drawn text is the name; given, it is the whole name in place of the drawn text, which stays drawn — for an action repeated in every row (drawn "Reset", named "Reset: Spacing") — and it must contain the drawn text, so that a person who says what they see is heard (BTN-16). It is about this one button, so it is the instance's alone and reads no word of the product's. | | `value` | `string` | `""` | `value` | What the button stands for, as data: never drawn and never announced. A component that holds a selection of Buttons reads it to tell which of them are selected — a toolbar group whose selection is single or multiple holds its selected members' values (TBR-28) — and on the web, with name, it is what a form is sent when this button submits it (BTN-31). Unique among the members of one selection. | ### Events | Event | Description | | --- | --- | | `click` | The button was activated by pointer, touch, keyboard or assistive technology. A link button emits it before its destination opens; a product that takes the navigation itself (a client-side router) cancels it (BTN-23). | | `change` | A toggle was activated; carries the new value of selected. | ### Slots | Slot | Description | | --- | --- | | `default` | Label content: the text that names the action. Leave it empty for an icon-only button. | | `icon` | The icon: a glyph of the system's icon set, drawn through the platform's icon helper. With a label it sits at the side iconPosition names; without one it is the button's only content. | ### States `enabled`, `disabled`, `hovered`, `focused`, `pressed`, `selected`, `loading` ### Accessibility - Role: `button (link while href is set)` - Labeling: A button that draws a label is named by that text, unless label is given: then label is the whole name, in place of the drawn text, and it must contain the drawn text (BTN-16). An icon-only button is named by label, which is required; its glyph is decorative to assistive technology. A tooltip may show the same text to sighted pointer users, but it never replaces label. A link button is named in the same way; its name should say where it goes. While target is new, targetLabel is its description ("opens in a new tab"), and the mark is decorative. A description is read after the name and is never the name: what tells one button from its neighbours belongs in the name, and what happens next belongs in the description. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab | Moves focus to the button — also to a busy one, and to a disabled one while focusableWhenDisabled is true. | | Enter or Space | Activates the button; a toggle switches selected. A link button is activated by Enter alone: Space does what it does on any link (on the web it scrolls the page). | | Enter in a field of the same form | On the web, presses the form's default button — its first submit button — where that is a Button of type submit, and so submits the form; nothing while that button is disabled (BTN-30). Enter in a Tanrei field, checkbox, radio button or switch does the same where the default button is the platform's own. | - A toggle is a button with an on/off state (aria-pressed on the web, the selected trait on Apple platforms, a toggleable state on Android), not a checkbox or a switch; its name does not change with its state. In a toolbar group whose selection is single it is one choice of a radio group instead, checked or not checked (BTN-47). - Text must remain readable at 200% text size: the container grows, the label never truncates by default. - Container heights are minimums: at larger text sizes the container grows in both axes. An icon-only button's glyph is not text, at any of its three widths: where sizes are points or dp (SwiftUI, Compose, Flutter, React Native), text size leaves its circle and its glyph as they are; on the web every Tanrei size follows the root font size (rem), so at 200% text size the circle and its glyph grow together and stay round and whole (BTN-12). Either way its label is still announced. - The icon's side follows the reading direction: leading is the start (left in left-to-right, right in right-to-left). A glyph whose name the system's icon set marks as mirrored (arrow_forward, chevron_right, reply) is mirrored in a right-to-left layout by the icon helper, not by the button, and the product can force or forbid that for one use (BTN-19). - How a state looks is a value decision of the active design system (a state-layer mix in Tanrei, possibly explicit colors, a dim, or no hover at all elsewhere). Components read the state's tokens and never compute the effect themselves, with one exception: on a tone a host gives it (BTN-45), whose color is known only where the button is drawn, the button lays the tone over its container at the system's state-layer opacities, as a carousel lays its state layer over a product's image. A system that draws no state layer sets those opacities to 0. - A narrow icon-only button is drawn narrower than the minimum target; its hit area is not (BTN-21). Leave room for the target beside it, or put narrow buttons in a toolbar or a group that spaces them. - The outline of an outlined button is the hairline of the default system (the divider's color), which is far below 3:1 against the surface. That is within WCAG 1.4.11: the edge is not what identifies the control. Its label is text held to 4.5:1 and its icon to the same ratio, a toggle that is on is shown by its fill, and focus by the focus ring. A product whose outlined buttons must show a 3:1 edge sets comp.button.outlined.outline.color to sys.color.outline in a layer. - A button with a destination is a link: the link role, the platform's own link, Enter and not Space. It is not a button that navigates from a click handler: on the web such a button has no address to copy, cannot be opened in a new tab and is announced as something that acts on the page. The look does not say which of the two it is, and need not: sighted people tell a destination from an action by its label, as they do in a toolbar. - Tanrei draws no visited state for a link button: it is a control whose color says its emphasis and its state, and the web restricts what a visited link may change to colors a page cannot read back. Visited links are a matter for links in running text. - A link that opens a new context says so twice: the open_in_new mark for people who see it, and targetLabel for people who do not (WCAG 1.1.1: the mark carries information, so it needs a text alternative; technique G201 advises warning before a new window). The words are the product's. - An action repeated in every row of a list or a table is drawn with one word and named for its row: label is the whole name ("Reset: Spacing"), opening with the drawn word where the language allows. Six buttons that are all named "Reset" cannot be told apart in the list of controls a screen reader offers, and a description does not appear there. The name must contain the drawn text (WCAG 2.5.3, label in name): a person who uses speech input says the word on the button. A debug build reports a name that does not; it never repairs one, because joining two texts into a phrase is a decision about a language, and the words are the product's. - On the web a Button of type submit or reset is its form's button as the platform's own is: the form validates, fires its submit or reset event, and the pressed button's name and value are sent with it. Enter in a field presses the form's first submit button, and a disabled one stops it. The default type is button, not the platform's submit: a button put in a form for another purpose must never send it by accident (BTN-27, BTN-33). - A button can keep a form from being sent twice: while busy it is shown and focusable but refuses every press, emits no click and therefore submits nothing (BTN-27 follows click), and it stops Enter in a field as a disabled default button does (BTN-37, BTN-32). Prefer it to disabling the button while the first submission is on its way: a disabled button drops the person's focus, and says nothing of why. - Where script does not run, or before the element is defined, a web Button is its text and nothing else, and submits nothing; so is every Tanrei field, so a form made of them cannot be filled either. A form that must be sent without script is made of the platform's own controls, with the platform's own submit button. - The native platforms have no form element, and the Button has no type there (BTN-34): which button the Return key presses is the app's to say, in the platform's idiom. - A disabled button leaves the focus order, so a keyboard or screen-reader user may never learn it is there or why it does nothing. Where a person can make the action available (fill in the message, choose a file), keep it reachable with focusableWhenDisabled and say why in a tooltip or a description; where the action simply does not apply, leave it out of the focus order (BTN-38). - destructive adds a color, never a meaning (WCAG 1.4.1, use of color): the error color tells people who see it that the action deletes or discards something, and nothing tells a screen reader user so but the label. So the label names the action and what it acts on ("Delete project", not "OK"), and a dialog that confirms it says what will be lost in its headline and supporting text. The web has no role or state for a destructive action, so none is invented; SwiftUI's destructive role is given where it exists, and the platform decides what it does with it. - Disabled, a destructive button looks like any disabled button of its variant: the error color is a warning about what a press would do, and a button that cannot be pressed does nothing. - A tone keeps a button readable on a colored surface its host draws (a status callout, an inverse snackbar): the button's content takes the surface's own content color, which the host holds to the contrast its own text needs, and its container is a translucent layer of that color rather than a color chosen against the page. The layer lowers the contrast between the content and what is under it a little (at 16 % in the default system, about a sixth of the way from the surface toward the content color): a host's content color must still hold 3:1 against that blend for an icon-only button (WCAG 1.4.11) and 4.5:1 for a labelled one (WCAG 1.4.3). ### Behaviour Requirements in EARS form, each with its stable id. - **BTN-1** WHEN the user activates the button by pointer, touch, Enter or Space — a link button (BTN-22) by pointer, touch or Enter — THE button SHALL emit click exactly once. - **BTN-2** WHILE disabled is true THE button SHALL NOT emit click or change, SHALL NOT be focusable and SHALL expose the disabled state to assistive technology. - **BTN-3** WHILE hovered, keyboard-focused or pressed THE button SHALL render its container, label, icon, outline, elevation and opacity from the component tokens of the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. - **BTN-4** WHEN the button receives keyboard focus THE button SHALL show the focus ring without animation; focus gained by pointer or touch SHALL NOT show it. - **BTN-5** WHERE the visual size is below the minimum target THE button SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size; a platform that cannot tell the input type SHALL use sys.target.touch. WHERE a component lays the button out beside another control — in a row or a column of its own, as a button group, a toolbar, the actions of a dialog, the controls of a snackbar or a field's own buttons do — THE button SHALL extend its hit area toward that neighbour no further than the middle of the gap between their visible bounds, and toward a side where nothing of the row stands as far as the row's own place allows, so that a press on a neighbour's visible bounds is never the button's and a press in the gap goes to the nearer of the two. WHERE the product lays buttons out beside each other itself, outside any such component, THE button SHALL take from the product how far its hit area may reach past its visible bounds toward each side — the start and the end of the row, the top and the bottom of a column — and reach no further, never less than its visible bounds; a component that lays the button out in a row of its own decides the reach toward the others in that row, over what the product gave around it, and the product's reaches the sides that component leaves open (the outer ends of a button group). - **BTN-6** WHILE disabled is true THE button SHALL render its container, label, icon, outline, elevation and opacity from the disabled component tokens of its variant and, for a toggle, of its selection, and, while destructive is true, of its destructive parts (BTN-40). - **BTN-7** WHEN variant or size names a value that the active design system does not have THE button SHALL render with the default value's tokens, and in debug builds report the unknown value. - **BTN-8** WHEN the button is pressed by pointer, touch, Enter or Space THE button SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. - **BTN-9** WHILE pressed THE button SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, icon, outline, elevation, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.button.motion.feedback-duration with motion.state-easing, fades over the motion.state-duration of its size with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **BTN-10** THE button SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. WHILE the button is an item of a connected button group THE button SHALL draw its corners and minimum width and height as the group sets them, the padding the group adds at a rounded outer end, and neither outline nor elevation ring along an edge the group joins to a neighbour under a divider, and, from a dialog, a side sheet or an image preview, its variant while none is set (DLG-20, SSH-17, IMP-8) and a host's close-button variant — the popover's, the side sheet's, the bottom sheet's, the callout's and the snackbar's close button, each an icon-only Button of the small size (POP-13, SSH-5, BSH-29, CLO-10, SNK-34; the image preview's bar names one variant for its close and zoom controls, IMP-8), from any component that draws it on a colored surface of its own, a tone (BTN-45), and, from a toolbar group whose selection is single, that it is one choice of that group (BTN-47), through an internal channel that is not part of its public surface (BGR-2, BGR-3, BGR-16, BGR-22, BGR-23). - **BTN-11** WHILE the button has both a label and an icon THE button SHALL draw the icon at the side iconPosition names in the reading direction (leading at the start, trailing at the end, both mirrored in right-to-left layouts) and the label comp.button.container.gap.medium from it at the medium size (and the gap of its own size otherwise), with comp.button.container.padding-inline-start-with-icon.medium on the icon's side for a leading icon and comp.button.container.padding-inline-end-with-icon.medium for a trailing one, and the plain padding (comp.button.container.padding-inline-start.medium, comp.button.container.padding-inline-end.medium) on the other side, each of its own size; WHILE it has a label and no icon it SHALL use the plain padding on both sides and ignore iconPosition. - **BTN-12** WHILE the button has an icon and no label THE button SHALL draw its container at the height of its size — comp.button.container.height.medium at the medium size, and the height of its own size otherwise — and at the width its width names: as wide as it is high WHILE width is default, as wide as its glyph's box (comp.button.icon.size-without-label.medium) with comp.button.container.padding-inline-narrow.medium on each side of it WHILE width is narrow, and comp.button.container.width-wide.medium wide WHILE width is wide (each of its own size), with the glyph centred, and SHALL round it by comp.button.container.shape, capped at half its shorter side, so that the default system's sys.shape.corner.full draws a circle at the default width and a capsule at the other two, and a smaller corner a rounded square or rectangle. The narrow width SHALL be the glyph and that inset twice, and nothing more: the button has no narrow width of its own to disagree with them, so a narrow button follows its glyph wherever a design system re-sizes it, and its container, state layer, ripple and outline are a capsule of that width. In the default system the inset is sys.space.space50 at every size, the least room that keeps the glyph clear of the capsule's edge; a design system that wants its narrow buttons to differ more by size gives a size a larger inset. It SHALL NOT draw an icon-only button at any other width, except to the minimum width a connected button group sets and the padding that group adds at an outer end (BTN-10). WHERE text size scales the glyph (every size follows the root font size on the web) the container SHALL grow with it and keep the proportion of its width to its height. - **BTN-13** THE button SHALL draw its icon at the icon box of its size — comp.button.icon.size.medium beside a label and comp.button.icon.size-without-label.medium alone at the medium size, and so on — with the family and fill of its selection (sys.icon.family.selected and sys.icon.fill.selected only when toggle and selected are both true; otherwise sys.icon.family.unselected and sys.icon.fill.unselected), sys.icon.weight, and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max; beside a label the icon SHALL take the label color of the button's look, and alone the icon color of its look (comp.button.text.icon.color for a plain text button, comp.button.text.selected.icon.color for a text toggle that is on, and so on). - **BTN-14** WHEN toggle is true and the user activates the button THE button SHALL emit click and then change with the opposite of selected, in that order (as a native checkbox does, and as CHP-11 says for a filter chip), and SHALL expose selected to assistive technology as pressed or not pressed; WHILE toggle is false THE button SHALL NOT expose a pressed state. - **BTN-15** WHILE toggle is true THE button SHALL render its container, label, icon and outline from the selected parts of its variant when selected is true (comp.button.filled.selected.container.color, and so on) and from the unselected parts when it is false (comp.button.filled.unselected.container.color, and so on), and its elevation from its variant's own comp.button.filled.container.elevation (and so on); WHILE toggle is false it SHALL render from the variant's own parts. - **BTN-16** WHILE the label prop is not empty THE button SHALL expose it as its accessible name, whole and alone, whether or not it draws a label; WHILE the label prop is empty and the button draws a label THE button SHALL expose the drawn label's text as its accessible name; WHILE the label prop is empty and the product gives the button a name of its own on the element — aria-label, or aria-labelledby naming an element — THE button SHALL expose that name as its accessible name, over the drawn label's text where it draws one, because the platform's text alternative computation puts an author's name over the element's content; WHILE the label prop is not empty THE label prop SHALL be the name, over the product's. WHILE it has an icon and no drawn label THE button SHALL keep the glyph from assistive technology, and WHILE the label prop is empty as well and the product gives it no name of its own SHALL still render, and in debug builds report that it has no accessible name. WHILE the button draws a label and the label prop is not empty THE button SHALL draw the label exactly as it would without the prop, SHALL NOT expose the drawn text a second time beside the name, and in debug builds SHALL report a label prop that does not contain the drawn text — the two compared with white space at their ends dropped, runs of white space read as one space and letters compared without case — because a person who speaks the words they see must be heard by the control that shows them. That report SHALL be all the button does about it: it SHALL still expose the label prop, whole and alone, as the name, SHALL NOT fall back to the drawn text and SHALL NOT add the drawn text to the name, in a debug build as in any other. THE button SHALL NOT make a name of the two itself, by joining them or in any other way: the order of a phrase is the language's, and the whole name is the product's to give. A description — the platform's own, or targetLabel (BTN-24) — SHALL be read after the name and the role and SHALL NOT be exposed as a name or as part of one. - **BTN-17** IF the button has neither a label nor an icon THE button SHALL still render its container at the height of its size and as wide as it is high, and in debug builds report that it has no content. - **BTN-18** THE button SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the button is shown THE button SHALL draw itself for the new direction at once, without a motion of its own, keeping its selection and its focus. - **BTN-19** WHERE the layout direction is right-to-left THE button SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order BTN-11 gives. THE button SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name. - **BTN-20** THE button SHALL lay out its label as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE button SHALL still place the label and align its lines by the layout direction, not by the text's own. - **BTN-21** WHILE the button has a label THE button SHALL ignore width: a labelled button is as wide as its content and its paddings (BTN-11). WHEN width names a value the button does not define THE button SHALL render at the default width, and in debug builds report the unknown value. THE button SHALL meet the minimum target of BTN-5 at every width by extending its hit area: a narrow button SHALL NOT be drawn wider to reach it. - **BTN-22** WHILE href is not empty and toggle is false THE button SHALL be a link and not a button: it SHALL expose the link role, named as BTN-16 names a button, with no pressed state; SHALL be the platform's own link to href (the web's anchor element; SwiftUI's Link; on Compose, Flutter and React Native an element with the platform's link semantics whose address is opened by the platform's opener), so that whatever the platform gives a link — on the web its context menu, opening in a new tab or window, copying and dragging its address, and the address shown before it is followed — is the platform's, and not the button's to draw or to take over; and SHALL draw its container, label, icon, outline, elevation and opacity in every state from the same tokens as a button of its variant, size and width that has no destination, with no look of its own for a link and none for a destination already visited. - **BTN-23** WHEN the user activates a link button by pointer, touch or Enter THE button SHALL emit click exactly once and then open href where target names, unless the product cancelled that click, in which case it SHALL open nothing: the product's own router has taken the navigation. It SHALL show the pressed state as BTN-8 and BTN-9 say and SHALL NOT hold the navigation back for sys.motion.duration.press-hold. THE button SHALL NOT activate a link button on Space, which on the web scrolls the page as it does on any link, and SHALL NOT show the pressed state for it; WHERE the platform gives its links other keys or gestures (on the web a modified or a middle click that opens a new tab, on Apple platforms a long press that previews) THE button SHALL leave them to the platform. - **BTN-24** WHILE the button is a link and target is new THE button SHALL open href in a new context — on the web a new tab or window that is given no handle to the page that opened it; on the other platforms outside the screen the person is on, as the platform's opener decides — and, WHILE it has a label and no icon at its trailing side, SHALL draw the glyph open_in_new of the system's icon set after the label as BTN-11 draws a trailing icon: comp.button.container.gap.medium from the label, at comp.button.icon.size.medium, with comp.button.container.padding-inline-end-with-icon.medium between it and the end edge at the medium size (and each of its own size otherwise), a leading icon keeping its own side as BTN-11 says; in the label color of its look and state; through the icon helper, which mirrors it in a right-to-left layout because the icon set marks its name; and hidden from assistive technology. WHILE the button holds the product's own icon at its trailing side, or has no label, THE button SHALL draw no mark of its own: the product has chosen what that place shows. Whether a mark is drawn or not THE button SHALL expose targetLabel as its description, read after its name and role, and WHILE targetLabel is empty SHALL still render and in debug builds report that a link that opens a new context does not say so. WHILE target is same THE button SHALL draw no mark and SHALL ignore targetLabel. - **BTN-25** WHILE href is not empty and disabled is true THE button SHALL NOT be a link that can be followed: it SHALL render as BTN-6 says, the mark of BTN-24 in the disabled label color, SHALL expose the link role with the disabled state and no destination, SHALL NOT be focusable, SHALL NOT emit click, and SHALL open nothing by any means the platform gives a link (on the web the anchor carries no href, so there is no context menu entry, no drag and no new tab for it). - **BTN-26** WHILE toggle is true THE button SHALL ignore href, target and targetLabel and stay the toggle BTN-14 describes, and in debug builds SHALL report that a toggle cannot be a link: a control that holds a state is not a destination. WHEN target names a value the button does not define THE button SHALL behave as same, and in debug builds report the unknown value. IF href is only white space, or names a script to run rather than a place to go (the web's javascript: scheme), or cannot be read as an address by the platform, THE button SHALL be a button without a destination, and in the last two cases report it in debug builds. - **BTN-27** WHERE the platform has a form element (the web) and WHILE type is submit, WHEN the user activates the button by any means of BTN-1 and the product has not cancelled its click THE button SHALL ask its form (BTN-29) to submit as the platform's own submit button does: after click has been emitted, exactly once for one activation, with the form's own validation run first and its failure shown by the platform and by the fields as they show it, then the form's submit event, which the product may cancel, and with the pressed button named in what is sent (BTN-31). It SHALL show the pressed state as BTN-8 and BTN-9 say and SHALL NOT hold the submission back for sys.motion.duration.press-hold. WHILE type is button, which is the default, THE button SHALL do nothing to any form, whatever it stands in. - **BTN-28** WHERE the platform has a form element (the web) and WHILE type is reset, WHEN the user activates the button and the product has not cancelled its click THE button SHALL ask its form (BTN-29) to reset as the platform's own reset button does: after click has been emitted, the form's reset event, which the product may cancel, and then every control of the form back at its initial value; it SHALL validate nothing, submit nothing and add nothing to any later submission. - **BTN-29** THE button's form SHALL be the one the platform gives a control at its place: the nearest form among its ancestors, or, WHILE the web's form attribute is not empty, the form of that id in the same document, and then not an ancestor; it SHALL be read when the button is activated, so that a button moved into a form, or a form attribute written later, is followed. WHERE the platform lists a form's controls (the web's form.elements) THE button SHALL be listed among them at its place in document order, whatever its type and also WHILE type is button — a link button too, since the element is one kind of control — and being listed SHALL send nothing: a Button adds to a submission only what BTN-31 says. IF type is submit or reset and the button has no form WHEN it is activated THE button SHALL emit click and do nothing more, and in debug builds report that a submit or a reset button has no form. - **BTN-30** WHERE the platform has a form element (the web) THE default button of a form SHALL be the first submit button among the form's controls in document order, a Button whose type is submit counted exactly as the platform's own submit button is. WHEN the person presses Enter in a field of the form that submits it implicitly — the platform's own single-line inputs; Tanrei's text field (TXI-3), number field (NMI-20), color field (CLI-19), combobox (CMB-28), one-time-code input (OTC-13) and search (SRC-13), once their own event for that key has not been cancelled; and Tanrei's checkbox, radio button and switch, which emit nothing for the key (CHK-1, RAD-1, SWT-1) — and the default button is a Button, THE button SHALL act as if it had been activated: click emitted exactly once, and then, unless the product cancelled it, the submission of BTN-27 with that button named in it (BTN-31); it SHALL NOT show the pressed state for a key pressed elsewhere and SHALL NOT take focus. WHILE the default button is disabled — a Button or the platform's own — THE form SHALL NOT be submitted by Enter in any of those controls, as the platform's own disabled default button prevents it from the platform's own inputs. WHILE the default button is the platform's own, Enter in a Tanrei control SHALL press it as Enter in the platform's own input does: its click, then the submission with its name and value. WHILE the form has no submit button of either kind THE button has no part in it: the field and the platform do as they do without one. THE button SHALL draw a form's default button no differently from any other: its emphasis is its variant's. - **BTN-31** WHEN a Button submits its form (BTN-27, BTN-30) THE submission SHALL carry the pair of that button's name and value — once, at most, and only WHILE its name is not empty; an empty value is sent as an empty value — and SHALL carry nothing of any other Button; WHEN the form is submitted by other means (another button, a script's own request) it SHALL carry nothing of this one. THE submit event SHALL name as its submitter a submit button of the platform's own that holds the same name and value and lasts no longer than the event's dispatch, because the platform lets only its own buttons be a submitter: a product reads which button was pressed from that name and value, or from click, and SHALL NOT expect the submitter to be the Tanrei element. THE button SHALL NOT override where or how its form is sent: the address, the method, the encoding, the target and whether the form is validated are the form's alone. - **BTN-32** WHILE disabled is true THE button SHALL submit and reset nothing by any means — a press, a key, assistive technology or a script's click — SHALL add nothing to a submission, and SHALL still be counted as its form's default button where it is the first submit button (BTN-30), so that a form whose button is disabled is not sent by Enter behind it. WHERE the platform has a form element (the web), WHILE the button is not a link and stands in a group of controls the page has disabled as a whole (a disabled fieldset) THE button SHALL be disabled exactly as BTN-2 and BTN-6 say, whatever its type, and SHALL be enabled again at once when the group is; a link button SHALL NOT be disabled by it, as no link of the platform is. - **BTN-33** WHILE toggle is true THE button SHALL ignore a type of submit or reset and stay the toggle BTN-14 describes, and in debug builds SHALL report that a toggle cannot submit or reset a form: a press that switches a state is not one that sends it. WHILE the button is a link (BTN-22) THE button SHALL ignore a type of submit or reset and stay the link, and in debug builds SHALL report that a link cannot submit or reset a form: it goes somewhere, and what a form sends on the way is the form's own action. WHEN type names a value the button does not define THE button SHALL behave as button and submit nothing — where the platform's own button would submit for an unknown type — and in debug builds report the unknown value. WHILE type is button THE button SHALL send nothing of its name or its value and ignore the web's form, without a report: they do no harm on a button that sends nothing, and its value stays what a component that places it reads (BTN-44). - **BTN-34** WHERE the platform has no form element (SwiftUI, Compose, Flutter, React Native) THE button SHALL have no type, no form and no name, and SHALL send its value nowhere — it stays what a component that places the button reads (BTN-44): there a product calls one function of its own from the button's click and from a field's action (TXI-3), and nothing of Tanrei's joins the two or decides which button a key in a field presses. - **BTN-36** WHILE busy is true THE button SHALL draw its container, outline, elevation and opacity from its enabled tokens (of its variant and, for a toggle, of its selection, or of its destructive parts, BTN-40), SHALL keep its label and icon in place without drawing them so that its width and height do not change, and SHALL draw at the centre of the container the loading indicator's arc (LDG-1; under reduced motion LDG-4's whole circle, its opacity easing once per cycle) in a box of the button's icon size (icon.size-without-label where it is icon-only), comp.button.busy.indicator.thickness thick, in the label color of its variant (the icon color where it is icon-only), turning once per comp.button.motion.busy-cycle-duration. It SHALL show neither the hovered nor the pressed state, and SHALL show the focused one. WHEN busy becomes true THE button SHALL fade its label and icon out, and WHEN busy becomes false SHALL fade them back in, over comp.button.motion.busy-fade-duration on comp.button.motion.state-easing (sys.motion.role.state.compact and sys.motion.easing.state), a change of opacity alone in which nothing changes place or size, turned round from the opacity then drawn where busy changes again during it (MOT-2); the arc SHALL appear and go at once, and what it exposes to assistive technology (BTN-37) SHALL change at once, not at the end of the fade, its name staying as it was throughout. WHERE motion is reduced THE button SHALL draw its label and icon, or stop drawing them, at once. - **BTN-37** WHILE busy is true THE button SHALL keep its focus and its place in the focus order, SHALL NOT emit click or change, and SHALL submit, reset and open nothing by any means (a press, a key, assistive technology or a script's click); where it is its form's default button it SHALL stop Enter in a field of the form from submitting it, as a disabled default button does (BTN-30, BTN-32), so that a form is not sent twice. It SHALL expose to assistive technology that it cannot be activated now (on the web aria-disabled) and busyLabel as its description, read after its name, and WHEN busy becomes true SHALL have busyLabel announced once, politely, without moving focus; nothing SHALL be announced when it ends, because what the action did is the product's to say. WHILE busy is true and busyLabel is empty THE button SHALL still render and in debug builds report that a busy button does not say so. - **BTN-38** WHILE disabled is true and focusableWhenDisabled is true THE button SHALL be drawn as BTN-6 says and refuse every activation as BTN-2, BTN-25 and BTN-32 say, but SHALL stay in the focus order, take focus from the keyboard and from a pointer, keep focus when it becomes disabled, show its focus indicator, and expose the disabled state to assistive technology while staying focusable (on the web aria-disabled, not the platform's disabled state), so that a person can reach it and learn why it does nothing. It SHALL show neither the hovered nor the pressed state. A link button so disabled is the disabled link of BTN-25, reachable by Tab. WHERE the platform disables a group of controls as a whole (a disabled fieldset on the web) THE button SHALL leave the focus order with the group, whatever focusableWhenDisabled says, as the platform's own controls do. WHILE focusableWhenDisabled is false, disabled keeps its meaning (BTN-2). - **BTN-39** WHILE fullWidth is true and no host lays the button out THE button SHALL take the whole inline size its container gives it, and SHALL keep the height, the paddings, the corners, the outline and the minimum target of its size, variant and state, centring its content in that width — the label and the icon as one row, in the order and at the gap BTN-11 gives them, or an icon-only button's glyph, whatever width says. WHERE that width is narrower than the label THE button SHALL wrap the label, its lines centred, rather than truncate it or draw past its container. WHILE a host lays the button out (a button group, a toolbar, or the actions of a dialog, a side sheet, a popover, a callout or an empty state) THE button SHALL take the width that host gives it and ignore fullWidth: the host's own full width (BGR-17) is how a row of buttons shares one width. - **BTN-40** WHILE destructive is true and toggle is false THE button SHALL render its container, label, icon and outline from the destructive parts of its variant (comp.button.filled.destructive.container.color, and so on for each variant), in each state from the destructive parts of that state, and its elevation, shape and opacity as it would without destructive; WHILE destructive is false it SHALL render from the variant's own parts. In every shipped system the destructive parts are the error color role at the variant's emphasis — filled: the error color with the on-error color on it; tonal: the error container with the on-error-container color on it; elevated, outlined and text: the variant's own container with the label and the icon in the error color, and an outlined button's edge in it too — and disabled they are those of the variant's plain disabled look, so that a disabled destructive button looks like any disabled button of its variant. An icon-only button takes destructive as a labelled button does; a link button ignores it (BTN-43). - **BTN-41** WHILE toggle is true THE button SHALL ignore destructive and render as BTN-15 says, and in debug builds SHALL report that a toggle has no destructive look: a control that switches a state on and off does not delete anything by being pressed. - **BTN-42** THE button SHALL NOT make color the only sign that its action is destructive: WHILE destructive is true it SHALL keep its role, its accessible name, its states and its keyboard behaviour exactly as they are without it, and SHALL expose nothing more to assistive technology on the web, where no role or state says it; WHERE the platform has a destructive role of its own (SwiftUI's ButtonRole.destructive) THE button SHALL be given that role. Its label, or its label prop on an icon-only button, says what it destroys. - **BTN-43** WHILE the button is a link (BTN-22) THE button SHALL ignore destructive and render as the link button of its variant without it, in each state and on a tone a host gives it (BTN-45), and in debug builds SHALL report that a link only leads somewhere and does not itself delete anything: the action that deletes is the one at its destination, and that action carries destructive. - **BTN-44** THE button SHALL hold value as data alone: it SHALL draw nothing of it, expose nothing of it to assistive technology, and change neither its look nor its behaviour with it. The component that places the button reads it to tell which of its Buttons a selection holds (a toolbar group's value and values, TBR-28); WHERE the platform has a form element (the web), a submission the button makes carries it with name (BTN-31). - **BTN-45** WHERE the component that places the button gives it a tone through the internal channel (BTN-10) — the content color of the colored surface it draws the button on (a status callout's, an inverse or status snackbar's), and optionally the color a focus indicator's outer stroke takes on that surface — THE button SHALL draw its plain look in that tone instead of its variant's own colors, at rest and in each state: its label, its icon and its state layer in the tone's color; its container, where its variant draws one at rest (filled, tonal, elevated, and a variant a layer adds), in the tone's color at comp.button.tone.container.opacity, and where its variant draws none (outlined, text) as its variant's own, an outlined button's edge taking the tone's color at that opacity instead; hovered, focused and pressed, that resting container with the tone's color laid over it at the system's state-layer opacity of the state (sys.state.hover-state-layer-opacity, sys.state.focus-state-layer-opacity, sys.state.pressed-state-layer-opacity), as the core rules lay a state over a resting color; disabled, the container (where its variant draws one) in the tone's color at sys.state.disabled-container-opacity and the label and icon at sys.state.disabled-content-opacity; and the outer stroke of its focus indicator in the tone's focus color, or its color where none is given. Its size, shape, paddings, elevation, opacity and answer to a press SHALL be its own, and a toggle and a destructive button SHALL keep their own looks (BTN-15, BTN-40). WHILE no tone is given THE button SHALL be drawn as without this clause. A tone is not part of the button's public surface: no prop, attribute or styling property gives one. - **BTN-46** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE button SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the button is invalid — except those the button owns (aria-pressed, aria-disabled), which it SHALL move and not expose. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE button SHALL take it off that element. WHEN the product sets an aria- attribute the button owns THE button SHALL report it in debug builds. - **BTN-47** WHERE the component that places the button makes it one choice of a single selection through the internal channel (BTN-10) — a member of a toolbar group whose selection is single (TBR-28) — and WHILE toggle is true THE button SHALL expose itself to assistive technology as a radio button, checked while selected and not checked otherwise, with no pressed state, and SHALL keep its looks, its name and its keys as a toggle (BTN-15, BTN-16). WHEN the user activates it while it is not selected it SHALL become selected and emit click and then change, as BTN-14 says; WHEN the user activates it while it is selected it SHALL emit click alone and stay selected, because a choice of one is changed by choosing another. WHILE no component gives it that place THE button SHALL be the toggle BTN-14 describes. - **BTN-48** WHILE size is not set and a container around the button sets a size for what it holds — a button group's size (BGR-26) or a toolbar's (TBR-31), the nearest such container where several do — THE button SHALL be drawn at that size, its height following the system's height ladder as at a size of its own, and at its nearest size where it has none of that name, in the order extra-small, small, medium, large, extra-large, the larger of two as near; a container whose size is not set SHALL pass none. WHILE size is set THE button SHALL be drawn at its own size, whatever a container sets. WHEN the size it takes changes — a container's size set, changed or removed, its own size set or removed, or the button moved into or out of such a container — THE button SHALL be drawn at the size it now takes at once. - **BTN-49** IF the icon set cannot draw a glyph the button shows yet — the glyph of its icon slot, or the mark of a link that opens a new context (BTN-24); its font is still loading or failed to load — THE button SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box at its size so that nothing else moves, SHALL still draw its container and label and expose its name and state, and SHALL show the glyph once the icon set can draw it, without a motion. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.button.…` → `--tanrei-comp-button-…`). #### `tanrei.comp.button` | Token | Type | Value | | --- | --- | --- | | `comp.button.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.button.container.height.small` | `dimension` | `36px` | | `comp.button.container.height.medium` | `dimension` | `40px` | | `comp.button.container.height.large` | `dimension` | `56px` | | `comp.button.container.padding-inline-narrow.small` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button.container.padding-inline-narrow.medium` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button.container.padding-inline-narrow.large` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button.container.width-wide.small` | `dimension` | `40px` | | `comp.button.container.width-wide.medium` | `dimension` | `52px` | | `comp.button.container.width-wide.large` | `dimension` | `72px` | | `comp.button.container.gap.small` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button.container.gap.medium` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button.container.gap.large` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button.container.padding-inline-start.small` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-inline-start.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-inline-start.large` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.button.container.padding-inline-end.small` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-inline-end.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-inline-end.large` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.button.container.padding-inline-start-with-icon.small` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button.container.padding-inline-start-with-icon.medium` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button.container.padding-inline-start-with-icon.large` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-inline-end-with-icon.small` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button.container.padding-inline-end-with-icon.medium` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button.container.padding-inline-end-with-icon.large` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button.container.padding-block.small` | `dimension` | `8px` | | `comp.button.container.padding-block.medium` | `dimension` | `6px` | | `comp.button.container.padding-block.large` | `dimension` | `6px` | | `comp.button.label.typescale.small` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button.label.typescale.large` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button.icon.size.small` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.button.icon.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.button.icon.size.large` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.button.icon.size-without-label.small` | `dimension` | `{tanrei.comp.button.icon.size.small}` | | `comp.button.icon.size-without-label.medium` | `dimension` | `{tanrei.comp.button.icon.size.medium}` | | `comp.button.icon.size-without-label.large` | `dimension` | `{tanrei.comp.button.icon.size.large}` | | `comp.button.outline.width.small` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button.outline.width.medium` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button.outline.width.large` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button.filled.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.button.filled.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button.filled.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.button.filled.icon.color` | `color` | `{tanrei.comp.button.filled.label.color}` | | `comp.button.filled.state-layer.color` | `color` | `{tanrei.comp.button.filled.label.color}` | | `comp.button.filled.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.filled.unselected.container.color` | `color` | `{tanrei.sys.color.surface-container-highest}` | | `comp.button.filled.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.filled.unselected.icon.color` | `color` | `{tanrei.comp.button.filled.unselected.label.color}` | | `comp.button.filled.unselected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.filled.unselected.state-layer.color` | `color` | `{tanrei.comp.button.filled.unselected.label.color}` | | `comp.button.filled.selected.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.button.filled.selected.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.button.filled.selected.icon.color` | `color` | `{tanrei.comp.button.filled.selected.label.color}` | | `comp.button.filled.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.filled.selected.state-layer.color` | `color` | `{tanrei.comp.button.filled.selected.label.color}` | | `comp.button.filled.destructive.container.color` | `color` | `{tanrei.sys.color.error}` | | `comp.button.filled.destructive.label.color` | `color` | `{tanrei.sys.color.on-error}` | | `comp.button.filled.destructive.icon.color` | `color` | `{tanrei.comp.button.filled.destructive.label.color}` | | `comp.button.filled.destructive.outline.color` | `color` | `{tanrei.comp.button.filled.outline.color}` | | `comp.button.filled.destructive.state-layer.color` | `color` | `{tanrei.comp.button.filled.destructive.label.color}` | | `comp.button.tonal.container.color` | `color` | `{tanrei.sys.color.secondary-container}` | | `comp.button.tonal.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button.tonal.label.color` | `color` | `{tanrei.sys.color.on-secondary-container}` | | `comp.button.tonal.icon.color` | `color` | `{tanrei.comp.button.tonal.label.color}` | | `comp.button.tonal.state-layer.color` | `color` | `{tanrei.comp.button.tonal.label.color}` | | `comp.button.tonal.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.tonal.unselected.container.color` | `color` | `{tanrei.sys.color.surface-container-highest}` | | `comp.button.tonal.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.tonal.unselected.icon.color` | `color` | `{tanrei.comp.button.tonal.unselected.label.color}` | | `comp.button.tonal.unselected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.tonal.unselected.state-layer.color` | `color` | `{tanrei.comp.button.tonal.unselected.label.color}` | | `comp.button.tonal.selected.container.color` | `color` | `{tanrei.sys.color.secondary}` | | `comp.button.tonal.selected.label.color` | `color` | `{tanrei.sys.color.on-secondary}` | | `comp.button.tonal.selected.icon.color` | `color` | `{tanrei.comp.button.tonal.selected.label.color}` | | `comp.button.tonal.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.tonal.selected.state-layer.color` | `color` | `{tanrei.comp.button.tonal.selected.label.color}` | | `comp.button.tonal.destructive.container.color` | `color` | `{tanrei.sys.color.error-container}` | | `comp.button.tonal.destructive.label.color` | `color` | `{tanrei.sys.color.on-error-container}` | | `comp.button.tonal.destructive.icon.color` | `color` | `{tanrei.comp.button.tonal.destructive.label.color}` | | `comp.button.tonal.destructive.outline.color` | `color` | `{tanrei.comp.button.tonal.outline.color}` | | `comp.button.tonal.destructive.state-layer.color` | `color` | `{tanrei.comp.button.tonal.destructive.label.color}` | | `comp.button.elevated.container.color` | `color` | `{tanrei.sys.color.surface-container-lowest}` | | `comp.button.elevated.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` | | `comp.button.elevated.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button.elevated.icon.color` | `color` | `{tanrei.comp.button.elevated.label.color}` | | `comp.button.elevated.state-layer.color` | `color` | `{tanrei.comp.button.elevated.label.color}` | | `comp.button.elevated.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.elevated.unselected.container.color` | `color` | `{tanrei.sys.color.surface-container-lowest}` | | `comp.button.elevated.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.elevated.unselected.icon.color` | `color` | `{tanrei.comp.button.elevated.unselected.label.color}` | | `comp.button.elevated.unselected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.elevated.unselected.state-layer.color` | `color` | `{tanrei.comp.button.elevated.unselected.label.color}` | | `comp.button.elevated.selected.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.button.elevated.selected.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.button.elevated.selected.icon.color` | `color` | `{tanrei.comp.button.elevated.selected.label.color}` | | `comp.button.elevated.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.elevated.selected.state-layer.color` | `color` | `{tanrei.comp.button.elevated.selected.label.color}` | | `comp.button.elevated.destructive.container.color` | `color` | `{tanrei.comp.button.elevated.container.color}` | | `comp.button.elevated.destructive.label.color` | `color` | `{tanrei.sys.color.error}` | | `comp.button.elevated.destructive.icon.color` | `color` | `{tanrei.comp.button.elevated.destructive.label.color}` | | `comp.button.elevated.destructive.outline.color` | `color` | `{tanrei.comp.button.elevated.outline.color}` | | `comp.button.elevated.destructive.state-layer.color` | `color` | `{tanrei.comp.button.elevated.destructive.label.color}` | | `comp.button.outlined.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.outlined.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button.outlined.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button.outlined.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.outlined.state-layer.color` | `color` | `{tanrei.comp.button.outlined.label.color}` | | `comp.button.outlined.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button.outlined.unselected.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.outlined.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.outlined.unselected.icon.color` | `color` | `{tanrei.comp.button.outlined.unselected.label.color}` | | `comp.button.outlined.unselected.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button.outlined.unselected.state-layer.color` | `color` | `{tanrei.comp.button.outlined.unselected.label.color}` | | `comp.button.outlined.selected.container.color` | `color` | `{tanrei.sys.color.inverse-surface}` | | `comp.button.outlined.selected.label.color` | `color` | `{tanrei.sys.color.inverse-on-surface}` | | `comp.button.outlined.selected.icon.color` | `color` | `{tanrei.comp.button.outlined.selected.label.color}` | | `comp.button.outlined.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.outlined.selected.state-layer.color` | `color` | `{tanrei.comp.button.outlined.selected.label.color}` | | `comp.button.outlined.destructive.container.color` | `color` | `{tanrei.comp.button.outlined.container.color}` | | `comp.button.outlined.destructive.label.color` | `color` | `{tanrei.sys.color.error}` | | `comp.button.outlined.destructive.icon.color` | `color` | `{tanrei.comp.button.outlined.destructive.label.color}` | | `comp.button.outlined.destructive.outline.color` | `color` | `{tanrei.sys.color.error}` | | `comp.button.outlined.destructive.state-layer.color` | `color` | `{tanrei.comp.button.outlined.destructive.label.color}` | | `comp.button.text.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button.text.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button.text.icon.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.text.state-layer.color` | `color` | `{tanrei.comp.button.text.label.color}` | | `comp.button.text.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.unselected.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.button.text.unselected.icon.color` | `color` | `{tanrei.comp.button.text.unselected.label.color}` | | `comp.button.text.unselected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.unselected.state-layer.color` | `color` | `{tanrei.comp.button.text.unselected.label.color}` | | `comp.button.text.selected.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.selected.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button.text.selected.icon.color` | `color` | `{tanrei.comp.button.text.selected.label.color}` | | `comp.button.text.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button.text.selected.state-layer.color` | `color` | `{tanrei.comp.button.text.selected.label.color}` | | `comp.button.text.destructive.container.color` | `color` | `{tanrei.comp.button.text.container.color}` | | `comp.button.text.destructive.label.color` | `color` | `{tanrei.sys.color.error}` | | `comp.button.text.destructive.icon.color` | `color` | `{tanrei.comp.button.text.destructive.label.color}` | | `comp.button.text.destructive.outline.color` | `color` | `{tanrei.comp.button.text.outline.color}` | | `comp.button.text.destructive.state-layer.color` | `color` | `{tanrei.comp.button.text.destructive.label.color}` | | `comp.button.motion.state-duration.small` | `duration` | `{tanrei.sys.motion.role.state.compact}` | | `comp.button.motion.state-duration.medium` | `duration` | `{tanrei.sys.motion.role.state.default}` | | `comp.button.motion.state-duration.large` | `duration` | `{tanrei.sys.motion.role.state.large}` | | `comp.button.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.button.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` | | `comp.button.motion.busy-cycle-duration` | `duration` | `{tanrei.comp.loading-indicator.motion.cycle-duration}` | | `comp.button.motion.busy-fade-duration` | `duration` | `{tanrei.sys.motion.role.state.compact}` | | `comp.button.busy.indicator.thickness` | `dimension` | `{tanrei.comp.loading-indicator.indicator.thickness.small}` | | `comp.button.tone.container.opacity` | `number` | `{tanrei.sys.state.selected-state-layer-opacity}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.button...` for the variants `filled`, `tonal`, `elevated`, `outlined`, `text`, the states `hovered`, `focused`, `pressed`, `disabled` and the properties `container.color`, `label.color`, `icon.color`, `outline.color`, `state-layer.color`, `container.elevation`, `unselected.container.color`, `unselected.label.color`, `unselected.icon.color`, `unselected.outline.color`, `unselected.state-layer.color`, `selected.container.color`, `selected.label.color`, `selected.icon.color`, `selected.outline.color`, `selected.state-layer.color`, `destructive.container.color`, `destructive.label.color`, `destructive.icon.color`, `destructive.outline.color`, `destructive.state-layer.color`. - `comp.button..` for the states `hovered`, `focused`, `pressed`, `disabled` and the properties `opacity`, `container.shape`. ## Button group > Lays out a few related Buttons in a row or a column, spaced apart or joined into one shape by a divider or a gap, places the completing and the backing-out actions where people expect them, and names the Buttons as a group. - Category: Actions - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/button-group/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/button-group.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/button-group`). - React: `ButtonGroup` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-button-group` | lagging | | SwiftUI | `TanreiButtonGroup` | lagging | | Jetpack Compose | `TanreiButtonGroup` | lagging | | Flutter | `TanreiButtonGroup` | lagging | | React Native | `ButtonGroup` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `group`: The row or column that holds the Buttons. It places and spaces the Buttons, joins them in the connected variant, and names them as a group. It draws nothing of its own but the dividers of a connected group. - `button`: A Tanrei Button placed in the group: icon-only, label-only or both, its icon on either side, a toggle or not. It is drawn from its own tokens and keeps its own states, focus, events and semantics. - `inner-corner` (optional): In the connected variant, a corner of a Button that faces its neighbour. The group sets it. - `outer-corner` (optional): In the connected variant, a corner at an end of the joined shape: the start corners of the first Button and the end corners of the last in a row, the top corners of the first and the bottom corners of the last in a column. The group sets it. - `divider` (optional): In the connected variant under divider, the line on the seam between two Buttons that touch. The group draws it; under gap there is none. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `standard`, `connected` | `"standard"` | `variant` | standard spaces the Buttons apart. connected joins them into one shape with rounded outer ends, by a divider or by a narrow gap (separation), for a closely related set (Bold, Italic, Underline; Previous, Today, Next). | | `orientation` | `enum`: `horizontal`, `vertical` | `"horizontal"` | `orientation` | horizontal lays the Buttons out in one row; vertical stacks them in one column, every Button as wide as the column. The confirming and dismissive Buttons change places with the orientation (BGR-13, BGR-14). | | `separation` | `enum`: `auto`, `divider`, `gap` | `"auto"` | `separation` | How the Buttons of a connected group are joined. divider: they touch, and a line is drawn on each seam. gap: they stand a narrow gap apart, with tighter corners where they face each other. Auto takes comp.button-group.connected.separation, the design system's answer (divider in the default system). Ignored while variant is standard. | | `fullWidth` | `boolean` | `false` | `full-width` | The group fills its container's width and its Buttons share it equally (in a column, each is the container's width). For the actions at the foot of a dialog, a picker or a side sheet. | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | The size of the Buttons it holds, as the Button's size: set on the group, it is the size of every Button in it that sets none of its own (BGR-26). Only a size set on the group is passed down, not this default: a group that sets none leaves each Button at its own default, or at the size a container around the group sets. A Button's own size always wins. A size a design system adds to the Button may be named. | | `label` | `string` | `""` | `label` | The accessible name of the group ("Text style"). Optional: a group of actions that are each named by their own label needs none. | ### Item: `button` A Button in the group: the button component, placed, spaced and (when connected) given its corners and minimum size by the group, otherwise drawn and behaving as it does anywhere. It is a Button. Names: Web `tanrei-button`, SwiftUI `TanreiButton`, Jetpack Compose `TanreiButton`, Flutter `TanreiButton`, React Native `Button`. | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `filled`, `tonal`, `elevated`, `outlined`, `text` | `"filled"` | `variant` | Its emphasis, as the Button's variant. | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Its height, as the Button's size. To give every Button of a group one size, set the group's size (BGR-26) and none on its Buttons. | | `width` | `enum`: `default`, `narrow`, `wide` | `"default"` | `width` | An icon-only Button's width, as the Button's width. A connected group still widens it to its minimum (BGR-3). | | `icon` | `string` | `""` | — | The glyph in the Button's icon slot, by its name in the system's icon set. Empty for a label-only Button. It is how a fixture fills that slot; in an application the icon slot is filled as the Button's own spec says. | | `iconPosition` | `enum`: `leading`, `trailing` | `"leading"` | `icon-position` | Which side of the label the icon is on, as the Button's iconPosition. | | `label` | `string` | `""` | `label` | Its accessible name, as the Button's label prop. Required for an icon-only Button. | | `toggle` | `boolean` | `false` | `toggle` | As the Button's toggle. | | `selected` | `boolean` | `false` | `selected` | As the Button's selected. | | `disabled` | `boolean` | `false` | `disabled` | As the Button's disabled. | | `destructive` | `boolean` | `false` | `destructive` | As the Button's destructive: the action deletes or discards something a person may not get back (Delete, Discard, Remove member). The group leaves it as set and gives it no look of its own (BGR-19): the Button draws it in the error role at its variant's emphasis (BTN-40). Its label still says what it deletes (BTN-42). | | `confirming` | `boolean` | `false` | — | The Button completes the task (OK, Save, Next, Delete). The group places it at the end of a row and at the top of a column (BGR-13, BGR-14). It changes the Button's place only, never its look (BGR-19). | | `dismissive` | `boolean` | `false` | — | The Button backs out of the task (Cancel, Back, Not now). The group places it at the start of a row and at the bottom of a column (BGR-13, BGR-14). It changes the Button's place only, never its look (BGR-19). | | Event | Description | | --- | --- | | `click` | The Button was activated, as the Button's click. | | `change` | A toggle Button was switched, as the Button's change. | | Slot | Description | | --- | --- | | `label` | Its label, as the Button's default slot. A fixture item's content is this label; an icon-only item has none. | | `icon` | Its glyph, as the Button's icon slot. A fixture fills it through the icon prop. | ### States `enabled` ### Accessibility - Role: `group` - Labeling: label, when given, names the group ("Text style"). Each item is named as it is anywhere: a Button by its label text, an icon-only Button by its label prop. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves focus to each enabled item in turn in the placed order (BGR-15): start to end in a row, top to bottom in a column. | | Enter or Space | Activates the focused item, as the Button itself says (a toggle switches). | - A button group is a layout of actions: each item is its own Tab stop with its own semantics. A row that should be one Tab stop with arrow keys is a toolbar; one choice among several is a single-selection control: tabs where it changes the content below, a radio group where it sets a value, or a segmented button in a system that ships one. - A toggle Button in a group keeps its own on/off state; the group does not make its toggles exclusive. One choice among several is a single-selection control: tabs where it changes the content below, a radio group where it sets a value, or a segmented button in a system that ships one. - confirming and dismissive are not announced: they decide where a Button is, and focus and reading follow that place, so a screen-reader user meets the actions in the same order a sighted user sees them. - The two flags describe the task, not the tone: in "Cancel · Delete" Delete is confirming. A destructive action is told apart by its own look (the Button's destructive) and its label, not by its place. - Compose has no group role: the group is a traversal group whose content description is label, and each item keeps its own role. - Text size: Buttons in a group grow as they do anywhere; a connected row stretches every item to the tallest, and a column makes every item as wide as the widest. - A divider is decoration: it is not exposed, takes no press and is no boundary a person must find. What tells two joined Buttons apart for assistive technology is that each is its own button with its own name; for sight, their content and the line or the gap between them. - A seam between a selected and an unselected toggle carries no line: the fill of the selected item ends there, at a contrast far above 3:1 against its neighbour, and that edge is the boundary. The selected state itself is exposed by the toggle (BTN-14), never by the line. - In the default system the outline of an outlined group and its rules are the hairline (the divider's color), far below 3:1 against the surface. That is within WCAG 1.4.11: each Button is identified by its label or its icon, not by its edge. ### Behaviour Requirements in EARS form, each with its stable id. - **BGR-1** WHILE orientation is horizontal THE button group SHALL lay out its items in one row, in the order BGR-13 gives, each at its own size and width unless fullWidth is true (BGR-17): WHILE variant is standard comp.button-group.standard.gap apart and centred on the row's middle; WHILE variant is connected joined as its separation names (BGR-21) — comp.button-group.connected.gap apart under gap, touching under divider — and each stretched to the height of the tallest item (a Button's height is a minimum), so that the joined shape stays even when a label wraps or text is enlarged. - **BGR-2** WHILE variant is connected and orientation is horizontal THE button group SHALL give the start corners of the first item and the end corners of the last the radius comp.button-group.connected.horizontal.outer-shape, and each corner that faces a neighbouring item the radius comp.button-group.connected.inner-shape WHILE its separation is gap and no radius, a square corner, WHILE its separation is divider (BGR-21), each capped at half the item's height and eased by sys.shape.corner-smoothing; the item's fill, outline, state layer, ripple and focus ring SHALL follow the resulting shape. WHILE variant is standard THE button group SHALL leave every corner of every item as the item draws it. - **BGR-3** WHILE variant is connected THE button group SHALL make each item at least sys.target.touch for touch input and sys.target.pointer for fine pointers along the direction in which it meets its neighbours — wide in a row, high in a column — because joined items cannot extend a hit area over each other: an icon-only Button narrower than that widens its container around its centred icon, and a Button lower than that in a column grows its container around its centred content. Across the other direction the items SHALL extend their hit areas as BTN-5 says. A platform that cannot tell the input type SHALL use sys.target.touch. - **BGR-4** WHILE variant is standard and the hit areas that two neighbouring items extend (BTN-5) overlap THE button group SHALL give every press on an item's visible bounds to that item, and a press in the gap between two items to the nearer one, so that neighbouring hit areas meet at the middle of the gap. comp.button-group.standard.gap is what keeps each item's target whole there: at sys.target.touch minus an item's width (in a row) or height (in a column) or more, no hit areas overlap and every item keeps its full target between its neighbours, as the default system's gap does for every Button size; a layer that narrows the gap narrows the targets between items. - **BGR-5** THE button group SHALL NOT restyle its items beyond BGR-2, BGR-3, BGR-12, BGR-16, BGR-17, BGR-22 and BGR-23: each item SHALL render from its own tokens, answer hover, focus and press itself, switch itself WHILE its toggle is true, emit its own events, keep its own semantics and be its own Tab stop in the order BGR-15 gives; the group itself SHALL NOT take focus, SHALL NOT handle arrow keys and SHALL keep no selection of its own. - **BGR-6** WHILE label is not empty THE button group SHALL expose itself to assistive technology as a group named by label that contains its items; WHILE label is empty THE button group SHALL expose no element of its own, only its items, unless the product names it (BGR-25). - **BGR-7** WHERE orientation is horizontal, fullWidth is false and the row is wider than the space its layout gives it THE button group SHALL narrow its labelled Buttons in proportion to their widths, down to the width of their longest word, letting their labels wrap as a Button's label does when its layout gives it less width, and SHALL keep icon-only Buttons at their width; it SHALL NOT wrap the row onto a second line or scroll it, and in debug builds SHALL report a row that still does not fit. - **BGR-8** WHEN the layout direction is right-to-left THE button group SHALL, in a row, put its start at the right — the dismissive items at the right and the confirming items at the left (BGR-13), the first placed item's outer corners on its right — and mirror which corners are inner corners; in a column it SHALL keep the top-to-bottom order of BGR-14. Each item's content SHALL follow the layout direction as the Button's does. - **BGR-9** WHEN variant, orientation or separation names a value the button group does not define THE button group SHALL render with that prop's default (standard, horizontal, auto), and in debug builds report the unknown value. - **BGR-10** WHILE the group holds fewer than two items, or content that is not a Tanrei Button, THE button group SHALL still render it, a single item keeping every corner as it draws it, and in debug builds report it; a platform that cannot inspect its content SHALL state the rule in its README and docs page. - **BGR-11** WHEN an item becomes disabled, is added or is removed, or its confirming or dismissive changes, THE button group SHALL place its items again by BGR-13 and BGR-14 and recompute which corners are inner and outer corners, where its dividers are (BGR-24) and which items carry the outer padding of BGR-23, at once, without animation; a disabled item SHALL keep its place, its gap or its dividers, and its corners, and an item that has focus while it moves SHALL keep it. - **BGR-12** WHILE orientation is vertical THE button group SHALL lay out its items in one column, top to bottom in the order BGR-14 gives, comp.button-group.standard.gap apart WHILE variant is standard and, WHILE variant is connected, comp.button-group.connected.gap apart under gap and touching under divider (BGR-21), and SHALL make every item as wide as the column — the widest item's width, or the container's width WHILE fullWidth is true — its content centred as a Button centres it in a wider container. WHERE the column is given less width than its widest item every item SHALL take that width and its label SHALL wrap as BGR-7 says; the column SHALL NOT scroll. - **BGR-13** WHILE orientation is horizontal THE button group SHALL place its items from start to end in three runs: first the items whose dismissive is true, then the items with neither flag, then the items whose confirming is true; within each run the items SHALL keep the order they were given in. The start is the left in a left-to-right layout and the right in a right-to-left one (BGR-8). - **BGR-14** WHILE orientation is vertical THE button group SHALL place its items from top to bottom in three runs: first the items whose confirming is true, then the items with neither flag, then the items whose dismissive is true; within each run the items SHALL keep the order they were given in, the first on top, in either layout direction. - **BGR-15** THE button group SHALL make the focus order, and the order in which assistive technology reads its items, the placed order of BGR-13 and BGR-14 — start to end in a row, top to bottom in a column — whatever order the items were given in; a platform whose visual reordering the focus order does not follow (the web's CSS order) SHALL reorder the items themselves in the tree that focus and assistive technology walk. - **BGR-16** WHILE variant is connected and orientation is vertical THE button group SHALL give the top corners of the first item and the bottom corners of the last the radius comp.button-group.connected.vertical.outer-shape, and every other corner of every item comp.button-group.connected.inner-shape WHILE its separation is gap and no radius, a square corner, WHILE its separation is divider (BGR-21), each capped at half the item's height and eased by sys.shape.corner-smoothing; the item's fill, outline, state layer, ripple and focus ring SHALL follow the resulting shape. - **BGR-17** WHILE fullWidth is true and orientation is horizontal THE button group SHALL take the whole width its container gives it and divide it, less the gaps (none under divider), into equal shares, one per item, whatever each item holds: a label shorter than its share SHALL be centred in it, a label longer SHALL wrap as BGR-7 says, and an icon-only Button SHALL widen its container around its centred icon. WHERE a share is narrower than an item's minimum width (BGR-3, or an icon-only Button's own width) THE button group SHALL give that item its minimum, share the rest equally among the others, and in debug builds report it. WHILE fullWidth is false THE button group SHALL take its natural width. - **BGR-18** IF an item's confirming and dismissive are both true THE button group SHALL place it among the items with neither flag and in debug builds report it. - **BGR-19** THE button group SHALL NOT change an item's look, emphasis or semantics for its confirming or dismissive: the flags decide its place only. A destructive confirming action (Delete) takes its look from its own variant and its own destructive (BTN-40), and a Button is not made filled, or destructive, by being confirming. - **BGR-20** THE button group SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the button group is shown THE button group SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows and its state. - **BGR-21** WHILE variant is connected THE button group SHALL join its items as its separation names: WHILE separation is auto, as comp.button-group.connected.separation names, which follows sys.behavior.separation unless a design system sets it apart; WHILE separation is divider or gap, as that value names, whatever the tokens say. Under gap the items SHALL stand comp.button-group.connected.gap apart with nothing drawn between them and the inner corners of BGR-2 and BGR-16; under divider the items SHALL touch, with square inner corners and the divider of BGR-22 on each seam. WHILE variant is standard THE button group SHALL ignore separation and space its items by comp.button-group.standard.gap. WHEN separation, or the token it follows, changes THE button group SHALL draw the other form at once, without animation, keeping the order, the focus and the state of its items. A platform that cannot draw a choice SHALL fall back to the first value, divider, and state that in its README. - **BGR-22** WHILE variant is connected and its separation is divider THE button group SHALL draw, on each seam between two neighbouring items that BGR-24 says carries one, a line comp.button-group.connected.divider.thickness thick, in the color BGR-24 names (comp.button-group.connected.divider.color, or comp.button-group.connected.divider.on-fill.color between two emphasis fills), centred on the seam, over the items' fills and state layers, running along the seam — top to bottom in a row, start to end in a column — and stopping comp.button-group.connected.divider.inset short of each end of it. The line SHALL take no space of its own, SHALL NOT take a press (a press on it goes to the item under the point), SHALL NOT be exposed to assistive technology and SHALL keep its color whatever state its neighbours are in. Each item SHALL draw neither its outline nor the ring of its elevation along an edge that meets a seam, whether or not a line is drawn on it, so that the divider is the only line a seam can carry and the outline of an outlined group runs once around the joined shape, in the color of its rules in the default system; an item's state layer, ripple and focus ring SHALL still follow that item's own shape. - **BGR-23** WHILE variant is connected and orientation is horizontal THE button group SHALL add comp.button-group.connected.horizontal.outer-inset to the inline padding of the first item at its start and of the last item at its end, under either separation, so that content beside a rounded outer end looks as far from it as from the tighter corner on its other side: a labelled Button SHALL be wider by that amount with its content moved inward by it, and an icon-only Button SHALL be wider by that amount with its glyph centred in what is left, half of it nearer its neighbour. A single item (BGR-10) SHALL get none; a column SHALL add none, its ends not being full (BGR-16); WHILE fullWidth is true the shares of BGR-17 SHALL be divided first and the padding taken inside the end items' shares. In a right-to-left layout the start is the right, as BGR-8 says. - **BGR-24** WHILE variant is connected and its separation is divider THE button group SHALL draw the line of BGR-22 on a seam only WHILE the two items it joins rest on the same fill: the colors from which they render their containers at rest — comp.button.outlined.container.color for an outlined Button, and so on for each variant, and for a toggle the selected or the unselected part of its variant (BTN-15) — are the same color in the active scheme, two containers that have no fill counting as the same. WHILE the two fills differ (a selected toggle beside an unselected one, a filled Button beside an outlined one) THE button group SHALL draw no line on that seam, because the edge of the fill already marks it, and the two items SHALL still draw neither outline nor elevation ring along it (BGR-22). A toggle of the text variant has no fill, selected or not, so its seams keep their lines. THE button group SHALL draw the line in comp.button-group.connected.divider.color, and in comp.button-group.connected.divider.on-fill.color WHILE both items rest on an emphasis fill: a filled Button that is not a toggle, or a selected toggle of the filled, tonal, elevated or outlined variant. It SHALL compare the fills the items have at rest: hover, focus and press SHALL neither add nor remove a line nor change its color, and a disabled item SHALL be compared by the look it has when enabled, so that disabling an item moves no line (BGR-11). WHEN an item's selected, toggle or variant changes THE button group SHALL change the lines beside it over comp.button-group.motion.state-duration on comp.button-group.motion.state-easing (sys.motion.role.state.default and sys.motion.easing.state): a line that a seam comes to carry SHALL fade in, a line it stops carrying SHALL fade out, and a line that changes color SHALL fade from the one color to the other, a change of opacity and color alone in which nothing changes place or size, turned round from what is drawn where it changes again during it (MOT-2). Which seams carry a line SHALL be decided at once, and the item's selected state and what it exposes to assistive technology SHALL change at once, not at the end of the motion. WHERE motion is reduced THE button group SHALL draw the lines as they rest at once, as it SHALL in the frames in which it is first drawn (MOT-3) and WHEN its items are placed again (BGR-11) or joined in the other form (BGR-21). - **BGR-25** WHERE the platform has ARIA attributes (the web), the host carries its group role (BGR-6) itself, so what the product writes on it is not moved, but for a name: WHILE label is not empty THE button group SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that label is its whole name although the platform gives aria-labelledby the precedence, and WHEN label is emptied SHALL give them back as they were written; WHILE label is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name. WHILE label is empty and the product names it so THE button group SHALL be exposed as a group named by that name, as with a label: a group the product names is a named group, and a name on an element with no role would name nothing. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE button group SHALL take it away. - **BGR-26** WHILE size is set THE button group SHALL give it to every Button it holds that sets no size of its own, which is then drawn at it (BTN-48), and a Button that sets its own SHALL keep it; WHILE size is not set THE button group SHALL give none, so that each Button is drawn at its own default, or at the size a container around the group sets: only a size set on a container is passed down. WHEN size is set, changed or removed THE button group SHALL have its Buttons drawn at the size they now take at once. A size the Button does not have SHALL be drawn as BTN-7 says. THE button group SHALL draw nothing of its own by its size: its gaps, corners, dividers and outer padding stay those of its variant and separation, around Buttons of the height they are drawn at. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.button-group.…` → `--tanrei-comp-button-group-…`). #### `tanrei.comp.button-group` | Token | Type | Value | | --- | --- | --- | | `comp.button-group.standard.gap` | `dimension` | `0px` | | `comp.button-group.connected.separation` | `number` | `{tanrei.sys.behavior.separation}` | | `comp.button-group.connected.divider.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button-group.connected.divider.on-fill.color` | `color` | `{tanrei.sys.color.outline}` | | `comp.button-group.connected.divider.thickness` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button-group.connected.divider.inset` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-group.connected.gap` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.button-group.connected.inner-shape` | `dimension` | `{tanrei.sys.shape.corner.small}` | | `comp.button-group.connected.horizontal.outer-shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.button-group.connected.horizontal.outer-inset` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button-group.connected.vertical.outer-shape` | `dimension` | `{tanrei.sys.shape.corner.large}` | | `comp.button-group.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` | | `comp.button-group.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | ## Button with menu > Performs a main action with one press, and reveals more options for it in a menu from a second button joined to it. - Category: Actions - Level: composed - Listing: default - Built from: Menu - Page: https://tanrei.chnotchy.com/components/button-with-menu/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/button-with-menu.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/button-with-menu`). - React: `ButtonWithMenu` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-button-with-menu` | lagging | | SwiftUI | `TanreiButtonWithMenu` | planned | | Jetpack Compose | `TanreiButtonWithMenu` | planned | | Flutter | `TanreiButtonWithMenu` | planned | | React Native | `ButtonWithMenu` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `destructive` (prop) | `destructive` | `role` | `destructive` | `isDestructiveAction` | `destructive` | | `label` (prop) | `label` | `title` | `text` | `label` | `label` | | `menuLabel` (prop) | `menuLabel` | `menuLabel` | `menuContentDescription` | `menuSemanticLabel` | `menuAccessibilityLabel` | | `open` (prop) | `open` | `isMenuPresented` | `menuExpanded` | `menuController` | `menuVisible` | | `disabled` (prop) | `disabled` | `disabled` | `enabled` | `onPressed` | `disabled` | | `busyLabel` (prop) | `busyLabel` | `busyLabel` | `busyLabel` | `busySemanticLabel` | `busyLabel` | | `hoverOpen` (prop) | `hoverOpen` | `opensOnHover` | `openOnHover` | `openOnHover` | `hoverOpen` | | `hoverDelay` (prop) | `hoverDelay` | `hoverDelay` | `hoverDelayMillis` | `hoverDelay` | `hoverDelay` | | `click` (event) | `click` | `action` | `onClick` | `onPressed` | `onPress` | | `toggle` (event) | `toggle` | `isMenuPresented` | `onMenuExpandedChange` | `onMenuToggle` | `onMenuToggle` | | `close` (event) | `close` | `isMenuPresented` | `onMenuDismissRequest` | `onMenuClose` | `onMenuDismiss` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `leading`: The leading half: a button that performs the main action. It holds the optional icon and the label, and carries its own hover, focus and press. - `trailing`: The trailing half: a button that opens and closes the menu of more options. It holds the chevron and carries its own hover, focus and press, at its default width or a narrow one. With hoverOpen on, a fine pointer resting on it opens the menu too. - `container`: Each half's shape: its fill, outline, elevation and corners. The halves share one look (the destructive one too, SPB-34) and are joined by a divider or by a narrow gap (separation): round outer ends, and under gap tighter corners where they face each other. The trailing half keeps its shape while the menu is open in the default system. - `icon` (optional): A glyph before the label in the leading half, drawn in the label color; the padding on its side is a step tighter than without it, as Button's. - `label`: The leading half's text and its accessible name. - `chevron`: The trailing half's glyph. By default it is the icon set's expand_more, turned half a turn while the menu is open. The chevron slot replaces it, and the chevron-open slot gives the trailing half a different glyph while the menu is open. - `divider` (optional): Under divider, the line on the seam where the two halves touch. Under gap there is none. - `menu`: The Tanrei Menu the trailing half opens, anchored to the whole button with menu. It keeps its own tokens and behaviour. - `focus-ring`: Gap-then-ring indicator shown for keyboard focus, around whichever half has it. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `filled`, `tonal`, `elevated`, `outlined` | `"filled"` | `variant` | Emphasis, as Button's variants of the same names. A design system may add values. | | `destructive` | `boolean` | `false` | `destructive` | Marks a main action that deletes or discards something a person may not get back (Delete, with Delete all in the menu): both halves keep their variant's emphasis and take the error role's color in it, as a destructive Button of the same variant does (SPB-34). Use it for that kind of action alone, never for emphasis. It adds a color, not a meaning: the label still says what the action does (SPB-35). The menu's items are not marked by it: an item that deletes carries its own destructive. | | `size` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | Visual height: comp.button-with-menu.container.height.\, matching Button's heights and never drawn below sys.target.minimum (36 / 40 / 56 under the default system, the small one held at the minimum). The hit area always meets the minimum target. While it is not set the button with menu is drawn at the size its nearest container sets — a toolbar's size (SPB-37) — and at medium where none does. A design system may add values. | | `separation` | `enum`: `auto`, `divider`, `gap` | `"auto"` | `separation` | How the two halves are joined. divider: they touch, and a line is drawn on the seam. gap: they stand a narrow gap apart, with tighter corners where they face each other. Auto takes comp.button-with-menu.container.separation, the design system's answer (divider in the default system). The halves always sit side by side: there is no vertical form. | | `trailingWidth` | `enum`: `default`, `narrow` | `"default"` | `trailing-width` | How wide the trailing half is. default holds the chevron in a square of the height (36 / 40 / 56 under the default system); narrow makes the half a slim handle on the main action: the chevron with a small inset on each side, and the padding at the rounded outer end (32 / 36 / 36), as the default width takes it too. The hit area meets the minimum target at both. | | `fullWidth` | `boolean` | `false` | `full-width` | Makes the button with menu take the whole width its container gives it, at the height of its size (SPB-38): the leading half takes the extra width, its content centred as a full-width Button's is, and the trailing half keeps the width trailingWidth gives it. For a form's only action on a narrow screen, the action at the foot of a card or a sheet. Ignored while a toolbar lays the button with menu out, which gives it a width of its own. | | `label` | `string` | `""` | `label` | The leading half's visible text and accessible name ("Save"). Required. | | `menuLabel` | `string` | `""` | `menu-label` | The trailing half's accessible name ("More save options"). Required: the chevron alone is not a name. | | `open` | `boolean` | `false` | `open` | Whether the menu is shown. Where open is a plain value (web, Compose, React Native) the product sets it from toggle and sets it to false from close; where it is a binding or a controller (SwiftUI, Flutter) the button with menu opens and closes the menu through it (SPB-2, SPB-16). | | `disabled` | `boolean` | `false` | `disabled` | Prevents interaction with both halves and removes them from the focus order. | | `busy` | `boolean` | `false` | `busy` | The main action it started is under way: the leading half keeps its focus, its place in the focus order and its size, draws the loading indicator's arc in place of its label and icon, refuses every activation, and tells assistive technology through busyLabel, as a busy Button does (SPB-39, SPB-40). The trailing half and its menu stay as they are, so the related actions are still one press away. For a save or a send that takes a moment; it is not disabled, so focus stays where the person left it. | | `busyLabel` | `string` | `""` | `busy-label` | What assistive technology is told while the button with menu is busy ("Saving"): announced once when it becomes busy and read after the leading half's name while it is. Tanrei ships no words of its own. Required while busy is true; ignored otherwise. | | `hoverOpen` | `boolean` | `false` | `hover-open` | Also opens the menu when a fine pointer rests on the trailing half for hoverDelay, and closes that menu when the pointer leaves the trailing half and the menu (SPB-22 to SPB-25). A press and the keyboard still open it as without. Never applies to touch. | | `hoverDelay` | `number` | — | `hover-delay` | How long, in milliseconds, a fine pointer rests on the trailing half before the menu opens on hover. Null takes comp.button-with-menu.motion.hover-open-delay. Ignored unless hoverOpen is true. | ### Events | Event | Description | | --- | --- | | `click` | The leading half was activated by pointer, touch, keyboard or assistive technology. | | `toggle` | The trailing half asks to open or close the menu: by a press or a key on it (SPB-2), or, with hoverOpen on, by a fine pointer resting on it or leaving it and the menu (SPB-22, SPB-23). Carries the open value it asks for. | | `close` | The menu asks to be closed; carries the menu's reason: escape, back, outside, tab, focus-out, item or anchor-hidden (in the platform's casing); anchor-hidden when the button with menu is no longer drawn while its menu is open (MNU-65). | ### Slots | Slot | Description | | --- | --- | | `icon` | The leading half's icon (a glyph of the system's icon set). | | `chevron` | The trailing half's glyph in place of expand_more (one glyph of the system's icon set). Alone, it is turned half a turn while the menu is open, as the default is; with chevron-open it is the closed form only (SPB-21). | | `chevron-open` | The trailing half's glyph while the menu is open (one glyph of the system's icon set). When it is filled, the trailing half cross-fades between the closed glyph and this one instead of turning (SPB-21). | | `menu` | The menu's content: the menu's own item kinds (item, checkbox-item, radio-item and group, as the menu spec defines them), which the button with menu presents in a Tanrei Menu. Fixtures cannot fill it (SPB-15). | ### States `enabled`, `disabled`, `hovered`, `focused`, `pressed`, `loading` ### Accessibility - Role: `button` - Labeling: The leading half is named by label, the trailing half by menuLabel, which should say what more the menu offers ("More save options"). The trailing half exposes that it opens a menu and whether it is open (aria-haspopup and aria-expanded on the web), however it opened. The icon and the chevron, whether the default or a slot's glyph, are decorative. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves focus to the leading half, then to the trailing half. | | Enter or Space on the leading half | Performs the main action (click). | | Enter, Space or Down Arrow on the trailing half | Opens the menu (Enter and Space also close it); focus moves to the first enabled item. On a menu that opened on hover, keeps it open and moves focus to its first enabled item. | | Escape (in the menu) | Closes the menu and returns focus to the trailing half. | | Escape (a menu that opened on hover) | Closes the menu wherever focus is, and leaves focus where it was. | - Two buttons, two Tab stops: the trailing half is a menu button in the WAI-ARIA sense, and the menu is the Tanrei Menu with its own keyboard (MNU-7). - The menu's items are the menu's own item kinds; their events (an item's click, a checkbox item's change, a group's change) are the menu's, and reach the product as they do from a menu anywhere. - Opening on hover is an addition for fine pointers, never a replacement: every menu that hover opens can also be opened by a press and by the keyboard, and keyboard and screen reader use is unchanged. It meets WCAG 1.4.13: the pointer can move onto the menu (the close delay), Escape dismisses it without moving the pointer, and it stays until the pointer leaves or the person dismisses it. It does not take focus, so a person typing elsewhere is not interrupted. - Text must remain readable at 200% text size: both halves grow in height together and the label never truncates. - How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves. - The divider is decoration: it is not exposed and takes no press. The two halves are two buttons whether a line or a gap is between them. - A narrow trailing half is drawn narrower than the minimum target; its hit area is not (SPB-6). Its target reaches outward past the end edge, so leave room for it there. - In the default system the outline of the outlined variant, and the divider of the outlined, tonal and elevated variants, are the hairline (the divider's color), far below 3:1 against their ground. That is within WCAG 1.4.11: the leading half is identified by its label, the trailing half by its chevron, and each half answers hover, focus and press on its own shape. The divider of the filled variant keeps the functional outline role, because a hairline cannot be seen on that fill. - destructive adds a color, never a meaning (WCAG 1.4.1, use of color): the error color tells people who see it that the main action deletes or discards something, and nothing tells a screen reader user so but the label. So the label names the action and what it acts on ("Delete project", not "OK"). Disabled, a destructive button with menu looks like any disabled one of its variant: a button that cannot be pressed does nothing. - busy is the leading half's, as a busy Button's is: it keeps focus and its place in the focus order, says that it cannot be activated now and what is under way (busyLabel, announced once), and announces nothing when it ends, so the product says what the action did. The trailing half and its menu stay usable, so the related actions are still offered; disable the menu's items that cannot run alongside the action. ### Behaviour Requirements in EARS form, each with its stable id. - **SPB-1** WHEN the user activates the leading half by pointer, touch, Enter or Space THE button with menu SHALL emit click exactly once, and SHALL NOT open or close the menu. - **SPB-2** WHEN the user activates the trailing half by pointer, touch, Enter or Space THE button with menu SHALL emit toggle exactly once with the opposite of open, and WHEN the user presses Down Arrow on the trailing half while open is false it SHALL emit toggle with true; the menu SHALL then open or close through open: through its binding or controller where open is one (SwiftUI, Flutter), and by the product setting open where open is a plain value (web, Compose, React Native). A menu that is open from hover is the exception: activating the trailing half then keeps it open and emits no toggle (SPB-24). - **SPB-3** WHILE disabled is true THE button with menu SHALL NOT emit click, toggle or close, SHALL NOT make either half focusable, SHALL expose the disabled state on both halves and SHALL present no menu, whatever open says; it SHALL NOT open the menu on hover, whatever hoverOpen says. - **SPB-4** WHILE a half is hovered, keyboard-focused or pressed THE button with menu SHALL render that half's container, label, icon or chevron, outline, elevation and opacity from the component tokens of its variant in that half's highest-precedence active state, with precedence pressed over focused over hovered, and SHALL keep the other half at its own state (neither half is hovered or pressed while the pointer or the press is on the other); focus gained by pointer or touch SHALL NOT select the focused state. - **SPB-5** WHEN a half receives keyboard focus THE button with menu SHALL show the focus ring around that half's own shape, without animation; focus gained by pointer or touch SHALL NOT show it. - **SPB-6** WHERE a half is smaller than the minimum target THE button with menu SHALL extend that half's hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers without changing its visual size — above and below, and outward past the button with menu's start edge for the leading half and past its end edge for the trailing half — and toward the other half no further than the middle of the gap between them, or the seam where they touch, so that the two never overlap; a narrow trailing half SHALL reach its target the same way and SHALL NOT be drawn wider for it; a platform that cannot tell the input type SHALL use sys.target.touch. - **SPB-7** WHILE disabled is true THE button with menu SHALL render both halves' containers, label, icon, chevron, outline, elevation and opacity from the disabled component tokens of its variant. A disabled button with menu SHALL draw its closed form (the trailing half's closed shape and the closed chevron: the chevron slot's glyph, or expand_more when that slot is empty, unturned), whatever open says. - **SPB-8** WHEN variant or size names a value that the active design system does not have THE button with menu SHALL render with the default value's tokens, and WHEN separation or trailingWidth names a value it does not define THE button with menu SHALL render with that prop's default (auto, default); in debug builds it SHALL report the unknown value. - **SPB-9** WHEN a half of the button with menu is pressed by pointer, touch, Enter or Space THE half SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. - **SPB-10** WHILE pressed THE half SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, icon, chevron, outline, elevation, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.button-with-menu.motion.feedback-duration with comp.button-with-menu.motion.state-easing, fades over comp.button-with-menu.motion.state-duration with comp.button-with-menu.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **SPB-11** THE half SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. - **SPB-12** THE button with menu SHALL draw its two halves in one row, joined as its separation names (SPB-30): the leading half at least the height of its size (comp.button-with-menu.container.height.medium for medium, and so on) and as wide as its content, holding its icon, when it has one, and then its label, comp.button-with-menu.container.gap.medium apart, padded at the start by comp.button-with-menu.leading.padding-inline-start-with-icon.medium when it has an icon and by comp.button-with-menu.leading.padding-inline-start.medium when it has none, at the end by comp.button-with-menu.leading.padding-inline-end.medium, and above and below by at least comp.button-with-menu.container.padding-block.medium; and the trailing half as tall as the leading half, holding the chevron centred between comp.button-with-menu.trailing.padding-inline.medium on each side WHILE trailingWidth is default and between comp.button-with-menu.trailing.padding-inline-narrow.medium on each side WHILE trailingWidth is narrow (and so on for each size). Each half SHALL then take the outer padding of SPB-32. THE button with menu SHALL NOT stack its halves: it has no vertical form. - **SPB-13** THE button with menu SHALL round the leading half's start corners and the trailing half's end corners by comp.button-with-menu.container.shape, capped at half that half's height (so that the default system's sys.shape.corner.full draws round ends) and eased by sys.shape.corner-smoothing. WHILE its separation is gap it SHALL round the corners where the halves face each other by comp.button-with-menu.container.inner-shape and, WHILE open is true, the trailing half's by comp.button-with-menu.container.inner-shape-open, each capped and eased the same way; WHILE its separation is divider those corners SHALL be square, open or not. WHILE open is true the chevron SHALL show its open form (SPB-21). WHEN open changes THE button with menu SHALL change the chevron, and the trailing half's inner corners where the two tokens differ, over comp.button-with-menu.motion.open-duration with comp.button-with-menu.motion.open-easing, and at once where motion is reduced. THE button with menu SHALL NOT change the shape of a half for any other reason: where comp.button-with-menu.container.inner-shape-open has the value of comp.button-with-menu.container.inner-shape, as in the default system, the trailing half keeps its shape while the menu is open and the chevron alone shows it. Each half SHALL clip its fill, state layer and ripple to its own shape, and draw its outline and its elevation's ring as SPB-26 says. - **SPB-14** THE button with menu SHALL set the label in the text style of its size (comp.button-with-menu.label.typescale.medium, and so on) and the label color of its variant and the leading half's state (comp.button-with-menu.filled.label.color for filled at rest, and so on), SHALL NOT truncate it (it stays on one line while it fits, wraps when the layout gives it less width, and the halves grow in height with it), and SHALL draw the icon and the chevron (expand_more, or a chevron slot's glyph, SPB-21) at the icon size of its size (comp.button-with-menu.icon.size.medium, and so on) through the icon helper, each in the label color of its own half's state, with the family and fill of an unselected icon, sys.icon.weight, and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max. - **SPB-15** WHEN open becomes true THE button with menu SHALL present the items of its menu slot as a Tanrei Menu, which then behaves as MNU-1 to MNU-29 say, anchored to the whole button with menu with placement bottom-end (below it with the end edges aligned, flipping as MNU-2 says), with the trailing half as the element focus returns to when the menu closes: an operated overlay that is not modal, as the menu is; a menu that opens from hover SHALL NOT take focus (SPB-22). WHEN open becomes false THE button with menu SHALL remove the menu. - **SPB-16** WHEN the menu asks to be closed (MNU-5, MNU-6) THE button with menu SHALL emit close once with the menu's reason and SHALL be closed: through its binding or controller where open is one (SwiftUI, Flutter), and by the product setting open to false where open is a plain value (web, Compose, React Native); WHEN an action item of the menu is activated THE button with menu SHALL let the item emit its click first and then emit close with the reason item. A press on the trailing half while the menu is open is not a press outside: it SHALL emit toggle with false (SPB-2), or keep a menu that is open from hover open (SPB-24), and emit no close. - **SPB-17** THE button with menu SHALL expose two buttons in reading order, each its own Tab stop: the leading half named by label, and the trailing half named by menuLabel, exposing that it opens a menu and whether the menu is open where the platform has those properties, however it opened, and WHILE the menu is open which element it is — naming nothing WHILE it is closed, as MNU-24 says; the icon and the chevron (expand_more or a chevron slot's glyph) SHALL be hidden, and the button with menu SHALL expose no element of its own around them. - **SPB-18** THE button with menu SHALL cast the blurred layers of each half's elevation, of its variant and that half's state (comp.button-with-menu.elevated.container.elevation for elevated at rest, and so on), outside that half without clipping them, and draw the elevation's ring inside the half (SPB-26); WHEN the elevation or the colors of a half change between states THE button with menu SHALL animate the change over comp.button-with-menu.motion.state-duration with comp.button-with-menu.motion.state-easing, changing them at once where motion is reduced. - **SPB-19** WHEN the layout direction is right-to-left THE button with menu SHALL put the trailing half on the left, mirror the order of the leading half's icon and label and apply its paddings by logical start and end, SHALL present its menu with the end edges aligned at the left (the menu's left edge on the button with menu's left edge, below the trailing half: SPB-15 and MNU-2), SHALL NOT mirror the chevron expand_more or change the way it turns, SHALL leave a glyph of the icon slot or of a chevron slot to the icon helper (SPB-28), and SHALL grow a ripple from the point of contact as in left-to-right. - **SPB-20** WHILE label is not empty THE button with menu SHALL expose it as the leading half's accessible name, over a name the product gives it on the element (aria-label or aria-labelledby). WHILE label is empty and the product gives the button with menu a name of its own on the element — aria-label, or aria-labelledby naming an element — THE button with menu SHALL expose that name as the leading half's accessible name. WHILE label is empty and the product gives it none, or menuLabel is empty, THE button with menu SHALL still render, and in debug builds report the half that has no accessible name; WHILE the menu slot holds no item THE button with menu SHALL still emit toggle and draw the trailing half's open form, SHALL present no menu, and in debug builds report the empty menu. - **SPB-21** WHILE neither the chevron slot nor the chevron-open slot holds a glyph THE button with menu SHALL draw the icon set's expand_more as the chevron, turned half a turn while open is true; WHILE only the chevron slot holds a glyph THE button with menu SHALL draw that glyph in its place, turned the same way; WHILE the chevron-open slot holds a glyph THE button with menu SHALL draw it unturned while open is true and, while open is false, the chevron slot's glyph (or expand_more when that slot is empty) unturned, and WHEN open changes SHALL cross-fade from one to the other instead of turning. Each slot SHALL hold at most one glyph: the button with menu SHALL draw the first and in debug builds report the rest. - **SPB-22** WHERE hoverOpen is true, WHEN a fine pointer (a mouse, a trackpad, or a pen that hovers) enters the trailing half while open is false and stays on it for hoverDelay milliseconds, or for comp.button-with-menu.motion.hover-open-delay when hoverDelay is null, THE button with menu SHALL emit toggle with true once, and WHEN open then becomes true the menu SHALL be open from hover: THE button with menu SHALL present it without moving focus into it (in place of MNU-1's move to the first item), focus staying where it was, and a pointer on an item SHALL render the item hovered without moving focus to it (in place of MNU-8). The pointer leaving the trailing half before the delay has passed, a press on either half, or open becoming true by other means SHALL cancel the wait. Touch, and pointer events a platform synthesises from touch, SHALL never open the menu on hover. WHERE hoverDelay is negative or not a number THE button with menu SHALL wait for comp.button-with-menu.motion.hover-open-delay, and in debug builds report the value. - **SPB-23** WHILE the menu is open from hover, WHEN the pointer has been off both the trailing half and the menu's surface for comp.button-with-menu.motion.hover-close-delay THE button with menu SHALL emit toggle with false once and SHALL NOT move focus; a pointer that comes back onto either within that time SHALL keep the menu open, and a press outside both SHALL close it as MNU-5 says. WHILE the menu is open for any other reason (a press, a key, or the product setting open) THE button with menu SHALL NOT close it when the pointer leaves. - **SPB-24** WHEN the user activates the trailing half by pointer, touch, Enter, Space or Down Arrow while the menu is open from hover THE button with menu SHALL NOT emit toggle, SHALL keep the menu open and SHALL move focus to its first enabled item as MNU-1 says; from then on the menu SHALL be open as if that activation had opened it: the pointer leaving no longer closes it (SPB-23), MNU-8 applies again, and the next activation of the trailing half emits toggle with false (SPB-2). - **SPB-25** WHILE the menu is open from hover, WHEN the user presses Escape or the platform's back, wherever focus is, THE button with menu SHALL emit close once with the reason escape or back, SHALL be closed as SPB-16 says, SHALL NOT move focus, and SHALL keep that key from reaching anything else, so that what hover showed can be dismissed without moving the pointer (WCAG 1.4.13); a later Escape reaches the page as usual. - **SPB-26** THE button with menu SHALL draw each half's outline (comp.button-with-menu.outline.width.medium wide at the medium size, and so on, in the outline color of its variant and that half's state) and the ring of its elevation (the layer with no offset, no blur and a positive spread, which the default system gives every level above sys.elevation.level0 and which a platform otherwise draws as a border) inside that half's own edge, the outline over the ring. WHILE its separation is gap neither SHALL reach into the comp.button-with-menu.container.inner-gap between the halves, so that the two halves' edges never meet, however narrow that gap is; WHILE its separation is divider each half SHALL draw neither along the edge where the halves touch, so that the outline and the ring run once around the joined shape and the divider (SPB-31) is the only line on the seam. Only the elevation's blurred layers SHALL fall outside a half (SPB-18). - **SPB-27** THE button with menu SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the button with menu is shown THE button with menu SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state and its focus, an open menu placed again by the new direction. - **SPB-28** WHERE the layout direction is right-to-left THE button with menu SHALL draw the glyph of its icon slot and a glyph of its chevron or chevron-open slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and fill nor the order SPB-19 gives. THE button with menu SHALL NOT mirror a glyph itself, and SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name. The chevron it draws itself (expand_more) is not marked and is never mirrored, and a mirrored chevron-slot glyph is turned while open as an unmirrored one is (SPB-21). - **SPB-29** THE button with menu SHALL lay out its label as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE button with menu SHALL still place the label and align its lines by the layout direction, not by the text's own. - **SPB-30** THE button with menu SHALL join its two halves as its separation names: WHILE separation is auto, as comp.button-with-menu.container.separation names, which follows sys.behavior.separation unless a design system sets it apart; WHILE separation is divider or gap, as that value names, whatever the tokens say. Under gap the halves SHALL stand comp.button-with-menu.container.inner-gap apart with nothing drawn between them and the inner corners of SPB-13; under divider the halves SHALL touch, with square inner corners and the divider of SPB-31 on the seam. WHEN separation, or the token it follows, changes THE button with menu SHALL draw the other form at once, without animation, keeping its open state and its focus. A platform that cannot draw a choice SHALL fall back to the first value, divider, and state that in its README. - **SPB-31** WHILE its separation is divider THE button with menu SHALL draw on the seam between its halves one line comp.button-with-menu.divider.thickness thick, in the divider color of its variant (comp.button-with-menu.filled.divider.color for filled at rest, and so on), centred on the seam, over the halves' fills and state layers, from comp.button-with-menu.divider.inset below the top of the seam to the same distance above its bottom. The line SHALL take no space of its own, SHALL NOT take a press (a press on it goes to the half under the point), SHALL NOT be exposed to assistive technology, and SHALL keep its resting color while either half is hovered, focused or pressed; WHILE disabled is true it SHALL take the disabled divider color of its variant. A half's state layer, ripple and focus ring SHALL still follow that half's own shape. - **SPB-32** THE button with menu SHALL add comp.button-with-menu.container.outer-inset to the leading half's start padding, under either separation and at either trailing width, and to the trailing half's end padding, under either separation and at either trailing width, so that content beside a rounded outer end looks as far from it as from the tighter corner on its other side: the leading half SHALL be wider by that amount with its icon and label moved inward by it, and the trailing half SHALL be wider by that amount with its chevron centred in what is left, half of it nearer the leading half. WHILE trailingWidth is narrow THE trailing half SHALL be as wide as the chevron's box, comp.button-with-menu.trailing.padding-inline-narrow.medium on each side of it (of its own size) and the outer padding, with the chevron centred in what is left: a slim half beside a full end needs the compensation as much as a wide one, its chevron being nearer the curve, so it is one outer padding wider than a narrow icon-only Button of its size (BTN-12) where the two components' tokens agree, as in the default system. In a right-to-left layout the start is the right, as SPB-19 says. - **SPB-33** WHERE the component that places the button with menu keeps one Tab stop among its items and makes each half a stop of its own (a toolbar, TBR-25), through the internal channel a Button reads from the component that places it (BTN-10), THE button with menu SHALL let that component say which half, if either, is its Tab stop and move focus to either half, SHALL take the other half out of the Tab order while it does, and SHALL keep each half's own name, role, state, keys and activation. WHILE no component does so THE button with menu SHALL keep both halves in the Tab order, as SPB-17 says. It adds nothing to the public surface: no prop, attribute or styling property says which half is a stop. - **SPB-34** WHILE destructive is true THE button with menu SHALL render both halves' containers, label, icon, chevron and outline, and the divider, from the destructive parts of its variant (comp.button-with-menu.filled.destructive.container.color, and so on for each variant), each half in its own state from the destructive parts of that state, and its elevation, shape and opacity as it would without destructive; WHILE destructive is false it SHALL render from the variant's own parts. In every shipped system the destructive parts are those of a destructive Button of the same variant (BTN-40) — filled: the error color with the on-error color on it; tonal: the error container with the on-error-container color on it; elevated and outlined: the variant's own container with the label, the icon and the chevron in the error color, and an outlined half's edge and divider in it too — and disabled they are those of the variant's plain disabled look, so that a disabled destructive button with menu looks like any disabled button with menu of its variant. THE button with menu SHALL NOT pass destructive to the items of its menu: an item is drawn destructive by its own destructive alone (MNU-18), since an option of the menu may delete where the main action does not, and the reverse. - **SPB-35** THE button with menu SHALL NOT make color the only sign that its main action is destructive: WHILE destructive is true it SHALL keep both halves' roles, accessible names, states and keyboard behaviour exactly as they are without it, and SHALL expose nothing more to assistive technology on the web, where no role or state says it; WHERE the platform has a destructive role of its own (SwiftUI's ButtonRole.destructive) THE button with menu SHALL give it to the leading half, whose press performs the action, and not to the trailing half, which only opens the menu. Its label says what it destroys. - **SPB-36** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE button with menu SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role (the leading half carries them) — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the button with menu is invalid — except those the button with menu owns (aria-haspopup, aria-expanded, aria-controls, aria-disabled), which it SHALL move and not expose. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE button with menu SHALL take it off that element. WHEN the product sets an aria- attribute the button with menu owns THE button with menu SHALL report it in debug builds. - **SPB-37** WHILE size is not set and a container around the button with menu sets a size for what it holds — a toolbar's size (TBR-31), the nearest such container where several do — THE button with menu SHALL draw both halves at that size, their heights following the system's height ladder as at a size of its own, and at its nearest size where it has none of that name, in the order extra-small, small, medium, large, extra-large, the larger of two as near; a container whose size is not set SHALL pass none. WHILE size is set THE button with menu SHALL be drawn at its own size, whatever a container sets. WHEN the size it takes changes — a container's size set, changed or removed, its own size set or removed, or the button with menu moved into or out of such a container — THE button with menu SHALL be drawn at the size it now takes at once. - **SPB-38** WHILE fullWidth is true and no toolbar lays the button with menu out THE button with menu SHALL take the whole inline size its container gives it and SHALL give all of it beyond what the two halves need to the leading half, the trailing half keeping the width trailingWidth gives it (SPB-12, SPB-32), as the leading button of a split button takes the room its trailing button leaves; both halves SHALL keep the height, the paddings, the corners, the outline, the separation and the minimum target of their size, variant and state, and the leading half SHALL centre its content in its own width — the icon and the label as one row, in the order and at the gap SPB-12 gives them — as a full-width Button centres its content (BTN-39). WHERE the leading half is then narrower than the label THE button with menu SHALL wrap the label, its lines centred, rather than truncate it or draw past its container. WHILE a toolbar lays the button with menu out THE button with menu SHALL take the width the toolbar gives it and ignore fullWidth. - **SPB-39** WHILE busy is true and disabled is false THE button with menu SHALL draw its leading half's container, outline, elevation and opacity from its enabled tokens (of its variant, or of its destructive parts, SPB-34), SHALL keep the leading half's label and icon in place without drawing them so that neither half's width or height changes, and SHALL draw at the centre of the leading half the loading indicator's arc (LDG-1; under reduced motion LDG-4's whole circle, its opacity easing once per cycle) in a box of the icon size of its size (comp.button-with-menu.icon.size.medium, and so on), comp.button-with-menu.busy.indicator.thickness thick, in the leading half's label color, turning once per comp.button-with-menu.motion.busy-cycle-duration, as a busy Button draws its own (BTN-36). The leading half SHALL show neither the hovered nor the pressed state, and SHALL show the focused one. WHEN busy becomes true THE button with menu SHALL fade the leading half's label and icon out, and WHEN busy becomes false SHALL fade them back in, over comp.button-with-menu.motion.busy-fade-duration on comp.button-with-menu.motion.state-easing, a change of opacity alone in which nothing changes place or size, turned round from the opacity then drawn where busy changes again during it (MOT-2); the arc SHALL appear and go at once, and what the leading half exposes to assistive technology (SPB-40) SHALL change at once, not at the end of the fade, its name staying as it was throughout. WHERE motion is reduced THE button with menu SHALL draw the label and the icon, or stop drawing them, at once. THE trailing half, its chevron and the divider SHALL be drawn as they are without busy, each half in its own state. - **SPB-40** WHILE busy is true and disabled is false THE button with menu SHALL keep the leading half's focus and its place in the focus order, SHALL NOT emit click by any means (a press, a key, assistive technology or a script's click), SHALL expose on the leading half that it cannot be activated now (on the web aria-disabled) and busyLabel as its description, read after its name, and WHEN busy becomes true SHALL have busyLabel announced once, politely, without moving focus; nothing SHALL be announced when it ends, because what the action did is the product's to say. THE trailing half SHALL keep its name, role, state, focus and keys, and SHALL emit toggle and present its menu as it does without busy (SPB-2, SPB-15, SPB-22), so that the related actions stay one press away. WHILE disabled is true busy SHALL change nothing (SPB-3, SPB-7). WHILE busy is true and busyLabel is empty THE button with menu SHALL still render and in debug builds report that its busy leading half does not say so. - **SPB-41** IF the icon set cannot draw a glyph the button with menu shows yet — the glyph of its icon slot, expand_more, or the glyph of its chevron or chevron-open slot; its font is still loading or failed to load — THE button with menu SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box at its size so that nothing else moves, SHALL still draw both halves and the label and expose their names and states, and SHALL show the glyph once the icon set can draw it, without a motion. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.button-with-menu.…` → `--tanrei-comp-button-with-menu-…`). #### `tanrei.comp.button-with-menu` | Token | Type | Value | | --- | --- | --- | | `comp.button-with-menu.container.separation` | `number` | `{tanrei.sys.behavior.separation}` | | `comp.button-with-menu.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.button-with-menu.container.inner-shape` | `dimension` | `{tanrei.sys.shape.corner.small}` | | `comp.button-with-menu.container.inner-shape-open` | `dimension` | `{tanrei.comp.button-with-menu.container.inner-shape}` | | `comp.button-with-menu.container.inner-gap` | `dimension` | `{tanrei.sys.space.space25}` | | `comp.button-with-menu.container.outer-inset` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button-with-menu.container.height.small` | `dimension` | `36px` | | `comp.button-with-menu.container.height.medium` | `dimension` | `40px` | | `comp.button-with-menu.container.height.large` | `dimension` | `56px` | | `comp.button-with-menu.container.padding-block.small` | `dimension` | `8px` | | `comp.button-with-menu.container.padding-block.medium` | `dimension` | `6px` | | `comp.button-with-menu.container.padding-block.large` | `dimension` | `6px` | | `comp.button-with-menu.container.gap.small` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-with-menu.container.gap.medium` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-with-menu.container.gap.large` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-with-menu.divider.thickness` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button-with-menu.divider.inset` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-with-menu.leading.padding-inline-start.small` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.leading.padding-inline-start.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.leading.padding-inline-start.large` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.button-with-menu.leading.padding-inline-start-with-icon.small` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button-with-menu.leading.padding-inline-start-with-icon.medium` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.button-with-menu.leading.padding-inline-start-with-icon.large` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.leading.padding-inline-end.small` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.leading.padding-inline-end.medium` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.leading.padding-inline-end.large` | `dimension` | `{tanrei.sys.space.space300}` | | `comp.button-with-menu.trailing.padding-inline.small` | `dimension` | `8px` | | `comp.button-with-menu.trailing.padding-inline.medium` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.button-with-menu.trailing.padding-inline.large` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.button-with-menu.trailing.padding-inline-narrow.small` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button-with-menu.trailing.padding-inline-narrow.medium` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button-with-menu.trailing.padding-inline-narrow.large` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.button-with-menu.label.typescale.small` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button-with-menu.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button-with-menu.label.typescale.large` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.button-with-menu.icon.size.small` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.button-with-menu.icon.size.medium` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.button-with-menu.icon.size.large` | `dimension` | `{tanrei.sys.icon.medium}` | | `comp.button-with-menu.outline.width.small` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button-with-menu.outline.width.medium` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button-with-menu.outline.width.large` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.button-with-menu.filled.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.button-with-menu.filled.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button-with-menu.filled.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.button-with-menu.filled.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button-with-menu.filled.divider.color` | `color` | `{tanrei.sys.color.outline}` | | `comp.button-with-menu.filled.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.filled.label.color}` | | `comp.button-with-menu.filled.destructive.container.color` | `color` | `{tanrei.comp.button.filled.destructive.container.color}` | | `comp.button-with-menu.filled.destructive.label.color` | `color` | `{tanrei.comp.button.filled.destructive.label.color}` | | `comp.button-with-menu.filled.destructive.outline.color` | `color` | `{tanrei.comp.button.filled.destructive.outline.color}` | | `comp.button-with-menu.filled.destructive.divider.color` | `color` | `{tanrei.comp.button-with-menu.filled.divider.color}` | | `comp.button-with-menu.filled.destructive.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.filled.destructive.label.color}` | | `comp.button-with-menu.tonal.container.color` | `color` | `{tanrei.sys.color.secondary-container}` | | `comp.button-with-menu.tonal.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button-with-menu.tonal.label.color` | `color` | `{tanrei.sys.color.on-secondary-container}` | | `comp.button-with-menu.tonal.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button-with-menu.tonal.divider.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button-with-menu.tonal.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.tonal.label.color}` | | `comp.button-with-menu.tonal.destructive.container.color` | `color` | `{tanrei.comp.button.tonal.destructive.container.color}` | | `comp.button-with-menu.tonal.destructive.label.color` | `color` | `{tanrei.comp.button.tonal.destructive.label.color}` | | `comp.button-with-menu.tonal.destructive.outline.color` | `color` | `{tanrei.comp.button.tonal.destructive.outline.color}` | | `comp.button-with-menu.tonal.destructive.divider.color` | `color` | `{tanrei.comp.button-with-menu.tonal.divider.color}` | | `comp.button-with-menu.tonal.destructive.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.tonal.destructive.label.color}` | | `comp.button-with-menu.elevated.container.color` | `color` | `{tanrei.sys.color.surface-container-lowest}` | | `comp.button-with-menu.elevated.container.elevation` | `shadow` | `{tanrei.sys.elevation.level2}` | | `comp.button-with-menu.elevated.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button-with-menu.elevated.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button-with-menu.elevated.divider.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button-with-menu.elevated.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.elevated.label.color}` | | `comp.button-with-menu.elevated.destructive.container.color` | `color` | `{tanrei.comp.button.elevated.destructive.container.color}` | | `comp.button-with-menu.elevated.destructive.label.color` | `color` | `{tanrei.comp.button.elevated.destructive.label.color}` | | `comp.button-with-menu.elevated.destructive.outline.color` | `color` | `{tanrei.comp.button.elevated.destructive.outline.color}` | | `comp.button-with-menu.elevated.destructive.divider.color` | `color` | `{tanrei.comp.button-with-menu.elevated.divider.color}` | | `comp.button-with-menu.elevated.destructive.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.elevated.destructive.label.color}` | | `comp.button-with-menu.outlined.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.button-with-menu.outlined.container.elevation` | `shadow` | `{tanrei.sys.elevation.level0}` | | `comp.button-with-menu.outlined.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.button-with-menu.outlined.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.button-with-menu.outlined.divider.color` | `color` | `{tanrei.comp.button-with-menu.outlined.outline.color}` | | `comp.button-with-menu.outlined.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.outlined.label.color}` | | `comp.button-with-menu.outlined.destructive.container.color` | `color` | `{tanrei.comp.button.outlined.destructive.container.color}` | | `comp.button-with-menu.outlined.destructive.label.color` | `color` | `{tanrei.comp.button.outlined.destructive.label.color}` | | `comp.button-with-menu.outlined.destructive.outline.color` | `color` | `{tanrei.comp.button.outlined.destructive.outline.color}` | | `comp.button-with-menu.outlined.destructive.divider.color` | `color` | `{tanrei.comp.button-with-menu.outlined.destructive.outline.color}` | | `comp.button-with-menu.outlined.destructive.state-layer.color` | `color` | `{tanrei.comp.button-with-menu.outlined.destructive.label.color}` | | `comp.button-with-menu.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.default}` | | `comp.button-with-menu.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.button-with-menu.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` | | `comp.button-with-menu.motion.open-duration` | `duration` | `{tanrei.sys.motion.role.appear.anchored.enter}` | | `comp.button-with-menu.motion.open-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.spatial}` | | `comp.button-with-menu.motion.hover-open-delay` | `duration` | `{tanrei.sys.motion.duration.medium2}` | | `comp.button-with-menu.motion.hover-close-delay` | `duration` | `{tanrei.sys.motion.duration.medium2}` | | `comp.button-with-menu.motion.busy-cycle-duration` | `duration` | `{tanrei.comp.button.motion.busy-cycle-duration}` | | `comp.button-with-menu.motion.busy-fade-duration` | `duration` | `{tanrei.comp.button.motion.busy-fade-duration}` | | `comp.button-with-menu.busy.indicator.thickness` | `dimension` | `{tanrei.comp.button.busy.indicator.thickness}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.button-with-menu...` for the variants `filled`, `tonal`, `elevated`, `outlined`, the states `hovered`, `focused`, `pressed`, `disabled` and the properties `container.color`, `container.elevation`, `label.color`, `outline.color`, `divider.color`, `state-layer.color`, `destructive.container.color`, `destructive.label.color`, `destructive.outline.color`, `destructive.divider.color`, `destructive.state-layer.color`. - `comp.button-with-menu..` for the states `hovered`, `focused`, `pressed`, `disabled` and the properties `opacity`, `container.shape`. ## Calendar > Shows one month as a grid of days, in the page or inside a picker, lets a person choose one date or one range of dates from it, and moves from month to month as one column of weeks that follows a scroll and a drag. - Category: Selection - Level: base - Listing: default - Used in: DateTimePicker - Page: https://tanrei.chnotchy.com/components/calendar/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/calendar.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/calendar`). - React: `Calendar` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-calendar` | lagging | | SwiftUI | `TanreiCalendar` | planned | | Jetpack Compose | `TanreiCalendar` | planned | | Flutter | `TanreiCalendar` | planned | | React Native | `Calendar` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `mode` (prop) | `mode` | `range` | `mode` | `mode` | `mode` | | `value` (prop) | `value` | `selection` | `value` | `value` | `value` | | `start` (prop) | `start` | `range` | `start` | `start` | `start` | | `end` (prop) | `end` | `range` | `end` | `end` | `end` | | `min` (prop) | `min` | `minDate` | `min` | `firstDate` | `min` | | `max` (prop) | `max` | `maxDate` | `max` | `lastDate` | `max` | | `today` (prop) | `today` | `today` | `today` | `currentDate` | `today` | | `showAdjacentDays` (prop) | `showAdjacentDays` | `showsAdjacentDays` | `showAdjacentDays` | `showAdjacentDays` | `showAdjacentDays` | | `label` (prop) | `label` | `label` | `label` | `label` | `accessibilityLabel` | | `change` (event) | `change` | `selection` | `onChange` | `onChanged` | `onChange` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `navigation-row`: The top row: the view toggle at the start, and the previous and next buttons at the end. - `view-toggle`: The displayed month and year with a chevron (expand_more). Pressing it switches between the day view and the year view. It is drawn with the unselected condition's colors. - `navigation`: The previous-month and next-month buttons: Tanrei icon-only Buttons of the text variant whose arrows follow the axis the months move along. They are hidden in the year view. A scroll of a wheel or a trackpad, a drag with a finger, a pen or a mouse, and Page Up and Page Down move the month too. - `weekday-row`: The narrow names of the seven weekdays, from the first day of the week. - `day`: One day in the grid (an item the calendar generates): its number on a round container that carries the day's condition and its state answer. The containers of the days inside a range join into one band. On the vertical axis the days are one unbroken column of weeks: a week two months share is one row, which a month change carries from its place in the one view to its place in the other. - `year` (optional): One year of the year view (an item the calendar generates), on a container that carries the year's condition and its state answer. - `focus-ring`: Gap-then-ring indicator around the container of the day, year or view toggle that has keyboard focus. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `mode` | `enum`: `single`, `range` | `"single"` | `mode` | single: one date, in value. range: one contiguous span of dates, from start to end inclusive. | | `value` | `string` | `""` | `value` | The chosen date in single mode, as an ISO 8601 calendar date ("2026-09-17"); empty when none is chosen. The calendar sets it when the person chooses a day and emits change; the product may also set it. A calendar date has no time and no time zone. | | `start` | `string` | `""` | `start` | The first date of the chosen range in range mode, as an ISO 8601 calendar date; empty when none is chosen. | | `end` | `string` | `""` | `end` | The last date of the chosen range in range mode, as an ISO 8601 calendar date, never before start; empty while only start is chosen. | | `min` | `string` | `""` | `min` | The earliest date that can be chosen, as an ISO 8601 calendar date; empty for no limit. | | `max` | `string` | `""` | `max` | The latest date that can be chosen, as an ISO 8601 calendar date; empty for no limit. | | `disabledDates` | `strings` | `` | `disabled-dates` | Dates inside min and max that cannot be chosen (booked, closed), as ISO 8601 calendar dates. Every platform also takes a predicate (isDateDisabled) for a rule no list can hold, such as every weekend; a day is unavailable when either says so. | | `today` | `string` | `""` | `today` | The date drawn as today, as an ISO 8601 calendar date. Empty uses the device's current date in its own time zone. Set it when the product's today is another (a venue's time zone, a server's date) and in tests. | | `firstDayOfWeek` | `enum`: `locale`, `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` | `"locale"` | `first-day-of-week` | The weekday in the first column. locale takes it from the locale (Sunday in the United States and Japan, Monday in most of Europe). | | `locale` | `string` | `""` | `locale` | A BCP 47 language tag ("en-US", "ja-JP") for month and weekday names, digits and the first day of the week. Empty uses the platform's current locale. The calendar is the Gregorian calendar in every locale. | | `startView` | `enum`: `day`, `year` | `"day"` | `start-view` | Whether the calendar first shows the days of a month or the list of years. year suits a date far from today, such as a birthday. | | `showAdjacentDays` | `boolean` | `false` | `show-adjacent-days` | Fills the grid's spare cells with the days of the previous and next month, drawn quieter than the month's own. Such a day can be chosen when it is available, and a range may start or end on it; choosing one also shows its month. | | `label` | `string` | `""` | `label` | The accessible name of the whole calendar ("Check-in date"). Needed when a page has more than one calendar, or when nothing near it says what the date is for. A picker that holds the calendar names it with its own label. | | `startLabel` | `string` | `""` | `start-label` | Range mode: the description of the start day, in the product's language ("Start date"). The product's: Tanrei has no words for it. Empty reads the product's words. | | `endLabel` | `string` | `""` | `end-label` | Range mode: the description of the end day, in the product's language ("End date"). The product's: Tanrei has no words for it. Empty reads the product's words. | | `previousMonthLabel` | `string` | `""` | `previous-month-label` | The accessible name of the previous-month button, in the product's language ("Previous month"). The product's: Tanrei has no words for it. Empty reads the product's words. Required: a glyph alone is not a name. | | `nextMonthLabel` | `string` | `""` | `next-month-label` | The accessible name of the next-month button, in the product's language ("Next month"). The product's: Tanrei has no words for it. Empty reads the product's words. Required: a glyph alone is not a name. | | `yearViewLabel` | `string` | `""` | `year-view-label` | The description of the view toggle, whose name is the month and year it shows, in the product's language ("Choose a year"). The product's: Tanrei has no words for it. Empty reads the product's words. | | `todayLabel` | `string` | `""` | `today-label` | Read after today's date and the current year, where the platform has no property that says so (the web's aria-current), in the product's language ("Today"). The product's: Tanrei has no words for it. Empty reads the product's words. With neither, the platform's own word for the present day in the locale, where it has one. | ### Events | Event | Description | | --- | --- | | `change` | The person chose a day that changes the choice. Carries value in single mode, or start and end in range mode (end empty after a start alone). The calendar has already set the props it carries. | ### Item: `day` One day in the grid. The calendar generates the days from the month, the bounds, the disabled dates and showAdjacentDays; a product and a fixture never list them. Names: Web `renderDay`, SwiftUI `TanreiCalendarDay`, Jetpack Compose `TanreiCalendarDay`, Flutter `TanreiCalendarDay`, React Native `CalendarDay`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `date` | `string` | `""` | The day, as an ISO 8601 calendar date. | | `disabled` | `boolean` | `false` | Whether the day is unavailable: before min, after max, in disabledDates or named by isDateDisabled. | | `adjacent` | `boolean` | `false` | Whether the day belongs to the previous or next month, shown because showAdjacentDays is true. | ### Item: `year` One year of the year view, from min's year to max's year. The calendar generates them; a product and a fixture never list them. Names: Web `renderYear`, SwiftUI `TanreiCalendarYear`, Jetpack Compose `TanreiCalendarYear`, Flutter `TanreiCalendarYear`, React Native `CalendarYear`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `year` | `number` | `0` | The year. | ### States `enabled`, `disabled`, `hovered`, `focused`, `pressed`, `selected` ### Accessibility - Role: `group` - Labeling: The calendar is a group named by label when it has one. The grid is named by the month and year it shows and its column headers are the weekdays' full names. Each day is named by its full date in the locale, with todayLabel after today's where the platform has no current-date property, and exposes its selected and disabled states; a range's start and end are described by startLabel and endLabel. The view toggle is named by its visible month and year, described by yearViewLabel, and exposes whether the year view is expanded. The navigation buttons are named by previousMonthLabel and nextMonthLabel. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab / Shift+Tab | Moves through the view toggle, the previous and next buttons and the active day (or the displayed year). | | Arrow keys | Move the active day by one day (Left and Right, in the direction the arrow points) or one week (Up and Down), changing the month as needed, whatever axis the months move along; in the year view, by one year or one row. | | Home / End | The first or last day of the week row; the first or last year. | | Page Up / Page Down | The same day of the previous or next month. | | Shift+Page Up / Shift+Page Down | The same day of the previous or next year. | | Enter or Space | Choose the active day or the focused year; activate the focused button. | - The cells are the days' hit areas and are never smaller than the minimum target (CAL-1); the view toggle extends its hit area (CAL-6). The navigation buttons are Tanrei Buttons, which meet the target themselves (BTN-5). - Unavailable days stay reachable by the arrow keys, as the WAI-ARIA date picker dialog pattern recommends, so a screen-reader user learns that a date exists and cannot be chosen. - Scrolling and dragging to move the month are pointer and touch shortcuts, with a finger, a pen, a mouse, a wheel or a trackpad. The buttons and Page Up / Page Down do the same, so nothing depends on a gesture, and a drag is never the only way (WCAG 2.5.7). While a drag lasts nothing the calendar exposes changes; while a scroll goes on through several months the title follows each month it reaches, but the month is announced once, when the scroll or the release has chosen it (CAL-31, CAL-32, CAL-34), so a screen reader is not read every month that passes. - A scroll along the calendar's axis is the calendar's while the pointer is over the day grid (CAL-33): a page that scrolls the same way does not scroll from there. The weekday row, the navigation row and everything around the calendar scroll the page as usual, and a calendar with a horizontal axis leaves the page's vertical scroll alone. - A day of a neighbouring month that is chosen by pointer brings its month into view (CAL-15), announced as any month change is. The keys never need it: the arrow keys show a day's month before Enter can choose it (CAL-11). - Typing a date is the Text field's job, not the calendar's: a product that wants both puts a Text field beside it, or uses a DateTimePicker opened from the field's trailing button. Typing is the fastest route for many people and the most direct one for screen reader users. - The calendar has no words of its own. Month and weekday names, digits and date forms are the platform's locale data, in the locale the calendar was given. Every other word it shows or announces is the product's: a prop of this instance, or the product's words set once. - The web exposes the grid with role grid, rows, column headers and gridcells with aria-selected and aria-disabled, and today with aria-current="date" (so todayLabel is not added there). The platforms without a grid role expose the rows and columns through their collection semantics where they have them (Compose's collection info), and otherwise each day as a button in reading order. - How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves. ### Behaviour Requirements in EARS form, each with its stable id. - **CAL-1** THE calendar SHALL lay out, from top to bottom, the navigation row, the weekday row and six rows of seven cells, each cell a square of comp.calendar.cell.size but never smaller than sys.target.touch for touch input and sys.target.pointer for fine pointers (a platform that cannot tell the input type SHALL use sys.target.touch), because the cells are the days' hit areas and cannot extend over each other; the first day of the displayed month SHALL sit in the column of its weekday, and all six rows SHALL be kept when the month needs fewer, so that the calendar keeps its height when the month changes. The navigation row and the weekday row are each one cell tall. THE calendar SHALL draw no surface and no padding of its own: it is as wide as its seven columns, and the page or the picker that holds it gives it its background and inset. - **CAL-2** THE calendar SHALL draw each day from exactly one condition, by precedence: selected for the date of single mode and for a range's start and end; in-range for a day strictly between a range's start and end; today for the date today names (or the device's current date) when it is neither; adjacent for a shown day of the previous or next month (CAL-15) when it is none of these; otherwise unselected. It SHALL draw each year of the year view from selected for the displayed year, today for the current year when it is not displayed, and otherwise unselected, and the view toggle from unselected. WHILE a day is unavailable THE calendar SHALL draw it from the disabled tokens of its condition. - **CAL-3** THE calendar SHALL draw a day's number in the locale's digits, centred in its cell, in comp.calendar.day.label.typescale and the label color of its condition (comp.calendar.unselected.label.color, and so on), on a container of side comp.calendar.day.container.size centred in the cell, with comp.calendar.day.container.shape corners eased by sys.shape.corner-smoothing, in the container color of its condition, with an outline of comp.calendar.outline.width in the outline color of its condition. The container of an in-range day SHALL instead span the full width of its cell at the same height, so that the containers of consecutive in-range days join into one band that breaks at the ends of a row with square ends; WHILE a range's start and end differ each of them SHALL also draw, behind its own container, the half of its cell toward the other in comp.calendar.in-range.container.color, so that the band runs into it. The band SHALL cover every day the grid shows between start and end, and no empty cell. - **CAL-4** THE calendar SHALL draw each weekday's narrow name from the locale ("S", "M" in English; "日", "月" in Japanese) centred in its column, in comp.calendar.weekday.typescale and comp.calendar.weekday.color, and SHALL expose it as a column header named by the weekday's full name; weekday names SHALL take no focus. - **CAL-5** THE calendar SHALL draw the navigation row with the view toggle at the start and, in the day view, the previous-month and next-month buttons at the end, comp.calendar.navigation.gap apart, each a Tanrei Button of the text variant and the medium size with an icon and no label, named previousMonthLabel and nextMonthLabel. WHILE comp.calendar.navigation.axis is vertical their glyphs SHALL be arrow_upward and arrow_downward; WHILE it is horizontal they SHALL be arrow_back for the previous month and arrow_forward for the next in every layout direction, pointing toward the start and the end: in a right-to-left layout the icon helper mirrors both, because the icon set marks them as mirrored, and the calendar SHALL NOT exchange the two names or mirror a glyph itself. The previous button SHALL be disabled while the displayed month is min's month and the next button while it is max's month, and in the year view both SHALL be hidden. THE calendar SHALL NOT change the buttons' variant, size or tokens. - **CAL-6** THE calendar SHALL draw the view toggle as a container at least comp.calendar.view-toggle.container.height tall with comp.calendar.view-toggle.container.shape corners eased by sys.shape.corner-smoothing, padded by comp.calendar.view-toggle.container.padding-inline at each end, holding the displayed month and year in the locale's form ("September 2026", "2026年9月") in comp.calendar.view-toggle.label.typescale and, comp.calendar.view-toggle.gap after it, the expand_more glyph at comp.calendar.view-toggle.icon.size with the family and fill of an unselected icon, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, both in comp.calendar.unselected.label.color on comp.calendar.unselected.container.color; the glyph SHALL be turned half a turn while the year view is shown, over comp.calendar.motion.state-duration with comp.calendar.motion.state-easing (at once where motion is reduced). WHERE the view toggle is shorter than the minimum target it SHALL extend its hit area to sys.target.touch for touch input and sys.target.pointer for fine pointers without changing its visual size; WHILE the year view is shown that hit area SHALL reach toward the first row of years, whose cells begin where the navigation row ends, no further than halfway across the space between the view toggle's visible bounds and that row, so that a press on a year, or in the nearer half of that space, goes to the year. WHEN it is activated it SHALL switch between the day view and the year view. - **CAL-7** WHEN the year view is shown THE calendar SHALL draw, in the space of the weekday row and the six rows of days, the years from min's year to max's year (1900 to 2100 when min or max is empty) in rows of three cells, each a third of the grid's width and comp.calendar.cell.size tall, each year centred in its cell in the locale's digits in comp.calendar.year.label.typescale on a container of comp.calendar.year.container.width by comp.calendar.year.container.height with comp.calendar.year.container.shape corners, colored and outlined as a day of its condition is; the list SHALL scroll, and SHALL open scrolled so that the displayed year's row is the third row in view, or as near to it as the list's ends allow. WHEN the user chooses a year THE calendar SHALL show the day view of the month with the displayed month's number in that year, clamped between min's and max's months, move focus to its active day and SHALL NOT change the choice; WHEN the view toggle is activated in the year view it SHALL show the day view unchanged. - **CAL-8** WHILE mode is single, WHEN the user chooses an available day by pointer, touch, Enter or Space THE calendar SHALL set value to it and, if it differs from the value before, emit change once with it. - **CAL-9** WHILE mode is range, WHEN the user chooses an available day THE calendar SHALL make it the start and clear the end when no start is chosen, when both are chosen, or when the day is before the start, and otherwise SHALL make it the end (a start and end on the same day make a one-day range); after each choice it SHALL set start and end and emit change once with both, end empty after a start alone. A range SHALL be one contiguous span from start to end inclusive; unavailable days between them SHALL stay inside it, drawn and exposed as unavailable (a product that cannot accept such a span says so after change). - **CAL-10** THE calendar SHALL give the day grid one tab stop, the active day: WHEN a month is shown the active day SHALL be the chosen date (single mode) or start (range mode) when it lies in that month, otherwise today when it does, otherwise the first available day of the month, otherwise its first day; only the active day SHALL take focus from Tab, and the keys of CAL-11 move it. - **CAL-11** WHILE focus is on a day THE calendar SHALL move the active day and focus with Right Arrow and Left Arrow one day in the direction the arrow points (the next and the previous day left to right, the previous and the next right to left), with Down Arrow and Up Arrow one week later and earlier, with Home and End to the first and last day of its week row, with Page Down and Page Up to the same day of the next and previous month (the last day of that month when it is shorter), and with Shift+Page Down and Shift+Page Up to the same day of the next and previous year, whatever comp.calendar.navigation.axis is; WHEN the new active day lies in another month THE calendar SHALL show that month; it SHALL NOT move the active day before min or after max; unavailable days SHALL be reachable but SHALL NOT be chosen; Enter and Space SHALL choose the active day. - **CAL-12** WHILE focus is in the year view THE calendar SHALL give the list one tab stop, the displayed year, and SHALL move focus with Right Arrow and Left Arrow one year in the direction the arrow points, with Down Arrow and Up Arrow one row, and with Home and End to the first and last year, scrolling the focused year into view; Enter and Space SHALL choose the focused year (CAL-7). - **CAL-13** WHEN the previous-month or next-month button is activated, a step of a detented wheel moves the month (CAL-33), a scroll or a drag ends on another month than the one shown when it began (CAL-34, CAL-31) or a day of a neighbouring month is chosen (CAL-15), THE calendar SHALL show that month, keep focus where it was, make the active day the same day number of the new month (its last day when the month is shorter; the chosen day, WHEN a day was chosen) and announce the new month and year once, politely; WHEN a year is chosen in the year view it SHALL announce the month and year it shows the same way. A month that a scroll only passes through is shown without an announcement (CAL-34). - **CAL-14** WHEN the displayed month changes by a button, a key, a step of a detented wheel (CAL-33) or a chosen day THE calendar SHALL play the change over comp.calendar.motion.page-duration with comp.calendar.motion.page-easing: WHILE comp.calendar.navigation.axis is vertical as one continuous scroll of the weeks, every frame of it being the in-between look of CAL-29 at the progress the easing gives, so that the two months are never drawn as two separate grids and a week they share is neither drawn twice nor replaced; WHILE the axis is horizontal as two pages, the old month's grid sliding out toward the start and the new one in from the end for a later month, and the reverse for an earlier one. Every way of moving the month SHALL move the same thing — on the vertical axis the one progress of CAL-29, on the horizontal one the place of the two pages — and none SHALL have a look of its own: a scroll of a wheel or a trackpad is followed as CAL-33 says and settles as CAL-34 says, and a drag is followed as CAL-30 says and settles as CAL-31 says. WHEN one of them begins while the days are still moving — a month change is playing, or the days are settling after a scroll or a drag — THE calendar SHALL carry on from what is on screen, without a jump and without waiting for the motion to end. WHEN it switches between the day view and the year view it SHALL cross-fade them over the same duration and easing; WHERE motion is reduced it SHALL make all of these changes at once. The weekday row, the navigation row and the calendar's size SHALL NOT move. - **CAL-15** WHILE showAdjacentDays is true THE calendar SHALL fill the cells before the displayed month's first day and after its last with the days of the previous and next month, in order, drawn from the adjacent condition unless a higher one applies (CAL-2), and treated as any day for availability (CAL-16), choosing (CAL-8, CAL-9) and the range's band (CAL-3); WHEN the user chooses such a day by pointer or touch THE calendar SHALL choose it as any day, emitting change as CAL-8 and CAL-9 say, and SHALL then show that day's month (CAL-13) with the motion of CAL-14, where the chosen day is one of the month's own and the active day, taking focus if focus was in the grid; a range's start and its end SHALL both do so. A press on an unavailable one SHALL choose nothing and show no other month. WHILE showAdjacentDays is false those cells SHALL be empty, take no press and be hidden from assistive technology. - **CAL-16** THE calendar SHALL treat as unavailable every day before min, after max, listed in disabledDates or named by the platform's isDateDisabled predicate. WHILE a day is unavailable THE calendar SHALL render its container, label, outline and opacity from the disabled tokens of its condition (comp.calendar.unselected.container.color at rest, and so on), SHALL NOT make it the chosen date, start or end, SHALL expose it to assistive technology as unavailable (disabled), and SHALL keep it reachable by the arrow keys. WHEN value, start or end names an unavailable day THE calendar SHALL still draw it as chosen, from the disabled tokens of the selected condition, until the person chooses another. - **CAL-17** WHEN the calendar is first shown THE calendar SHALL show the month of value or start, otherwise of today, clamped between min's month and max's month, or the year view WHERE startView is year; WHEN the product sets value, start or end to a date outside the displayed month THE calendar SHALL show that date's month, without the motion of CAL-14. - **CAL-18** WHILE a day, a year or the view toggle is hovered, keyboard-focused or pressed THE calendar SHALL render its container, label, outline and opacity from the component tokens of its condition in the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. WHEN these colors change between states THE calendar SHALL animate them over comp.calendar.motion.state-duration with comp.calendar.motion.state-easing, and SHALL change them at once where motion is reduced. - **CAL-19** WHEN a day, a year or the view toggle receives keyboard focus THE calendar SHALL show the focus ring around its container — around the circle of comp.calendar.day.container.size for every day, an in-range day included — without animation; focus gained by pointer or touch SHALL NOT show it. A day, a year or the view toggle that has focus SHALL become keyboard-focused WHEN a key works it — Enter or Space, or a key that moves focus to it (CAL-11, CAL-12) — however focus first reached it. WHEN the product moves focus to the calendar and says whether that focus is to show the ring — as a date-time picker does as it opens (DTM-3), from how it was opened — THE calendar SHALL show the ring or not as it says, also on a day or a year that has focus already, whatever the platform would draw for a focus given that way. - **CAL-20** WHEN the calendar's day, year or view toggle is pressed by pointer, touch, Enter or Space THE calendar SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner. - **CAL-21** WHILE pressed THE calendar's day, year or view toggle SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; label, outline, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.calendar.motion.feedback-duration with comp.calendar.motion.state-easing, fades over comp.calendar.motion.state-duration with comp.calendar.motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced. - **CAL-22** THE calendar's day, year and view toggle SHALL ease their container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show their keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. - **CAL-23** THE calendar SHALL expose itself as a group named by label while label is not empty, the day grid as a grid named by the displayed month and year with the weekday names as its column headers, and each shown day as a cell that can be activated, named by its full date in the locale ("Thursday, September 17, 2026") followed by todayLabel for today where the platform has no property for the current date, with its selected state (true for the chosen date and for every day of a range), described by startLabel or endLabel for a range's start and end, and with its disabled state while unavailable; empty cells SHALL be hidden. It SHALL expose the view toggle as a button named by its visible month and year, described by yearViewLabel, with its expanded state (true while the year view is shown), and each year as a button with its selected state and todayLabel for the current year. - **CAL-24** THE calendar SHALL take month and weekday names, digits and the locale's first day of the week from locale, or from the platform's current locale while locale is empty, and SHALL use firstDayOfWeek instead of the locale's while it is not locale; WHERE the platform has no week data for the locale it SHALL use the first days of CLDR's weekData, which the platform package embeds. Every date SHALL be a Gregorian calendar date without a time or a time zone, and WHILE today is empty THE calendar SHALL read the device's current date in its own time zone WHEN it is first shown and WHEN the date changes while it is shown. - **CAL-25** THE calendar's days, years, weekday names and view toggle SHALL grow with enlarged text rather than clip it: a day's container SHALL grow to hold its number. WHERE the space given to the calendar is narrower than seven minimum targets, the cells SHALL narrow equally so that the grid fits it, keeping their numbers at their size, and the calendar SHALL never be wider than the space it is given. - **CAL-26** WHEN the layout direction is right-to-left THE calendar SHALL mirror its layout — the first day of the week in the rightmost column, the view toggle at the right and the navigation buttons at the left, and, on the horizontal axis, the slide of CAL-14 and the side each neighbouring month lies on (the next month toward the left, so that a drag toward the right brings it, CAL-30) — and SHALL NOT mirror the vertical scroll of the weeks, a vertical drag or the vertical arrows. A drag SHALL move the days where the pointer goes, and a scroll of a wheel or a trackpad SHALL move them where it moves the content of a scrolled list, in every layout direction. - **CAL-27** WHEN mode, startView or firstDayOfWeek names a value the calendar does not define THE calendar SHALL behave as its default value and in debug builds report the unknown value; WHEN value, start, end, min, max, today or an entry of disabledDates is not an ISO 8601 calendar date, end is before start, value is set in range mode or start or end in single mode THE calendar SHALL ignore it and in debug builds report it; WHEN min is later than max THE calendar SHALL ignore both and report it in debug builds. - **CAL-28** THE calendar SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the calendar is shown THE calendar SHALL draw itself for the new direction at once, without a motion of its own, keeping the displayed month, the selection and its focus. - **CAL-29** WHILE comp.calendar.navigation.axis is vertical THE calendar SHALL treat the days as one unbroken column of week rows, in which a month's view is the six rows from the row of its first day, and SHALL draw every look between the views of two neighbouring months from one progress, 0 at the one and 1 at the other, with no threshold. The rows SHALL be offset along the column by the progress times the distance between the two views' first rows (four or five rows, each comp.calendar.cell.size tall) and clipped to the grid's six rows, so that a week the two views share is one row that travels from its place in the one to its place in the other. Every day SHALL be drawn at the linear interpolation by the progress between what the one view draws for it and what the other draws: its container, label and outline colors between the tokens of the adjacent condition and those of the unselected condition (comp.calendar.adjacent.label.color and comp.calendar.unselected.label.color, and so on, in the state the day is in) WHERE it is a neighbouring month's day in the one view and the month's own in the other (CAL-2), and its opacity between 1 where a view draws it and 0 where a view does not — a row outside that view's six, or a cell that view leaves empty because showAdjacentDays is false — so that a day coming into view fades in and a day leaving it fades out as far as the weeks have moved. A day that both views draw alike SHALL NOT change, and the band of a range (CAL-3) SHALL follow the same rule, each piece with its day. WHERE the two months are not neighbours (a step of a year, CAL-11; a date the keys reach in a further month) the distance SHALL be six rows, as if the later month's view began where the earlier one's ends. - **CAL-30** WHILE the day view is shown, WHEN the user presses the day grid with touch, a pen or the primary button of a mouse and drags past the platform's touch slop (8 points where the platform names none, for every kind of pointer), further along the axis comp.calendar.navigation.axis names than across it, THE calendar SHALL take the drag: the press SHALL choose no day when it ends (CAL-8, CAL-9), the day under it SHALL leave its pressed state as it does when a press ends (CAL-20), and from then until the drag ends THE calendar SHALL move the days by the distance the pointer has travelled along the axis since the press, in the frame the pointer moves and without a motion of its own — toward the next month for a drag toward the top (vertical) or the start (horizontal), toward the previous month for the reverse — never further than the view of the month next to the displayed one, and never past min's or max's month, where the days SHALL stop. WHILE the axis is vertical THE calendar SHALL draw the in-between look of CAL-29 at the progress that travel gives (the travel over the distance between the two views), so that the scroll of the weeks, the fading in of the days coming into view and the change of a neighbouring month's day into one of the month's own all follow the pointer continuously; WHILE the axis is horizontal the two pages of CAL-14 SHALL travel with the pointer, side by side. A press that ends before it has passed the slop SHALL choose the day under it as CAL-8 and CAL-9 say, with every kind of pointer, so that a click of a mouse on a day still chooses it. WHILE a drag the calendar has taken lasts, THE calendar SHALL follow the pointer wherever it goes, outside the grid and the calendar included; no day SHALL be drawn hovered; nothing the calendar draws SHALL be selected as text or picked up by the platform's drag and drop; and a fine pointer SHALL show the platform's cursor for something held and dragged (grabbing) until the drag ends. At rest the cursor over a day SHALL stay the one a pressable day shows: the grid does not advertise the drag, which is a shortcut. A press of another mouse button SHALL take no drag. A drag that is further across the axis than along it when it passes the slop SHALL be left to the scrolling ancestor for its whole length; a scroll of a wheel or a trackpad is followed as CAL-33 says. - **CAL-31** WHEN the user releases a drag the calendar has taken THE calendar SHALL choose one month: the neighbouring month the days have moved toward WHERE they are a quarter or more of the distance from the displayed month's view toward its view, and otherwise the displayed month — the same quarter that ends a scroll (CAL-34) — or, WHEN the release is a fling along the axis, the one of the two the fling is toward; a fling is a release faster than the platform's minimum fling velocity (Android's ViewConfiguration.getScaledMinimumFlingVelocity, Flutter's kMinFlingVelocity) or, where the platform names none (the web, SwiftUI, React Native), 0.5 points per millisecond, with every kind of pointer. A release's velocity is the pointer's over its last moves: WHERE the pointer has not moved for longer than the time after which the platform's velocity tracker takes a pointer as stopped (40 milliseconds in Android's VelocityTracker, Jetpack Compose's VelocityTracker and Flutter's VelocityTracker) or, where the platform names none (the web, SwiftUI, React Native), 40 milliseconds before the release THE calendar SHALL take the release as having no velocity, so that a drag that stops where it is wanted and is let go there is no fling, however fast it moved before it stopped. WHERE the chosen month is not the displayed one THE calendar SHALL show it as CAL-13 says and bring the days from where the release left them to its view over comp.calendar.motion.page-duration with comp.calendar.motion.page-easing; WHERE it is the displayed month THE calendar SHALL return them over the same motion and announce nothing. The quarter decides only what a release chooses; nothing drawn changes at it. The release SHALL NOT also choose the day under the pointer, and a drag SHALL never change value, start or end, nor emit change. - **CAL-32** WHEN a drag the calendar has taken is cancelled — the platform cancels the pointer (a system gesture, a lost capture), Escape is pressed while it lasts, the product sets value, start or end (CAL-17), or the year view is shown — THE calendar SHALL return the days to the view of the displayed month (the month the product's date has just named, where it named one) over comp.calendar.motion.page-duration with comp.calendar.motion.page-easing and announce nothing; WHEN the product sets value, start or end, or the year view is shown, while a scroll is being followed THE calendar SHALL do the same and SHALL ignore what is left of that scroll (CAL-34). WHILE a drag or a scroll holds the days between two views THE calendar SHALL NOT change the month and year that the view toggle and the grid's name show, the active day, keyboard focus or what it exposes to assistive technology: the days of the month coming into view SHALL be hidden from assistive technology and take no focus and no press until that month is the displayed one, which it becomes by the release that chooses it (CAL-31), by the end of the scroll that chooses it or by the scroll reaching its view (CAL-34). WHERE motion is reduced THE calendar SHALL still move the days with the pointer and with the scroll and draw the in-between look, which the person's own hand moves, and SHALL put them at the chosen month's view at once when the drag is released or cancelled or the scroll ends. - **CAL-33** WHILE the day view is shown, WHEN a wheel or a trackpad scrolls over the day grid further along the axis comp.calendar.navigation.axis names than across it, THE calendar SHALL take the scroll and move the days by the distance the scroll reports, one point for each point and in the frame it arrives, as the content of a scrolled list moves — toward the next month for a scroll toward the bottom (vertical) or toward the end (horizontal), toward the previous month for the reverse — without a motion of its own and with no least amount: the slightest scroll moves the days by that much and no further. WHILE the axis is vertical THE calendar SHALL draw the in-between look of CAL-29 at the progress that travel gives; WHILE it is horizontal the two pages of CAL-14 SHALL travel side by side. A scroll that goes on SHALL go on through month after month: WHEN the days reach the view of the neighbouring month THE calendar SHALL make that month the displayed one (CAL-34) and carry on toward the month after it with the distance that is left, in the same frame, so that a scroll never waits for an earlier one to end and no part of it is dropped. The days SHALL stop at the view of min's or max's month; a scroll along the axis that can move them no further SHALL still be the calendar's and SHALL NOT be passed on to a scrolling ancestor. A scroll further across the axis than along it SHALL be left to the scrolling ancestor, and so SHALL a scroll that zooms (a pinch on a trackpad, a wheel turned with the platform's zoom key). WHERE the platform reports a scroll as steps of a detented wheel and not as a distance (a delta in lines or pages on the web; a mouse wheel's notch where the platform tells it from a trackpad), each step SHALL instead move one month, as a press of the previous or next button does (CAL-13, CAL-14), one step after another without waiting for the motion to end. - **CAL-34** THE calendar SHALL take a scroll it follows (CAL-33) as ended WHEN the platform says that it has ended, its momentum included, where the platform reports that; where it does not (the web), WHEN no scroll event has arrived for 150 milliseconds, or WHEN the scroll has slowed below 0.1 points per millisecond, measured over its events of the last 100 milliseconds — the tail of a momentum scroll, which need not be waited out: THE calendar SHALL then ignore the events that follow for as long as they are no faster than that, until a faster one arrives or 150 milliseconds pass without any. WHEN a scroll ends with the days between two views THE calendar SHALL choose one of the two — the neighbouring month WHERE the days are a quarter or more of the distance from the displayed month's view toward its view, and otherwise the displayed month, so that a slight scroll returns and a deliberate one need not reach halfway — and SHALL bring the days to the chosen view over comp.calendar.motion.page-duration with comp.calendar.motion.page-easing (at once where motion is reduced, CAL-32). The displayed month SHALL be the month whose view the days last rested on or reached: WHEN a scroll that goes on reaches a neighbouring month's view THE calendar SHALL show that month in the view toggle and the grid's name at once, make its days the ones that take focus and presses, and move the active day and a focused day as CAL-13 says, but SHALL announce nothing yet; the quarter is then counted from that view. THE calendar SHALL announce the month and year once, politely, WHEN a scroll has ended and the days have been given their view, and only WHERE that month is not the one that was displayed when the scroll began; a scroll that returns SHALL announce nothing. WHEN a faster scroll event arrives, a drag is taken or a button or a key moves the month while the days are settling THE calendar SHALL carry on from what is on screen (CAL-14). A scroll SHALL never change value, start or end, nor emit change. - **CAL-35** THE calendar SHALL have no words of its own: it SHALL take startLabel, endLabel, previousMonthLabel, nextMonthLabel, yearViewLabel and todayLabel from the instance's prop and, WHILE that is empty, from the product's words of the same name; WHILE neither gives todayLabel it SHALL take the word from the platform's locale data WHERE the platform has the locale's own word for the present day, and it SHALL take no other word from anywhere. IF neither gives a navigation button its name, or a range's start or end its description, THE calendar SHALL still draw the part and keep it working, and in debug builds SHALL report the missing words once, naming the prop. WHILE neither gives yearViewLabel the view toggle SHALL have no description: its name and its expanded state (CAL-23) still say what it shows. - **CAL-36** WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE calendar SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its group, which it SHALL be WHILE it has a name: its label, or one given so — an id reference by the elements it names in the host's tree or a tree around it, a description after its own. WHILE label is not empty it is the group's name, over a name given so. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE calendar SHALL take it off that element. - **CAL-37** WHEN the control height (dial.control.height) is N THE calendar's view toggle and a year's container SHALL be N tall: the view toggle of CAL-6 SHALL be drawn at comp.calendar.view-toggle.container.height and a year's container of CAL-7 at comp.calendar.year.container.height, each sys.control.height.medium held at sys.target.minimum, as a day's container is drawn at comp.calendar.day.container.size (CAL-3), so that the navigation row's controls stand as tall as its previous and next Buttons, which follow the control height as theirs do. The cell (comp.calendar.cell.size) is the pitch of the grid and no control on a row: it holds a touch target for every day and every row of years, because cells cannot extend a hit area over each other (CAL-1), as Material draws a 40 day in a 48 cell; it SHALL keep its own size at every control height, and the navigation row SHALL stay one cell tall. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.calendar.…` → `--tanrei-comp-calendar-…`). #### `tanrei.comp.calendar` | Token | Type | Value | | --- | --- | --- | | `comp.calendar.view-toggle.container.height` | `dimension` | `40px` | | `comp.calendar.view-toggle.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.calendar.view-toggle.container.padding-inline` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.calendar.view-toggle.gap` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.calendar.view-toggle.label.typescale` | `typography` | `{tanrei.sys.typescale.label}` | | `comp.calendar.view-toggle.icon.size` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.calendar.navigation.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.calendar.navigation.axis` | `number` | `0` | | `comp.calendar.weekday.typescale` | `typography` | `{tanrei.sys.typescale.label-small}` | | `comp.calendar.weekday.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.calendar.cell.size` | `dimension` | `48px` | | `comp.calendar.day.container.size` | `dimension` | `40px` | | `comp.calendar.day.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.calendar.day.label.typescale` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.calendar.year.container.width` | `dimension` | `72px` | | `comp.calendar.year.container.height` | `dimension` | `40px` | | `comp.calendar.year.container.shape` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.calendar.year.label.typescale` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.calendar.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.calendar.motion.page-duration` | `duration` | `{tanrei.sys.motion.duration.medium1}` | | `comp.calendar.motion.page-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.standard}` | | `comp.calendar.motion.state-duration` | `duration` | `{tanrei.sys.motion.role.state.compact}` | | `comp.calendar.motion.state-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.state}` | | `comp.calendar.motion.feedback-duration` | `duration` | `{tanrei.sys.motion.role.feedback}` | | `comp.calendar.unselected.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.unselected.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.calendar.unselected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.unselected.state-layer.color` | `color` | `{tanrei.comp.calendar.unselected.label.color}` | | `comp.calendar.adjacent.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.adjacent.label.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.calendar.adjacent.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.adjacent.state-layer.color` | `color` | `{tanrei.comp.calendar.adjacent.label.color}` | | `comp.calendar.today.container.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.today.label.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.calendar.today.outline.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.calendar.today.state-layer.color` | `color` | `{tanrei.comp.calendar.today.label.color}` | | `comp.calendar.selected.container.color` | `color` | `{tanrei.sys.color.primary}` | | `comp.calendar.selected.label.color` | `color` | `{tanrei.sys.color.on-primary}` | | `comp.calendar.selected.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.selected.state-layer.color` | `color` | `{tanrei.comp.calendar.selected.label.color}` | | `comp.calendar.in-range.container.color` | `color` | `{tanrei.sys.color.surface-dim}` | | `comp.calendar.in-range.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.calendar.in-range.outline.color` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.calendar.in-range.state-layer.color` | `color` | `{tanrei.comp.calendar.in-range.label.color}` | Per-state tokens, valued by the design system's pattern rules (not written by hand): - `comp.calendar...` for the variants `unselected`, `adjacent`, `today`, `selected`, `in-range`, the states `hovered`, `focused`, `pressed`, `disabled` and the properties `container.color`, `label.color`, `outline.color`, `state-layer.color`. - `comp.calendar..` for the states `hovered`, `focused`, `pressed`, `disabled` and the properties `opacity`. ## Callout > A notice that is part of the content and stays there: a note, a caution, the reason for something or a summary of what is wrong, in the flow of the page, as a quiet fill or an outline, in the colors and with the glyph of a status where it has one, with an optional title, actions and a close button; announced only when it appears in answer to something. - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/callout/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/callout.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/callout`). - React: `Callout` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-callout` | lagging | | SwiftUI | `TanreiCallout` | planned | | Jetpack Compose | `TanreiCallout` | planned | | Flutter | `TanreiCallout` | planned | | React Native | `Callout` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `title` (prop) | `headline` | `title` | `title` | `title` | `title` | | `statusLabel` (prop) | `statusLabel` | `statusLabel` | `statusDescription` | `statusSemanticLabel` | `statusAccessibilityLabel` | | `live` (prop) | `live` | `isLive` | `live` | `live` | `live` | | `closable` (prop) | `closable` | `isClosable` | `closable` | `closable` | `closable` | | `closeLabel` (prop) | `closeLabel` | `closeLabel` | `closeDescription` | `closeSemanticLabel` | `closeAccessibilityLabel` | | `open` (prop) | `open` | `isPresented` | `visible` | `visible` | `open` | | `dismiss` (event) | `dismiss` | `onDismiss` | `onDismiss` | `onDismiss` | `onDismiss` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The block that holds the notice, as wide as its place in the layout and as tall as its content, flat on the surface it sits on. Filled in the tonal look (a quiet neutral, or a status's quiet container) and edged in the outlined look. It carries no state: nothing about it answers a pointer, a press or focus. - `outline` (optional): The outlined look's edge: one hairline inside the container, the same in every status. - `icon` (optional): The glyph at the start, on the first line of the text: the status's glyph from the system's icon set (info, warning, error or check_circle, the ones a snackbar draws), or the glyph the product names. In the status's own color, a little softer than the text. Decorative: the status is given in words. - `title` (optional): A few words that name the notice, above the body. Plain text unless the product gives a heading; it wraps and is never cut. - `body`: The notice itself: the product's content, from one sentence to several paragraphs with lists, links, code and tables. Long-form blocks in it are prose. - `actions` (optional): One or two of the product's own Buttons or links that follow up on the notice, in a row below the text. - `close-button` (optional): An icon-only Button of the size comp.callout.close-button.size names (small in the default system) showing the close glyph at the end of the first row, in the variant comp.callout.close-button.variant names (tonal in the default system) and, on a filled look, in the tone of that fill: its content color, so that its container is that color made translucent and its glyph is that color. The callout places it and chooses its variant and its tone; everything else it reads from Button's own tokens. The only part of a callout that answers a pointer, a press or focus, and it answers as a Button. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `title` | `string` | `""` | `headline` | A few words above the body that name the notice ("Not published yet"). Plain text, never a heading. Empty draws the body alone. The title slot takes its place where the product needs a heading of its own level or inline content. | | `status` | `enum`: `default`, `info`, `warning`, `error`, `success` | `"default"` | `status` | What the notice is, in the names the snackbar and the tag use. default: a neutral aside, with no glyph unless the product gives one. info, warning, error and success draw the look in that status's color roles with that status's glyph; a live callout is announced assertively for warning and error. Use them for what they mean everywhere in the system: advice is not a success. | | `statusLabel` | `string` | `""` | `status-label` | The status in words, in the product's language ("Warning"), read by assistive technology before the title and the body and not drawn, so that the status never rests on color and glyph alone. For a callout whose title does not itself say the status; needed when it has a status and no title. Ignored while status is default. | | `variant` | `enum`: `tonal`, `outlined` | `"tonal"` | `variant` | How much the callout weighs. tonal: a quiet fill, the default. outlined: no fill and one hairline, for a callout on a tinted surface or inside a filled card, where a fill would vanish, and for many callouts close together. A design system may add values. | | `size` | `enum`: `medium`, `large` | `"medium"` | `size` | The size of the text, in prose's two sizes. medium sets the body in the interface's own text style, for a callout among controls: a form, a panel, a dialog. large sets it in the style for long reading, for a callout in a page whose purpose is the text. Paddings, the glyph and the close button are the same at both. A design system may add values. | | `live` | `boolean` | `false` | `live` | Whether the callout is announced. False, the default, is for a callout that is part of what was written: it is a note, read where it stands. True is for one that appears or changes in answer to something (a summary of a form's errors after a submit, a notice that the file changed underneath the person): it is a live region, announced once when it is shown and when its content changes, politely or, for warning and error, assertively. It changes nothing that is drawn. | | `closable` | `boolean` | `false` | `closable` | Draws a close button, for a notice the person may put away (an announcement, a hint they have read). A caution that qualifies the content beside it should not be closable. | | `closeLabel` | `string` | `""` | `close-label` | The close button's accessible name, in the product's language ("Close"). Required while closable is true. | | `open` | `boolean` | `true` | `open` | Whether the callout is shown. The close button sets it to false; the product sets it to show a callout again or to show one in answer to something. A callout that is not open draws nothing and takes no space; it opens and closes in one motion of its height and its opacity (CLO-13). | ### Events | Event | Description | | --- | --- | | `dismiss` | The person closed the callout with its close button. Emitted exactly once, after open became false; never emitted when the product sets open. | ### Slots | Slot | Description | | --- | --- | | `default` | The body: text, or the product's own blocks (paragraphs, lists, a table, a code block, any component). Long-form blocks are laid out as prose of the callout's size. | | `icon` | A glyph of the system's icon set, by name, drawn in place of the status glyph, or as the glyph of a callout without a status (a tip's lightbulb). | | `title` | The product's own title content in place of the title prop: text with inline content, or a heading of the level the page's outline needs. The callout draws it in the title's style and changes neither its role nor its level. | | `actions` | The actions: the product's own Buttons or links, one or two. The callout lays them out below the text and does nothing else to them. | ### States `enabled` ### Accessibility - Role: `note` - Labeling: A callout that is not live is a note (the note role on the web), read where it stands, named by its title or, without one, by statusLabel. A live callout is a live region instead: polite in the default, info and success forms (the status role on the web) and assertive in the warning and error forms (the alert role on the web), announced once when it is shown after its page was presented and when its content changes. In both, statusLabel is exposed as text before the title and the body; the glyph is hidden. A title given as text is plain text; a heading in the title slot keeps its level. The close button's name is closeLabel. Actions are the product's own controls with their own names. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab | Reaches, at the callout's place in the page, the links and controls of the body, then the actions, then the close button. The callout itself is not a stop, and showing one never moves focus. | | Enter or Space | Activates the focused close button: the callout closes and focus returns to where it was before it entered the callout (CLO-12). | - Static content is not an alert. A callout written into a page (a note in documentation, a caution above a procedure) must not interrupt a screen reader when the page loads or be repeated as a status message: it is read in order, as the paragraph before it is. live is for what appears or changes in answer to something, and even then a callout that the page is first presented with is not announced (CLO-21). - A summary of a form's errors is a live callout with the error status, shown after the submit. Whether focus also moves to it is the product's decision, by its own means (the callout takes no focus by itself): moving focus to the summary suits a long form whose first error may be off screen; announcing it and moving focus to the first field in error suits a short one. Do not do both. - A notice for a whole page or screen (a banner: the connection is lost, the file changed on disk, a trial ends) is a callout placed by the product above that region's content, live, usually with an action or a close button. Put it where it comes first in reading order for the region it concerns. - WCAG 1.4.1 (use of color): a status is never told by color alone. A status form draws the status's glyph, a shape of the icon set, and the status is in the title's words or in statusLabel (CLO-20). The component cannot tell whether a title says its status, so that is the product's to check: "Accessibility" on a warning needs statusLabel "Warning"; "Warning: not published yet" does not. - WCAG 1.3.1 (info and relationships): the callout does not decide whether its title is a heading. Most titles are labels of a note and should stay text, or the page's outline fills with entries such as "Note". Where a callout does open a part of the page that people navigate to, the product gives a heading of the right level in the title slot. - WCAG 1.4.3 and 1.4.11 (contrast) in the default system: the title and the body are a role on its paired role (on-secondary-container on secondary-container, on-info-container on info-container, on-surface on a surface), each held to 4.5:1 by the token invariants. The glyph is drawn at an opacity of its color, so its contrast is that of the color as drawn: at least 3.5:1 on its own status container and on every surface, in every scheme. A link in the body is the system's link color, underlined: at least 4.6:1 on every tonal container (7.2:1 in the high-contrast schemes). The outlined look's edge is decorative. - Actions are the product's Buttons. A filled or a tonal Button brings its own fill and keeps its own contrast; the label of an outlined or a text Button sits on the callout's fill, where the default system's primary keeps at least 13:1 on every tonal container. A tonal Button has the fill of the tonal callout without a status and cannot be seen as a button there: use outlined or text. The focus indicator of a product's control in the body or the actions is the system's focus color, at least 4.6:1 on every tonal container of the default system. - A closable callout that returns on every visit is noise: when the person closes one, the product should remember it. The callout only reports the close (dismiss). - Do not nest callouts, and do not stack several at the top of a page: two notices of the same weight side by side cancel each other. One callout may hold a list of points. - Forced colors (CLO-24): a tonal callout loses its fill, so every look gains an edge in the text color. Statuses then differ by glyph and words alone. - Web: the body, the title slot and the actions are light-DOM children of ``, so they stay in the document: they are found by search in the page, translated, selected and read without script, and before the element is defined they show as plain blocks in the page's own text styles, without the fill, the glyph and the close button. A title given by the `headline` attribute is not shown until the element is defined; content pages should use the title slot. - The callout itself has no states: nothing about its container, its text or its glyph answers a pointer, a press or focus. Its close button is a Button, and answers them as every Button does. - WCAG 1.4.11 (non-text contrast) and 2.4.13 (focus appearance) for the close button: in a filled look it is drawn in the tone of the fill (BTN-45), its glyph in the fill's content color (the body color, held to 4.5:1 on the fill by the token invariants) over a container of that color at comp.button.tone.container.opacity. In the default system the glyph keeps against that blend, in every status, at least 9.5:1 at rest in the light schemes and 7.7:1 in the dark ones, and at least 6.0:1 hovered, focused or pressed in every scheme; the focus indicator's outer stroke, in the same color on the callout's fill, keeps at least 12:1. In the outlined look it is the variant's own Button on the surface, whose glyph the Button's own tokens hold. ### Behaviour Requirements in EARS form, each with its stable id. - **CLO-1** THE callout SHALL draw a container as wide as the layout it is placed in gives it (CLO-22) and as tall as its content, with corners comp.callout.container.shape eased by sys.shape.corner-smoothing and no elevation, padded by comp.callout.container.padding-block above its first line and below its last block, by comp.callout.container.padding-inline at the start, and at the end by comp.callout.container.padding-inline where the text meets it or by comp.callout.container.padding-inline-end-with-close after the close button. Inside it SHALL lay out, from the start: the glyph, where it has one (CLO-5, CLO-6); comp.callout.icon.gap after it a column that takes the remaining width and holds the title (CLO-7), the body (CLO-8) and the actions (CLO-9), in that order; and comp.callout.container.gap after that column the close button, where it has one (CLO-10). THE callout SHALL centre the glyph and the close button on the first line of the text (the title's, or the body's without a title) and keep them there however tall the text grows, and any height the container has beyond its content SHALL lie below the content. - **CLO-2** WHILE status is default THE callout SHALL fill its container with the container color of its variant and draw its title, its body and a glyph the product gave in that variant's title, body and icon colors: comp.callout.container.color.tonal, comp.callout.title.color.tonal, comp.callout.body.color.tonal and comp.callout.icon.color.tonal for tonal, and outlined's tokens of the same names (comp.callout.container.color.outlined, comp.callout.body.color.outlined, and so on). - **CLO-3** WHILE status is info, warning, error or success THE callout SHALL draw its container, its title, its body and its glyph from the parts of its variant prefixed with the status: for a tonal info callout comp.callout.info.container.color.tonal, comp.callout.info.title.color.tonal, comp.callout.info.body.color.tonal and comp.callout.info.icon.color.tonal; for outlined, and for warning, error and success, their own tokens of the same names (comp.callout.error.icon.color.outlined, comp.callout.success.container.color.tonal, and so on). A status SHALL change these colors, the glyph (CLO-5), the tone of the close button (CLO-10) and how a live callout is announced (CLO-21), and nothing else: the callout's size, shape, layout and edge stay those of its variant and size. - **CLO-4** WHILE variant is outlined THE callout SHALL draw an edge comp.callout.outline.width wide in comp.callout.outline.color inside its container's size, following its corners, in every status, without changing the callout's size or the place of its content; WHILE variant is tonal it SHALL draw no edge. A status SHALL NOT color the edge: it is the system's one hairline. - **CLO-5** WHILE status is info, warning, error or success and the icon slot is empty THE callout SHALL draw that status's glyph from the system's icon set (info for info, warning for warning, error for error, check_circle for success), the glyphs a snackbar draws, in a box of comp.callout.icon.size, in its form's icon color (CLO-3) drawn at comp.callout.icon.opacity (an opacity of the glyph alone, which fades nothing else), with sys.icon.family.unselected and sys.icon.fill.unselected, sys.icon.weight and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max. The glyph so drawn SHALL keep 3:1 against its container in every scheme of the default system, and against every surface role in the outlined look. THE callout SHALL keep the glyph from assistive technology, which is given the status in words (CLO-20). WHILE status is default and the icon slot is empty THE callout SHALL draw no glyph and no room for one: the text starts at the start padding. - **CLO-6** WHERE the icon slot holds a glyph THE callout SHALL draw it in the place, the box, the color and the opacity CLO-5 gives the status glyph (the icon color of its form, CLO-2 and CLO-3), in every status and without one, SHALL draw no status glyph beside it, and SHALL keep it from assistive technology: the product's glyph says what kind of notice this is (advice, an experiment, something new), and the words say it to everyone. - **CLO-7** WHILE title is not empty THE callout SHALL draw it above the body in the text style of its size (comp.callout.title.typescale.medium for medium, comp.callout.title.typescale.large for large) and the title color of its form (CLO-2, CLO-3), with comp.callout.title.gap between it and the body; the title SHALL wrap and SHALL never be cut. WHERE the title slot holds content THE callout SHALL draw that content in the title's place, style and color instead of the title prop, and SHALL change neither its role nor its level: a title given as text is plain text and never a heading, and a title the product gives as a heading stays a heading of the level the product gave it, drawn as every other title is. WHILE both are empty THE callout SHALL draw the body alone, on the first line. THE callout SHALL set the title's letter-spacing by the script of its text, as every title is set (PRS-20): no negative letter-spacing WHERE its language is Chinese, Japanese or Korean, and none WHERE its script joins its letters or stacks marks on them. - **CLO-8** THE callout SHALL draw the content of its default slot as its body, below the title, and SHALL give it the text style of its size (comp.callout.body.typescale.medium for medium, comp.callout.body.typescale.large for large) and the body color of its form (CLO-2, CLO-3) as the style and color its text takes where nothing inside sets another. The body SHALL wrap and SHALL never be cut or limited to a number of lines. WHERE the body holds long-form blocks (paragraphs, lists, a quote, a table, a code block) they SHALL be laid out as prose of the callout's size (PRS-1, PRS-5), without a measure of their own, so that the first block has no space before it and the last none after it and the body is exactly as tall as its content; the callout SHALL add no style to anything inside a component placed in its body, and a link in the body SHALL be underlined at rest (PRS-17). - **CLO-9** WHERE the actions slot holds content THE callout SHALL lay it out as a row below the text (the body, or the title where there is no body), comp.callout.actions.gap below it, starting at the text's start edge, with comp.callout.actions.item-gap between two actions along the row and between rows where they wrap; an action's label SHALL NOT be cut to make the row fit. The actions are the product's own Buttons and links: THE callout SHALL NOT restyle them, SHALL NOT answer their presses and SHALL NOT close when one is activated. They SHALL follow the body in reading order and in the focus order, before the close button. - **CLO-10** WHILE closable is true THE callout SHALL draw at the end of its first row an icon-only Button of the size comp.callout.close-button.size names showing the glyph close of the system's icon set and named by closeLabel, in the variant comp.callout.close-button.variant names and, in every look but outlined, in the tone of its form (BTN-45): the body color of that form (comp.callout.body.color.tonal without a status, comp.callout.info.body.color.tonal for info, and so on), the content color of the fill it stands on, so that its container is that color made translucent and its glyph is that color; both given through the channel a Button reads from the component that places it, and otherwise unrestyled: it reads Button's own tokens, answers hover, focus and press as any Button does and keeps its own minimum target (BTN-5). The outlined look has no fill, so its close button takes no tone and is drawn as the variant draws it on the surface the callout sits on. THE callout's container, its text and its glyph SHALL NOT change under a pointer, a press or focus: the callout itself has no states. WHILE closable is false THE callout SHALL draw no close button and keep no room for one. - **CLO-11** WHEN the user activates the close button by pointer, touch, Enter or Space THE callout SHALL set open to false, emit dismiss exactly once and close (CLO-13). THE callout SHALL NOT close by itself after a time, and SHALL NOT answer Escape: it is part of the content, and Escape belongs to whatever overlay or field the person is in. - **CLO-12** WHEN a callout closes while focus is inside it THE callout SHALL move focus to the element that had it before focus entered the callout or, where that element no longer exists or cannot take focus, leave focus to the platform's default, so that the next Tab reaches what followed the callout; WHEN it closes while focus is elsewhere it SHALL NOT move focus. - **CLO-13** WHILE open is false THE callout SHALL draw nothing, take no space and expose nothing to assistive technology, and its content SHALL NOT be reachable by focus. WHEN open becomes false while the callout is drawn THE callout SHALL close in one motion, in its layout, over comp.callout.motion.disclosure-duration with comp.callout.motion.disclosure-easing (sys.motion.role.disclosure and sys.motion.easing.spatial): its height goes to none with its content fixed to its top edge, nothing inside it moving or scrolling, while its opacity goes from whole to transparent; what stands below it moves with its bottom edge at every frame, and the space its container keeps beside it (a gap, a margin) closes over the same motion, so that nothing that follows moves by a jump when it is gone (MOT-5). WHEN open becomes true THE callout SHALL open along the same path the other way: from no height and transparent to its height and whole, what follows moving with it from the place it had without the callout. WHEN open changes while the callout moves THE callout SHALL turn round from the height and the opacity then drawn (MOT-2). What assistive technology and focus are given SHALL change at once, not after the motion: from the moment open becomes false the callout exposes nothing, nothing in it can take focus (focus has left it, CLO-12) and nothing of it is announced; from the moment open becomes true it is exposed as CLO-20 says, a live callout is announced (CLO-21), and its content is reachable by focus. WHERE motion is reduced, and while the callout draws its first frames (MOT-3), THE callout SHALL appear or disappear at once (MOT-6). A callout that comes to have content or loses it while open is true (CLO-31) changes at once. THE callout SHALL emit dismiss only for a close the person made (CLO-11), never when the product sets open. - **CLO-19** THE callout SHALL ease its container corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0); a platform that cannot draw it SHALL fall back to a quarter circle and state that in its README. Its close button's corners and its focus indicator are the Button's (BTN-10). - **CLO-20** WHILE live is false THE callout SHALL be exposed to assistive technology as a note: a part of the content that qualifies what is around it, read where it stands in reading order, named by its title where it has one and otherwise by statusLabel where status is not default and the product gave one. WHILE status is not default and statusLabel is not empty THE callout SHALL expose statusLabel as text before the title and the body, set apart so that it is read as a phrase of its own ("Warning, …"), and SHALL NOT draw it; WHILE status is default it SHALL ignore statusLabel. A callout that is not live SHALL NOT be announced when it is shown or when its content changes, SHALL NOT move focus, and SHALL NOT be a stop in the focus order: static content is not an alert. - **CLO-21** WHILE live is true THE callout SHALL be a live region in place of a note. WHEN it is shown after its page or view was first presented (open becomes true, or the product adds it), and WHEN its title, its body or its status changes while it is shown, THE callout SHALL have assistive technology announce it once: statusLabel first when status is not default, then the title when it has one, then the whole body. It SHALL announce politely (after what is being read) when status is default, info or success, and assertively (interrupting what is being read) when status is warning or error, as a snackbar does, and SHALL NOT move keyboard or screen-reader focus. A live callout that is drawn with the first presentation of its page or view SHALL NOT announce itself then. live SHALL change nothing that is drawn. - **CLO-22** THE callout SHALL lay itself out as a block in the flow of its container: it SHALL take the whole inline size the container gives it, in a page, in a list item, in a tab's panel, in a card or in another callout's body alike, with its start edge on the start edge of the text around it; it SHALL bring no outer space of its own (PRS-15: the space between it and its neighbours is its container's), SHALL never be wider than its container, SHALL have no minimum width, no maximum width and no measure of its own, and SHALL NOT scroll: content that cannot shrink (a table, a line of code) scrolls inside its own box. THE callout SHALL NOT float over the content, stick to an edge while the content scrolls or raise itself above it: where it stands is the product's layout. - **CLO-23** WHILE the text size is enlarged THE callout SHALL grow its title and its body with it, keep its paddings and gaps, wrap, and grow in height; it SHALL keep the glyph's box at comp.callout.icon.size and the close button at its own size (a Button's icon-only circle, BTN-12), both still centred on the first line (CLO-1), SHALL cut nothing and set no fixed height, SHALL lose no content when the reader raises line height, paragraph spacing, letter spacing or word spacing, and SHALL need no horizontal scrolling at a width of 320 points with text at 200 %. - **CLO-24** WHERE the platform draws with a person's own forced colors (the web's forced-colors mode, and a platform's equivalent where it has one) THE callout SHALL draw an edge comp.callout.outline.width wide in the platform's text color inside its container in every variant and status, its title, body and glyph in that text color with the glyph whole (no opacity), links in the platform's link color and still underlined, and its close button as a Button draws itself there, so that a look whose fill the mode removes is still a bounded block; the status SHALL then rest on the glyph's shape, the title's words and statusLabel. - **CLO-25** WHERE the layout direction is right-to-left THE callout SHALL mirror the order of its content and apply its paddings by logical start and end: the glyph at the right, the text after it, the actions starting at the text's right edge and the close button at the left. - **CLO-26** THE callout SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the callout is shown THE callout SHALL draw itself for the new direction at once, without a motion of its own, keeping its open state and its focus. - **CLO-27** WHERE the layout direction is right-to-left THE callout SHALL draw the glyph of its icon slot mirrored left to right exactly when the system's icon set marks that glyph's name as mirrored or the product forces mirroring for that use, and unmirrored when the product forbids it: the icon helper mirrors the glyph inside its own box, about the box's vertical centre line, changing neither its place, size, color and opacity nor the order CLO-25 gives. THE callout SHALL NOT mirror a glyph itself, SHALL NOT mirror content the product gives as an image or a view of its own rather than by a glyph's name, and its own glyphs (the four status glyphs) are drawn through the same helper, which mirrors none of them under the default icon set; the close button's glyph is the Button's (BTN-19). - **CLO-28** THE callout SHALL lay out a title given as text as text of its own direction, isolated from the text around it: it takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right name, a number with its unit and a version keep their own order in a right-to-left layout and reorder nothing beside them; THE callout SHALL still place the title and align its lines by the layout direction, not by the text's own. The body's blocks are laid out as prose lays out a block (PRS-25): each by its own first strong character unless the content states a direction, with its lines aligned to the start edge of the layout. - **CLO-29** WHILE the system's icon set cannot yet draw a glyph the callout draws itself (a status's glyph, or the icon slot's; its font is still loading) THE callout SHALL draw nothing in that glyph's place, never the glyph's name as text, SHALL keep the glyph's box, and SHALL draw the glyph once the set can; statusLabel and closeLabel SHALL still reach assistive technology. The close button's glyph is the Button's to draw. - **CLO-30** WHEN variant or size names a value that the active design system does not have, or status names a value this spec does not have, THE callout SHALL render with the default value (the default variant's or size's tokens, status default), and in debug builds report the unknown value. - **CLO-31** IF the title, the title slot and the body are all empty THE callout SHALL draw nothing, take no space and expose nothing, and in debug builds report that a callout has no content: a glyph, actions or a close button alone are not a notice. WHILE status is not default and both the title and statusLabel are empty THE callout SHALL still render and in debug builds report that the status is not given in words; WHILE closable is true and closeLabel is empty it SHALL still render the close button and in debug builds report that the button has no accessible name; IF statusLabel is not empty while status is default THE callout SHALL ignore it and in debug builds report it. - **CLO-32** WHERE the platform has ARIA attributes (the web), the host carries its note or live region role (CLO-20, CLO-21) itself, so what the product writes on it is not moved, but for a name: WHILE its name (its title, else statusLabel) is not empty THE callout SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that its name (its title, else statusLabel) is its whole name although the platform gives aria-labelledby the precedence, and WHEN its name (its title, else statusLabel) is emptied SHALL give them back as they were written; WHILE its name (its title, else statusLabel) is empty a name the product gives so — aria-label, or aria-labelledby naming an element — SHALL be its name. WHILE it is closed or empty (CLO-13) it exposes nothing, and SHALL hold them as well, giving them back when it is shown. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE callout SHALL take it away. ### Tokens As written in the token documents (DTCG): an alias in braces names the token it takes its value from, which each design system resolves. On the web each token is a CSS custom property: `--tanrei` and the name after `tanrei`, joined by hyphens (`tanrei.comp.callout.…` → `--tanrei-comp-callout-…`). #### `tanrei.comp.callout` | Token | Type | Value | | --- | --- | --- | | `comp.callout.container.padding-block` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.callout.container.padding-inline` | `dimension` | `{tanrei.sys.space.space200}` | | `comp.callout.container.padding-inline-end-with-close` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.callout.container.gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.callout.container.shape` | `dimension` | `{tanrei.sys.shape.corner.medium}` | | `comp.callout.container.color.tonal` | `color` | `{tanrei.sys.color.secondary-container}` | | `comp.callout.container.color.outlined` | `color` | `{"colorSpace":"srgb","components":[0,0,0],"alpha":0,"hex":"#000000"}` | | `comp.callout.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.callout.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.callout.icon.size` | `dimension` | `{tanrei.sys.icon.small}` | | `comp.callout.icon.gap` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.callout.icon.opacity` | `number` | `0.85` | | `comp.callout.icon.color.tonal` | `color` | `{tanrei.comp.callout.body.color.tonal}` | | `comp.callout.icon.color.outlined` | `color` | `{tanrei.sys.color.on-surface-variant}` | | `comp.callout.title.typescale.medium` | `typography` | `{tanrei.sys.typescale.heading-6}` | | `comp.callout.title.typescale.large` | `typography` | `{tanrei.sys.typescale.heading-5}` | | `comp.callout.title.gap` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.callout.title.color.tonal` | `color` | `{tanrei.comp.callout.body.color.tonal}` | | `comp.callout.title.color.outlined` | `color` | `{tanrei.comp.callout.body.color.outlined}` | | `comp.callout.body.typescale.medium` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.callout.body.typescale.large` | `typography` | `{tanrei.sys.typescale.body-large}` | | `comp.callout.body.color.tonal` | `color` | `{tanrei.sys.color.on-secondary-container}` | | `comp.callout.body.color.outlined` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.callout.actions.gap` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.callout.actions.item-gap` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.callout.close-button.variant` | `number` | `1` | | `comp.callout.close-button.size` | `number` | `0` | | `comp.callout.motion.disclosure-duration` | `duration` | `{tanrei.sys.motion.role.disclosure}` | | `comp.callout.motion.disclosure-easing` | `cubicBezier` | `{tanrei.sys.motion.easing.spatial}` | | `comp.callout.info.container.color.tonal` | `color` | `{tanrei.sys.color.info-container}` | | `comp.callout.info.container.color.outlined` | `color` | `{tanrei.comp.callout.container.color.outlined}` | | `comp.callout.info.title.color.tonal` | `color` | `{tanrei.comp.callout.info.body.color.tonal}` | | `comp.callout.info.title.color.outlined` | `color` | `{tanrei.comp.callout.info.body.color.outlined}` | | `comp.callout.info.body.color.tonal` | `color` | `{tanrei.sys.color.on-info-container}` | | `comp.callout.info.body.color.outlined` | `color` | `{tanrei.comp.callout.body.color.outlined}` | | `comp.callout.info.icon.color.tonal` | `color` | `{tanrei.sys.color.info}` | | `comp.callout.info.icon.color.outlined` | `color` | `{tanrei.sys.color.info}` | | `comp.callout.warning.container.color.tonal` | `color` | `{tanrei.sys.color.warning-container}` | | `comp.callout.warning.container.color.outlined` | `color` | `{tanrei.comp.callout.container.color.outlined}` | | `comp.callout.warning.title.color.tonal` | `color` | `{tanrei.comp.callout.warning.body.color.tonal}` | | `comp.callout.warning.title.color.outlined` | `color` | `{tanrei.comp.callout.warning.body.color.outlined}` | | `comp.callout.warning.body.color.tonal` | `color` | `{tanrei.sys.color.on-warning-container}` | | `comp.callout.warning.body.color.outlined` | `color` | `{tanrei.comp.callout.body.color.outlined}` | | `comp.callout.warning.icon.color.tonal` | `color` | `{tanrei.sys.color.warning}` | | `comp.callout.warning.icon.color.outlined` | `color` | `{tanrei.sys.color.warning}` | | `comp.callout.error.container.color.tonal` | `color` | `{tanrei.sys.color.error-container}` | | `comp.callout.error.container.color.outlined` | `color` | `{tanrei.comp.callout.container.color.outlined}` | | `comp.callout.error.title.color.tonal` | `color` | `{tanrei.comp.callout.error.body.color.tonal}` | | `comp.callout.error.title.color.outlined` | `color` | `{tanrei.comp.callout.error.body.color.outlined}` | | `comp.callout.error.body.color.tonal` | `color` | `{tanrei.sys.color.on-error-container}` | | `comp.callout.error.body.color.outlined` | `color` | `{tanrei.comp.callout.body.color.outlined}` | | `comp.callout.error.icon.color.tonal` | `color` | `{tanrei.sys.color.error}` | | `comp.callout.error.icon.color.outlined` | `color` | `{tanrei.sys.color.error}` | | `comp.callout.success.container.color.tonal` | `color` | `{tanrei.sys.color.success-container}` | | `comp.callout.success.container.color.outlined` | `color` | `{tanrei.comp.callout.container.color.outlined}` | | `comp.callout.success.title.color.tonal` | `color` | `{tanrei.comp.callout.success.body.color.tonal}` | | `comp.callout.success.title.color.outlined` | `color` | `{tanrei.comp.callout.success.body.color.outlined}` | | `comp.callout.success.body.color.tonal` | `color` | `{tanrei.sys.color.on-success-container}` | | `comp.callout.success.body.color.outlined` | `color` | `{tanrei.comp.callout.body.color.outlined}` | | `comp.callout.success.icon.color.tonal` | `color` | `{tanrei.sys.color.success}` | | `comp.callout.success.icon.color.outlined` | `color` | `{tanrei.sys.color.success}` | ## Card > Sets a group of related content apart from its background, and can be one action that opens what it shows, or one link to it. - Category: Containment - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/card/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/card.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3-like (Material 3-inspired) (`m3-like`) | Yes | — | ### Platforms - Web: the element ``, registered by importing `@tanrei/web` (or only its own module, `@tanrei/web/components/card`). - React: `Card` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-card` | lagging | | SwiftUI | `TanreiCard` | lagging | | Jetpack Compose | `TanreiCard` | lagging | | Flutter | `TanreiCard` | lagging | | React Native | `Card` | lagging | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `interactive` (prop) | `interactive` | `action` | `onClick` | `onTap` | `onPress` | | `disabled` (prop) | `disabled` | `disabled` | `enabled` | `enabled` | `disabled` | | `href` (prop) | `href` | `destination` | `href` | `href` | `href` | | `targetLabel` (prop) | `targetLabel` | `targetLabel` | `targetLabel` | `targetSemanticLabel` | `targetLabel` | | `inset` (prop) | `flush` | `inset` | `inset` | `inset` | `inset` | | `label` (prop) | `label` | `label` | `contentDescription` | `semanticLabel` | `accessibilityLabel` | | `click` (event) | `click` | `action` | `onClick` | `onTap` | `onPress` | Statuses: `planned` — In the inventory. Nothing shippable exists yet. `lagging` — An implementation of an earlier spec exists; it has not caught up with the current one. `alpha` — Implemented with tests. The API may still change. `beta` — Feature complete and at parity. Only fixes are expected. `stable` — Covered by semantic versioning. `deprecated` — Still shipped; scheduled for removal. ### Anatomy - `container`: The shape that holds the content, clips it to its corners and, for an interactive card, carries hover, focus and press. - `outline` (optional): The border of the outlined variant. - `content`: Whatever the product puts in the card. The card does not lay it out; it only insets it, clips it and hands it a content color. - `focus-ring` (optional): Gap-then-ring indicator shown for keyboard focus of an interactive card. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `variant` | `enum`: `elevated`, `filled`, `outlined` | `"outlined"` | `variant` | How the card separates from its background: by depth (elevated), by tone (filled) or by an edge (outlined). Pick by the background, not by importance. A design system may add values. | | `interactive` | `boolean` | `false` | `interactive` | Makes the whole card one pressable action (it emits click). Its content must then contain no other interactive element. A card whose action is to go somewhere takes href instead and is a link, not a button. | | `disabled` | `boolean` | `false` | `disabled` | Prevents interaction and removes an interactive card or a link card from the focus order. Ignored unless interactive is true or href is set: a card that is neither an action nor a link cannot be disabled. | | `href` | `string` | `""` | `href` | The destination: an address as the platform's links take one (a URL; on the web a path or a fragment as well). Not empty, it makes the whole card one link — a link card — whether interactive is set or not: the link role, one tab stop, activated by pointer, touch or Enter and not by Space, opened by the platform as its own links are, and drawn exactly as an interactive card is (CRD-19, CRD-20). Its content must then contain no other interactive element, as an interactive card's. | | `target` | `enum`: `same`, `new` | `"same"` | `target` | Where the destination opens. same: where the person is — the same tab on the web, the app's own handling of the address elsewhere. new: a new context — a new tab or window on the web, outside the current screen elsewhere — which the card says through targetLabel; the card draws no mark, because its content is the product's (CRD-21). Ignored without href. | | `targetLabel` | `string` | `""` | `target-label` | What assistive technology reads after the link's name while target is new ("opens in a new tab"). Tanrei ships no words of its own, so the product gives them in its own language, as it gives a chip its removeLabel. Required while target is new; ignored otherwise. | | `inset` | `boolean` | `true` | `flush` (turns it off) | Insets the content by the card's padding. Set it to false for content that reaches the card's edges (a photo on top); that content pads its own text. | | `label` | `string` | `""` | `label` | The accessible name. For an interactive card or a link card, normally the text of its heading; without it the whole content becomes the name. For a card that is neither, a label makes it a named group. | ### Events | Event | Description | | --- | --- | | `click` | An interactive card or a link card was activated by pointer, touch, keyboard or assistive technology. A link card emits it before its destination opens; a product that takes the navigation itself (a client-side router) cancels it (CRD-20). | ### Slots | Slot | Description | | --- | --- | | `default` | The content: any layout of media, text and — only when interactive is false and href is empty — actions. | ### States `enabled`, `disabled`, `hovered`, `focused`, `pressed` ### Accessibility - Role: `button (link while href is set)` - Labeling: The role is button while interactive is true and link while href is set; otherwise the card has no role, or is a group when label is set. An interactive card's or a link card's name is label — normally its heading's text — or, without one, its whole content read as one string (reported in debug builds). Their content is presentational: its headings and images are read as part of the name, not as separate elements. While target is new, targetLabel is a link card's description. - Minimum target size: yes | Keys | Action | | --- | --- | | Tab | Moves focus to an interactive card or a link card. A card that is neither is not a tab stop; focus moves through its content. | | Enter or Space | Activates an interactive card. A link card is activated by Enter alone: Space does what it does on any link (on the web it scrolls the page). | - Never nest interactive elements in an interactive card or a link card: assistive technology cannot reach them (the card is one element) and a press on them would also activate the card. A card that needs its own buttons or links stays plain, and its primary action or destination is one of them: a heading that is a link, or a link Button. - Web: an interactive card draws a shadow element with role button and tabindex 0 around the slot (not a \