--- title: "色見本" description: "色を見本として示し、その横に名前を添えます。見本は色そのままで、半透明の色は市松模様の上に描き、縁取りがあるのでサーフェスに近い色でもどこで終わるかが分かります。見て確かめるための見本であり、コントロールでもピッカーでもありません。" url: "https://tanrei.chnotchy.com/ja/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/ja/components/color-field/)。色の名前をすでに示している行では[カラー入力欄](https://tanrei.chnotchy.com/ja/components/color-input/)。 | | どこかへ移動する色、何かを開く色 | 色見本を入れた[リンク](https://tanrei.chnotchy.com/ja/components/link/)か[ボタン](https://tanrei.chnotchy.com/ja/components/button/)。 | | 色の集まりから選ぶ 1 つの色 | このコンポーネントではありません。1 つを選ぶ色見本の集まりはピッカーで、値を持ち、ラジオグループのキー操作をします。Tanrei にそれが加わるまでは、選択肢ごとに名前の横へ装飾の色見本を置いた[ラジオグループ](https://tanrei.chnotchy.com/ja/components/radio-group/)を使います。 | | 状態（エラー、成功） | [タグ](https://tanrei.chnotchy.com/ja/components/tag/)か[コールアウト](https://tanrei.chnotchy.com/ja/components/callout/)。状態は言葉で伝え、色はそれに添えるだけです。 | ### 描くもの - **色そのもの。** 何も混ぜません。ティントも、状態による変化も、ライトとダークによる変化もありません。テーマに従わせたい色見本にはロールのカスタムプロパティ（`var(--tanrei-sys-color-primary)`）を、その値自体を示す色見本には固定の値を渡します。 - **下に敷く市松模様。** 半透明の色は市松模様が透けて見えるので、半透明であることが分かります。不透明な色は市松模様を覆い隠します。 - **縁。** 見本の端の内側に、区切り線の色の細い線を 1 本描きます。白いページの上の白や、サーフェスに近い色でも、どこで終わるかが分かります。 - **色なし。** `color` が空なら、縁だけを描きます。それが何を意味するかは、ラベルで伝えます（「色なし」「継承」）。 どのプラットフォームも 16 進数の表記を読みます。`#0f766e`、アルファ付きなら `#0f766e80` です。Web では、どの CSS の色も使えます。 ### サイズと形 | `size` | 辺の長さ | 用途 | | --- | --- | --- | | `small` | 16 | 小さなテキスト 1 行の隣。表のセル、密な行、凡例など。 | | `medium`（既定） | 24 | 本文 1 行の隣。リストの行、設定など。 | | `large` | 32 | 色そのものを見る場所。パレット、テーマの概要など。 | | `shape` | 用途 | | --- | --- | | `square`（既定） | 色のタイル。パレット、テーマ。 | | `circle` | ほかのものに色で印を付けるドット。ラベル、カレンダー、グラフの系列。 | 名前と補足テキストも、サイズに合わせて変わります。 ### 名前 色の名前は、プロダクトで人がその色を呼ぶとおりに書きます。「ティール 700」「プライマリ」「バグ」などです。`#0f766e` のような値は名前ではないので、名前の下の `supportingText` に入れます。色見本は、色から名前を作りません。色を何と呼ぶかは、言語とプロダクトによって変わるからです。 ### 推奨 - どの色見本にも `label` を指定し、場所があるところでは表示したままにします。 - テキストで書いた同じ名前や値の隣に置く色見本には、`decorative` を付けます。 - 利用者がコピーしたり比べたりする値は、`supportingText` に入れます。 ### 非推奨 - 色見本にハンドラーを付けない。リンクかボタンの中に入れます。状態とフォーカスインジケーターを持つのはそちらです。 - 何であるかを色だけで伝えない。それを伝えるのは名前です。 - プロダクト側でハンドラーを付けた色見本を並べて、カラーピッカーを組み立てない。 ## アクセシビリティ ### コンポーネントが担うこと - 名前を描いているとき、色見本はそのテキストそのものです。色見本の位置で、名前、続いて補足テキストが読まれます。見本は隠します。言葉がすでにその色を伝えているからです。 - `labelHidden` を付けると、`label` を名前、`supportingText` を説明とする 1 つの画像になります。 - `decorative` を付けると、支援技術からは隠され、テキストも描きません。 - ラベルも補足テキストもない色見本は隠され、デバッグビルドで報告します。 - 入力もフォーカスも受けないので、フォーカスが止まる位置を増やしません。リンクやボタンの中では、支援技術に伝わるのはその要素の名前です。 - 文字を拡大しても、見本はアイコンと同じように大きさを保ち、横のテキストが大きくなります。 - 強制カラーモードでも、色はそのまま残ります。色こそがコンテンツだからです。縁はテキストの色になります。 - 右から左のレイアウトでは、見本は右側に来ます。`#0f766e` のような値の並びは変わりません。 ### 利用者側で行うこと - 色見本ごとに、名前を持たせるか装飾にするかを決めます。決め方はこうです。色見本を消すと名前が失われるなら、名前が必要です。そうでなければ装飾です。 - `labelHidden` よりも、見える名前を選びます。隠した名前は支援技術には色を伝えますが、見本を見ても隣の見本と見分けられない人には伝わりません。場所がないときは、色見本を入れた要素のツールチップで、求めに応じて名前を見せます。 - 表示する色の上に描くテキストは、そのコントラストを確かめます。色見本は色を見せるだけで、色を検査はしません。