Swatch
Shows a color as a sample with its name beside it. The sample is exactly the color, over a checkerboard where the color is translucent, and edged so that a color close to the surface still shows where it ends. A sample to look at, never a control and never a picker.
- Category
- Communication
- Tokens
comp.swatch- Level
- Base
- Web
tanrei-swatchclock_loader_40 - SwiftUI
TanreiSwatchradio_button_unchecked - Jetpack Compose
TanreiSwatchradio_button_unchecked - Flutter
TanreiSwatchradio_button_unchecked - React Native
Swatchradio_button_unchecked
Generated from docs/status/status.json, specs/swatch.spec.json
A color with its value, a role of the theme, a translucent color and a dot
A swatch shows a color that is not being edited: a brand color in a settings page, the color of a label beside the label, the roles of a theme side by side. It draws the color exactly as given and the color’s name beside it, because a color is never told by its sample alone. It never answers a pointer, a key or focus.
On the web it is <tanrei-swatch>. The other platforms have not implemented it yet.
<!-- The name beside the sample, and the value under it. -->
<tanrei-swatch color="#0f766e" label="Teal 700" supporting-text="#0f766e"></tanrei-swatch>
<!-- A role of the current theme: the swatch follows the scheme because the custom property does. -->
<tanrei-swatch color="var(--tanrei-sys-color-primary)" label="Primary"></tanrei-swatch>
<!-- No room for the name: the sample alone, named for assistive technology. -->
<tanrei-swatch color="#e11d48" label="Bug" shape="circle" size="small" label-hidden></tanrei-swatch>
<!-- Beside the same value in text: decorative, so it is read once. -->
<td><tanrei-swatch decorative size="small" color="#0f766e"></tanrei-swatch> #0f766e</td>
<script type="module">
import '@tanrei/web/components/swatch';
</script>import { Swatch } from '@tanrei/react';
<Swatch color={label.color} label={label.name} shape="circle" size="small" />
<Swatch color="#0f766e" label="Teal 700" supportingText="#0f766e" />Three sizes, two shapes, and an empty swatch
Anatomy
| Part | Description |
|---|---|
1 container | The sample: a square box of the swatch's size, clipped to a rounded square or to a circle. It carries no state: nothing about it answers a pointer, a press or focus. |
2 checkerboard · optional | Squares of two quiet colors under the color, filling the sample. A color that lets what is behind it through shows them; an opaque color covers them entirely. |
3 fill · optional | The color itself, exactly as given, over the checkerboard. |
4 outline | One hairline inside the sample's edge, drawn over the color and following its shape, so that a color close to the surface around it still shows where it ends. An empty swatch draws it alone. |
5 label · optional | The color's name, beside the sample: what the color is called where it is shown ("Teal 700", "Primary", "Bug"). |
6 supporting-text · optional | A line under the name: the color's value, the token it comes from, or where it is used. |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
color | string | "" | The color the sample shows: in every platform a number sign and three, four, six or eight hexadecimal digits in sRGB, either case (#0f766e; the fourth or the last two the alpha, #0f766e80); on the web also any CSS color, a custom property included (var(--tanrei-sys-color-primary)); on a native platform also the platform's own color. Empty shows no color: the edge alone. |
label | string | "" | The color's name, in the product's words ("Teal 700", "Primary", "Bug"). Drawn beside the sample, and what assistive technology reads; while labelHidden is true it is the sample's accessible name and is not drawn. The value of the color is not a name: put it in supportingText. |
supportingText | string | "" | A line under the name: the color's value ("#0f766e"), the token it comes from, or where it is used. Drawn under the label and read after it; while labelHidden is true it is the sample's accessible description and is not drawn. |
labelHidden | boolean | false | True draws the sample alone, for a place with no room for text (a row of dots): the label becomes the sample's accessible name and supportingText its description, so the color is still told to assistive technology, though not to a person who sees the sample and cannot tell its color. Prefer a visible label. |
decorative | boolean | false | True draws the sample alone and hides the swatch from assistive technology, for a swatch that stands beside the same name or value in visible text (a table cell that already says "#0f766e", a list row titled "Teal 700"), so the name is read once. label and supportingText are then neither drawn nor read. |
size | small | medium | large | "medium" | Small (16) stands beside one line of small text: a table cell, a dense row, a legend. Medium (24) beside a line of body text: a list row, a setting. Large (32) where the color itself is looked at: a palette, a theme's overview. The text beside the sample follows the size. A design system may add values. |
shape | square | circle | "square" | Square, a slightly rounded square, is a tile of the color. Circle is a dot: a color that marks something else (a label's color, a series in a legend). A design system may add values. |
States
Behavior
Requirements in EARS form. Every platform implementation is tested against these ids.
| ID | Requirement |
|---|---|
SWC-1 | THE swatch SHALL draw its sample as a square box whose side is the container size of its size (comp.swatch.container.size.small for small, comp.swatch.container.size.medium for medium, comp.swatch.container.size.large for large), with the corners of its shape (comp.swatch.container.shape.square for square, comp.swatch.container.shape.circle for circle), 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, and SHALL clip everything the sample draws to that shape. THE swatch SHALL lay itself out inline with the text or the row it is placed in, its sample one box that the layout neither stretches nor shrinks, and SHALL draw no elevation. |
SWC-2 | WHILE color is a color THE swatch SHALL fill its sample with exactly that color, in sRGB, its alpha included, over the checkerboard (SWC-3), and SHALL mix nothing into the fill: no state layer, no tint, no opacity of its own, no elevation, and no change with the scheme, the contrast level or the design system — the swatch shows the color it is given, and a product that wants a color of the current scheme gives it that role's value. |
SWC-3 | WHILE color is a color THE swatch SHALL draw under the fill, across the whole sample and clipped to its shape, a checkerboard of squares of side comp.swatch.checkerboard.size, alternately comp.swatch.checkerboard.color and comp.swatch.checkerboard.alternate-color, the square at the sample's top-left corner in comp.swatch.checkerboard.color in every layout direction, so that a color that lets what is behind it through is shown as such and an opaque color covers the checkerboard entirely. |
SWC-4 | THE swatch SHALL edge its sample, inside its size and following its shape, with a line comp.swatch.outline.width wide in comp.swatch.outline.color, drawn over the fill, whatever the color: so that a color close to the surface around it — white on a light surface — still shows where it ends. |
SWC-5 | WHILE color is empty THE swatch SHALL draw no fill and no checkerboard, the surface showing through the sample, and the edge of SWC-4, which is then all the sample draws; its label and supporting text SHALL be drawn and read as for any color. |
SWC-6 | THE swatch SHALL read color as a number sign followed by three, four, six or eight hexadecimal digits in either case, with white space before and after it left out, in sRGB — red, green and blue, and where there are four or eight digits the last digit or pair the alpha — as CSS reads that notation (#0f766e80 is the teal at half opacity, #fff white); on the web it SHALL also take any CSS color value, a reference to a custom property included, and draw it as the browser resolves it where the swatch stands, and on a native platform also the platform's own color. IF color is not empty and reads as no color THE swatch SHALL draw as for an empty color (SWC-5) and in debug builds report the value. |
SWC-7 | WHILE labelHidden and decorative are false and label or supportingText is not empty THE swatch SHALL draw beside its sample, comp.swatch.gap.small after it for size small (and so on for each size), one column of text: label in comp.swatch.label.typescale.small for size small (and so on for each size) and comp.swatch.label.color, and under it supportingText in comp.swatch.supporting-text.typescale.small for size small (and so on) and comp.swatch.supporting-text.color, each drawn only where it is not empty. THE swatch SHALL centre the sample and the column of text on each other vertically, SHALL be as wide as its sample, the gap and its longest line, and no wider, and WHERE the place it stands in is narrower SHALL wrap each text at word boundaries rather than cut it, keeping the sample whole. Each text SHALL be laid out in its own direction, isolated from the text around it, so that a value such as #0f766e keeps its order in a right-to-left layout. |
SWC-8 | WHILE labelHidden is true or decorative is true THE swatch SHALL draw its sample alone, with no text and no gap beside it, and SHALL be exactly as large as its sample. |
SWC-9 | WHILE the swatch draws its text (SWC-7) THE swatch SHALL keep its sample from assistive technology and expose its label and then its supportingText as text, in that order, read where the swatch stands, with no role of its own: the color is told by the words, which every person reads, and the sample adds nothing a word does not say. |
SWC-10 | WHILE labelHidden is true and decorative is false THE swatch SHALL be exposed to assistive technology as one image named by label — by supportingText where label is empty — and described by supportingText where label names it, and SHALL expose nothing else: not the color's value unless the product wrote it, not its size or its shape. |
SWC-11 | WHILE decorative is true THE swatch SHALL expose nothing to assistive technology, and SHALL neither draw nor read label and supportingText. |
SWC-12 | IF decorative is false, label and supportingText are both empty and the product gives it no name (SWC-20) THE swatch SHALL draw its sample alone, expose nothing to assistive technology, and in debug builds report that a color is shown without a name: a sample alone tells its color to no one who cannot see it or tell it from another. |
SWC-13 | THE swatch 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. WHERE the swatch is placed inside an element that takes input (a link, a Button, a list item, a chip, a menu item) THE swatch SHALL let input over it reach that element, stay as it is drawn while that element is hovered, focused or pressed, and add what it exposes (SWC-9, SWC-10) to that element's content in reading order. A swatch that is chosen from a set is a picker's, not this component's. |
SWC-14 | WHEN color, label, supportingText, labelHidden, decorative, size or shape changes THE swatch SHALL draw and expose the new value at once, without a motion, and SHALL NOT announce the change by itself. |
SWC-15 | WHILE the text size is enlarged THE swatch SHALL keep its sample at the container size of its size and let its label and supportingText follow their text styles as they grow, the sample staying centred on the column of text (SWC-7): a sample is a picture of a color and is enlarged with the page, not with the text. |
SWC-16 | 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 swatch SHALL keep its fill and its checkerboard out of the forced palette, because the color is the content the swatch shows and not a decoration of it, SHALL draw its edge in the platform's text color so that the sample is bounded on any background, and its label and supportingText in the platform's text color. |
SWC-17 | WHERE the layout direction is right-to-left THE swatch SHALL draw its sample at the start, the right, and its text after it, to the left, with the gap applied by logical start and end, and SHALL mirror no drawing of its own: the checkerboard starts at the sample's top-left corner in every direction (SWC-3), and each text keeps its own direction (SWC-7). |
SWC-18 | THE swatch 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 swatch is shown THE swatch SHALL draw itself for the new direction at once, without a motion of its own, keeping what it shows. |
SWC-19 | WHEN size or shape names a value that the active design system does not have THE swatch SHALL render with the default value's tokens, and in debug builds report the unknown value. |
SWC-20 | WHERE the platform has ARIA attributes (the web), the host carries its image role while it is one (SWC-10) itself, so what the product writes on it is not moved, but for a name: WHILE its name (label, or supportingText where label is empty) is not empty THE swatch SHALL hold the product's aria-label and aria-labelledby on that host as their data-aria- twins, so that its name (label, or supportingText where label is empty) is its whole name although the platform gives aria-labelledby the precedence, and WHEN its name (label, or supportingText where label is empty) is emptied SHALL give them back as they were written; WHILE its name (label, or supportingText where label is empty) 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 (SWC-12). WHILE decorative is false and it draws its sample alone — labelHidden is true, or it has no text to draw — and it has no name of its own, a name the product gives so SHALL make it one image named by that name, as SWC-10 says of its own: an image the product names is a named image. WHILE it draws its text (SWC-9) or is decorative (SWC-11) it has no role, and SHALL hold them as well, giving them back when it is an image again. WHEN the product removes one, or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaLabelledByElements) to null, THE swatch SHALL take it away. |
Platform name mapping
Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.
| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| Component | tanrei-swatch | TanreiSwatch | TanreiSwatch | TanreiSwatch | Swatch |
color · Property | color | color | color | color | color |
label · Property | label | label | label | label | label |
supportingText · Property | supportingText | supportingText | supportingText | supportingText | supportingText |
labelHidden · Property | labelHidden | labelHidden | labelHidden | labelHidden | labelHidden |
decorative · Property | decorative | isDecorative | decorative | decorative | decorative |
size · Property | size | size | size | size | size |
shape · Property | shape | shape | shape | shape | shape |
| Notes | <tanrei-swatch color="#0f766e" label="Teal 700" supporting-text="#0f766e" size shape label-hidden decorative>. The host is display: inline-flex, vertical-align: middle, with no tabindex, no listeners and pointer-events left as they are (SWC-13). The sample is a span in the shadow root whose background is two layers: the color as a linear-gradient of one color over a conic-gradient checkerboard, both clipped by the shared corner rule; the edge is an inset box-shadow, drawn over the background. color is set as a custom property through style.setProperty, so any CSS color the browser resolves where the swatch stands is drawn (var(--tanrei-sys-color-primary) included), and a value CSS.supports('color', …) refuses is drawn as empty (SWC-6). The sample is aria-hidden while the text is drawn; while label-hidden it is role="img" with aria-label and aria-description; while decorative or nameless the host is aria-hidden. Under forced-colors: active the sample keeps forced-color-adjust: none and takes a CanvasText edge (SWC-16). | TanreiSwatch(_ label: String, color: Color?, supportingText:, size:, shape:, labelHidden:, isDecorative:), with an initializer that takes the hexadecimal string of SWC-6. allowsHitTesting(false). With its text, one element that combines its children; with labelHidden, an element with the image trait and the label; decorative, accessibilityHidden(true). | TanreiSwatch(color: Color?, label, supportingText, size, shape, labelHidden, decorative), with an overload that takes the hexadecimal string of SWC-6. No clickable and no focusable modifier; with labelHidden, semantics Role.Image with the label as contentDescription; decorative, clearAndSetSemantics {}. | TanreiSwatch(color: Color?, label:, supportingText:, size:, shape:, labelHidden:, decorative:), with TanreiSwatch.hex(…) for the string of SWC-6. Wrapped in IgnorePointer; with labelHidden, Semantics(image: true, label:) over an excluded sample; decorative, ExcludeSemantics. | <Swatch color="#0f766e" label="Teal 700" supportingText="#0f766e" />; color is any color React Native parses. pointerEvents="none"; with labelHidden, accessibilityRole="image" with the label as accessibilityLabel; decorative, accessible={false} with importantForAccessibility="no-hide-descendants". |
Tokens
| Token | Aliases | Resolved (light) |
|---|---|---|
--tanrei-comp-swatch-checkerboard-alternate-color | sys.color.surface-container-highest | |
--tanrei-comp-swatch-checkerboard-color | sys.color.surface | |
--tanrei-comp-swatch-checkerboard-size | — | 4px |
--tanrei-comp-swatch-container-shape-circle | sys.shape.corner.full | 9999px |
--tanrei-comp-swatch-container-shape-square | sys.shape.corner.extra-small | 3px |
--tanrei-comp-swatch-container-size-large | — | 32px |
--tanrei-comp-swatch-container-size-medium | — | 24px |
--tanrei-comp-swatch-container-size-small | — | 16px |
--tanrei-comp-swatch-gap-large | sys.space.space150 | 12px |
--tanrei-comp-swatch-gap-medium | sys.space.space100 | 8px |
--tanrei-comp-swatch-gap-small | sys.space.space50 | 4px |
--tanrei-comp-swatch-label-color | sys.color.on-surface | |
--tanrei-comp-swatch-outline-color | sys.color.outline-variant | |
--tanrei-comp-swatch-outline-width | sys.border.hairline | 1px |
--tanrei-comp-swatch-supporting-text-color | sys.color.on-surface-variant | |
--tanrei-comp-swatch-label-typescale-large | sys.typescale.body | 400 14px/1.5714 |
--tanrei-comp-swatch-label-typescale-medium | sys.typescale.body | 400 14px/1.5714 |
--tanrei-comp-swatch-label-typescale-small | sys.typescale.body-small | 400 13px/1.5385 |
--tanrei-comp-swatch-supporting-text-typescale-large | sys.typescale.body-small | 400 13px/1.5385 |
--tanrei-comp-swatch-supporting-text-typescale-medium | sys.typescale.body-small | 400 13px/1.5385 |
--tanrei-comp-swatch-supporting-text-typescale-small | sys.typescale.caption | 500 11px/1.4545 |
Fixtures
Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.
size: small (2)
small
color: #0f766e label: Teal 700 supportingText: #0f766e size: small dot
color: #e11d48 label: Bug labelHidden: true size: small shape: circle size: medium (9)
default
color: #0f766e label: Teal 700 supportingText: #0f766e label-only
color: #7c3aed label: Violet circle
color: #e11d48 label: Bug shape: circle translucent
color: #0f766e80 label: Teal 700 at half opacity supportingText: #0f766e80 near-surface
color: #ffffff label: White supportingText: #ffffff empty
color: label: No color label-hidden
color: #0f766e label: Teal 700 supportingText: #0f766e labelHidden: true decorative
color: #0f766e label: Teal 700 decorative: true rtl
color: #0f766e label: أخضر مزرق supportingText: #0f766e direction: rtl size: large (1)
large
color: #0f766e label: Teal 700 supportingText: #0f766e size: large Generated from specs/swatch.spec.json, tokens/comp/swatch.tokens.json, design/tokens/
Use a swatch wherever a color is shown and not changed: a palette, a theme’s overview, the color a person gave a label or a calendar, a legend. It is a picture of a color with words, and nothing more.
| You need | Use |
|---|---|
| A color a person can type, paste or pick | A color field, or a color input in a row that already names it. |
| A color that leads somewhere or opens something | A link or a button that holds the swatch. |
| One color chosen from a set of colors | Not this component: a set of swatches of which one is chosen is a picker, with a value and the keys of a radio group. Until Tanrei has one, use a radio group whose options each hold a decorative swatch beside their name. |
| A status (error, success) | A tag or a callout: words say a status, a color only adds to them. |
- The color, exactly. Nothing is mixed into it: no tint, no state, no change with light or dark. Give a role’s custom property (
var(--tanrei-sys-color-primary)) where the swatch should follow the theme, and a fixed value where it shows that value. - A checkerboard under it. A translucent color shows the checkerboard through it, so it reads as translucent. An opaque color covers it.
- An edge. One hairline inside the sample’s edge, in the divider’s color, so that white on a white page, or a color close to the surface, still shows where it ends.
- No color. An empty
colordraws the edge alone. Say what that means in the label (“No color”, “Inherited”).
Every platform reads the hexadecimal notation: #0f766e, and with an alpha #0f766e80. On the web any CSS color works too.
size |
Side | Use for |
|---|---|---|
small |
16 | Beside one line of small text: a table cell, a dense row, a legend. |
medium (default) |
24 | Beside a line of body text: a row of a list, a setting. |
large |
32 | Where the color itself is looked at: a palette, a theme’s overview. |
shape |
Use for |
|---|---|
square (default) |
A tile of the color: a palette, a theme. |
circle |
A dot that marks something else with a color: a label, a calendar, a series in a chart. |
The name and the supporting text follow the size.
Write the color’s name as people in your product call it: “Teal 700”, “Primary”, “Bug”. A value such as #0f766e is not a name, so put it in supportingText under the name. The swatch never makes a name from the color: what a color is called depends on the language and on the product.
- Give every swatch a
label, and leave it visible where there is room. - Set
decorativeon a swatch that stands beside the same name or value in text. - Put a value people may copy or compare in
supportingText.
- Don’t put a handler on a swatch. Put it in a link or a button, which has the states and the focus indicator.
- Don’t rely on the color alone to say what something is. The name does that.
- Don’t build a color picker out of swatches with handlers of your own.
- Role
img- Labeling
- A swatch with its name drawn beside it is text: the sample is hidden and the label, then the supporting text, are read where the swatch stands. A swatch whose label is hidden is one image named by the label and described by the supporting text. A decorative swatch, beside the same name in text, is hidden. A swatch with neither a label nor supporting text is hidden and reported. The color's value is never turned into words by the swatch: a color's name is the product's, in the product's language.
- Minimum target
- The hit area meets the minimum target size even when the visual size is smaller. minimum 32px · pointer 44px · spacing 8px · touch 48px
Keyboard
| Keys | Action |
|---|
Notes
- Not interactive: the swatch takes no input and no focus (SWC-13), so there is no target to size and minimumTarget holds trivially. A swatch that is pressed is inside a link or a Button, which meets the minimum target by its own spec.
- Use of color (WCAG 1.4.1): a sample alone tells a color only to a person who can see it and tell it from its neighbours. The name drawn beside it tells everyone, which is why the label is drawn by default; a hidden label (labelHidden) still names the color to assistive technology, but not to a person with a color vision deficiency who sees the sample. Where there is no room for the name, the product shows it on demand (a tooltip on the element that holds the swatch).
- Non-text contrast (WCAG 1.4.11): the swatch's meaning is carried by its text, so the sample's edge is not a graphical object required to understand the content and is not held to 3:1; it is the divider's hairline (outline-variant), which raised-contrast schemes strengthen, and it keeps a color close to the surface from disappearing into it.
- Decorative or named is the product's decision and cannot be seen from the swatch: beside "#0f766e" in text, a named swatch would be read as "Teal 700, #0f766e" twice. The rule the docs page gives: if deleting the swatch loses a name, it is named; otherwise it is decorative.
- Contrast in the default system: the label is on-surface and the supporting text on-surface-variant, pairs the token invariants hold to 4.5:1 on every surface tone. The sample's own color is the product's and is not checked: it is content, as a picture is.
- Not a picker: a set of swatches of which one is chosen is a selection control with roles, keys and a value of its own (a radio group or a listbox of colors), which this component does not provide and does not imitate.
Generated from specs/swatch.spec.json, tokens/sys/measure.tokens.json
- With its name drawn, the swatch is that text: the name, then the supporting text, read where the swatch stands. The sample is hidden, because the words already say it.
- With
labelHidden, it is one image named bylabeland described bysupportingText. - With
decorative, it is hidden from assistive technology and draws no text. - A swatch with neither a label nor supporting text is hidden and reported in debug builds.
- It takes no input and no focus, so it adds no stop to the focus order. Inside a link or a button, what it exposes is that element’s name.
- With enlarged text the sample keeps its size, as an icon does, and the text grows beside it.
- In forced-colors mode the color is kept, because it is the content, and the edge takes the text color.
- In a right-to-left layout the sample is at the right. A value such as
#0f766ekeeps its order.
- Decide for each swatch whether it is named or decorative. The rule: if deleting the swatch loses a name, it is named. Otherwise it is decorative.
- Prefer a visible name to
labelHidden. A hidden name tells assistive technology the color, but not a person who sees the sample and cannot tell it from its neighbour. Where there is no room, show the name on demand, in a tooltip on the element that holds the swatch. - Check the contrast of any text you draw on the colors you show. The swatch shows colors; it does not check them.