--- title: "色块" description: "以样本显示一种颜色，并在旁边写出它的名称。样本就是这种颜色本身；颜色半透明时，下面垫着棋盘格；样本带一道边线，与表面相近的颜色也看得出到哪里为止。它是用来看的样本，从不是控件，也从不是选择器。" url: "https://tanrei.chnotchy.com/zh-cn/components/swatch/" last_updated: 2026-10-23T21:17:12.000Z --- # 色块 > 以样本显示一种颜色，并在旁边写出它的名称。样本就是这种颜色本身；颜色半透明时，下面垫着棋盘格；样本带一道边线，与表面相近的颜色也看得出到哪里为止。它是用来看的样本，从不是控件，也从不是选择器。 ## 概览 色块显示一种不在编辑中的颜色：设置页里的品牌色、写在标签旁边的那个标签的颜色、并排列出的主题角色。它按给定的值原样绘制颜色，并在旁边写出颜色的名称，因为单凭样本永远说不清一种颜色。它从不响应指针、按键或焦点。 在 Web 上它是 ``。其他平台尚未实现。 ### 用法 **Web** ```html #0f766e ``` **React** ```tsx import { Swatch } from '@tanrei/react'; ``` ## 规格 - Category: Communication - Level: base - Listing: default - Page: https://tanrei.chnotchy.com/components/swatch/ - Spec: https://github.com/chnotchy/tanrei/blob/main/specs/swatch.spec.json ### Availability | Design system | Has it | Notes | | --- | --- | --- | | Tanrei (`tanrei`) | Yes | — | | Cupertino (Apple HIG-inspired) (`cupertino`) | Yes | — | | M3 Expressive-like (Material 3 Expressive-inspired) (`m3-expressive-like`) | 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/swatch`). - React: `Swatch` from `@tanrei/react`. | Platform | Name | Status | | --- | --- | --- | | Web | `tanrei-swatch` | alpha | | SwiftUI | `TanreiSwatch` | planned | | Jetpack Compose | `TanreiSwatch` | planned | | Flutter | `TanreiSwatch` | planned | | React Native | `Swatch` | planned | Names a platform gives in its own idiom: | Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native | | --- | --- | --- | --- | --- | --- | | `decorative` (prop) | `decorative` | `isDecorative` | `decorative` | `decorative` | `decorative` | 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 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. - `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. - `fill` (optional): The color itself, exactly as given, over the checkerboard. - `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. - `label` (optional): The color's name, beside the sample: what the color is called where it is shown ("Teal 700", "Primary", "Bug"). - `supporting-text` (optional): A line under the name: the color's value, the token it comes from, or where it is used. ### Props | Prop | Type | Default | Web attribute | Description | | --- | --- | --- | --- | --- | | `color` | `string` | `""` | `color` | 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` | `""` | `label` | 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` | `""` | `supporting-text` | 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` | `label-hidden` | 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` | `decorative` | 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` | `enum`: `small`, `medium`, `large` | `"medium"` | `size` | 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` | `enum`: `square`, `circle` | `"square"` | `shape` | 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 `enabled` ### Accessibility - 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 size: yes - 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. ### Behaviour Requirements in EARS form, each with its stable id. - **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. ### 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.swatch.…` → `--tanrei-comp-swatch-…`). #### `tanrei.comp.swatch` | Token | Type | Value | | --- | --- | --- | | `comp.swatch.container.size.small` | `dimension` | `16px` | | `comp.swatch.container.size.medium` | `dimension` | `24px` | | `comp.swatch.container.size.large` | `dimension` | `32px` | | `comp.swatch.container.shape.square` | `dimension` | `{tanrei.sys.shape.corner.extra-small}` | | `comp.swatch.container.shape.circle` | `dimension` | `{tanrei.sys.shape.corner.full}` | | `comp.swatch.checkerboard.color` | `color` | `{tanrei.sys.color.surface}` | | `comp.swatch.checkerboard.alternate-color` | `color` | `{tanrei.sys.color.surface-container-highest}` | | `comp.swatch.checkerboard.size` | `dimension` | `4px` | | `comp.swatch.outline.width` | `dimension` | `{tanrei.sys.border.hairline}` | | `comp.swatch.outline.color` | `color` | `{tanrei.sys.color.outline-variant}` | | `comp.swatch.gap.small` | `dimension` | `{tanrei.sys.space.space50}` | | `comp.swatch.gap.medium` | `dimension` | `{tanrei.sys.space.space100}` | | `comp.swatch.gap.large` | `dimension` | `{tanrei.sys.space.space150}` | | `comp.swatch.label.typescale.small` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.swatch.label.typescale.medium` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.swatch.label.typescale.large` | `typography` | `{tanrei.sys.typescale.body}` | | `comp.swatch.label.color` | `color` | `{tanrei.sys.color.on-surface}` | | `comp.swatch.supporting-text.typescale.small` | `typography` | `{tanrei.sys.typescale.caption}` | | `comp.swatch.supporting-text.typescale.medium` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.swatch.supporting-text.typescale.large` | `typography` | `{tanrei.sys.typescale.body-small}` | | `comp.swatch.supporting-text.color` | `color` | `{tanrei.sys.color.on-surface-variant}` | ## 指南 ### 何时使用 凡是显示颜色而不改变它的地方，都使用色块：调色板、主题概览、用户给标签或日历设定的颜色、图例。它是一张配有文字的颜色图片，仅此而已。 | 你需要 | 使用 | | --- | --- | | 可以键入、粘贴或选取的颜色 | [颜色字段](https://tanrei.chnotchy.com/zh-cn/components/color-field/)；在已经写出颜色名称的行里，用[颜色输入框](https://tanrei.chnotchy.com/zh-cn/components/color-input/)。 | | 通向某处或打开某样东西的颜色 | 里面放着色块的[链接](https://tanrei.chnotchy.com/zh-cn/components/link/)或[按钮](https://tanrei.chnotchy.com/zh-cn/components/button/)。 | | 从一组颜色中选出的一种颜色 | 不是这个组件：从一组色块中选中其一，那是选择器，它有一个值，按键与单选组相同。在 Tanrei 提供它之前，请使用[单选组](https://tanrei.chnotchy.com/zh-cn/components/radio-group/)，在每个选项的名称旁边各放一个装饰性的色块。 | | 语义状态（错误、成功） | [Tag](https://tanrei.chnotchy.com/zh-cn/components/tag/) 或[提示块](https://tanrei.chnotchy.com/zh-cn/components/callout/)：状态要用文字说出，颜色只是对文字的补充。 | ### 它绘制什么 - **颜色本身，分毫不差。** 不往里混入任何东西：没有色调叠加，没有状态，也不随浅色或深色变化。希望色块跟随主题时，给出角色的自定义属性（`var(--tanrei-sys-color-primary)`）；要显示某个固定值时，就给出那个值。 - **下面垫着棋盘格。** 半透明的颜色会透出棋盘格，一看就知道是半透明的。不透明的颜色会把它完全盖住。 - **一道边线。** 沿样本边缘的内侧画一条细线，颜色与分隔线相同，所以白色页面上的白色，或与表面相近的颜色，也看得出到哪里为止。 - **无颜色。** `color` 为空时只画边线。请在标签里说明它的含义（“无颜色”“继承”）。 每个平台都能读取十六进制写法：`#0f766e`，带 alpha 时是 `#0f766e80`。在 Web 上，任何 CSS 颜色也都可以。 ### 尺寸和形状 | `size` | 边长 | 用于 | | --- | --- | --- | | `small` | 16 | 一行小号文本的旁边：表格单元格、紧凑的行、图例。 | | `medium`（默认） | 24 | 一行正文的旁边：列表中的一行、一项设置。 | | `large` | 32 | 颜色本身就是观看对象的地方：调色板、主题概览。 | | `shape` | 用于 | | --- | --- | | `square`（默认） | 一块颜色：调色板、主题。 | | `circle` | 用颜色给别的东西做标记的圆点：标签、日历、图表中的一个系列。 | 名称和辅助文本随尺寸变化。 ### 名称 按你的产品里人们对这种颜色的叫法来写名称：“青绿 700”“主色”“缺陷”。`#0f766e` 这样的值不是名称，所以把它放在名称下方的 `supportingText` 里。色块从不根据颜色生成名称：一种颜色叫什么，取决于语言，也取决于产品。 ### 推荐 - 给每个色块一个 `label`，有空间的地方就让它保持可见。 - 色块位于写着同一个名称或值的文本旁边时，给它设置 `decorative`。 - 人们可能复制或比较的值，放在 `supportingText` 里。 ### 避免 - 不要在色块上放处理函数。把它放进链接或按钮，它们才有各种状态和焦点指示。 - 不要只靠颜色说明某样东西是什么。这要由名称来说明。 - 不要用色块加上你自己的处理函数拼出一个颜色选择器。 ## 无障碍 ### 组件负责的部分 - 画出名称时，色块就是那段文本：先是名称，然后是辅助文本，在色块所在的位置朗读。样本是隐藏的，因为文字已经说明了它。 - 设置 `labelHidden` 时，它是一张由 `label` 命名、由 `supportingText` 描述的图像。 - 设置 `decorative` 后，它对辅助技术隐藏，也不绘制任何文本。 - 既没有标签也没有辅助文本的色块会被隐藏，并在调试构建中报告。 - 它不接受任何输入，也不接受焦点，所以不在焦点顺序中增加停靠点。在链接或按钮里面时，它暴露出来的是该元素的名称。 - 文本放大时，样本像图标一样保持大小，旁边的文本随之变大。 - 在强制颜色模式下，颜色保持不变，因为它就是内容；边线改用文本颜色。 - 在从右到左的布局中，样本位于右侧。`#0f766e` 这样的值保持原有顺序。 ### 需要你做的事 - 为每个色块决定它是有名称的，还是装饰性的。规则是：如果删掉这个色块会丢掉一个名称，它就是有名称的；否则就是装饰性的。 - 尽量使用可见的名称，而不是 `labelHidden`。隐藏的名称能把颜色告诉辅助技术，却告诉不了看得见样本、但分不清它和相邻样本的人。没有空间时，在放着色块的元素上用工具提示，在需要时显示名称。 - 检查你画在所显示颜色上的任何文本的对比度。色块只负责显示颜色，不负责检查颜色。