الرئيسية المكوّناتمربع اللون

مربع اللون

يعرض لونًا في عيّنة واسمه بجانبها. العيّنة هي اللون نفسه تمامًا، فوق رقعة شطرنج حيث يكون اللون نصف شفاف، ولها حدّ يُظهر أين تنتهي حتى حين يقترب اللون من لون السطح. عيّنة للنظر، لا عنصر تحكم أبدًا ولا منتقٍ.

آخر تحديث: 23 أكتوبر 2026

content_copy

عرض بتنسيق Markdown

الفئة: التواصل
الرموز: comp.swatch
المستوى: أساسي

نظرة عامة

Web: tanrei-swatch; clock_loader_40
SwiftUI: TanreiSwatch; radio_button_unchecked
Jetpack Compose: TanreiSwatch; radio_button_unchecked
Flutter: TanreiSwatch; radio_button_unchecked
React Native: Swatch; radio_button_unchecked

مولَّد من docs/status/status.json, specs/swatch.spec.json

لون مع قيمته، ودور من السمة، ولون نصف شفاف، ونقطة

مربع اللون (swatch) يعرض لونًا لا يجري تعديله: لون العلامة التجارية في صفحة إعدادات، أو لون تصنيف بجانب التصنيف نفسه، أو أدوار سمة متجاورة. يرسم اللون كما أُعطي تمامًا، ويرسم اسم اللون بجانبه، لأن اللون لا يُعرف من عيّنته وحدها أبدًا. ولا يستجيب أبدًا لمؤشر ولا لمفتاح ولا لتركيز.

على الويب هو <tanrei-swatch>. والمنصات الأخرى لم تنفّذه بعد.

الاستخدام

<!-- الاسم بجانب العيّنة، والقيمة تحته. -->
<tanrei-swatch color="#0f766e" label="أخضر مزرق 700" supporting-text="#0f766e"></tanrei-swatch>

<!-- دور من السمة الحالية: يتبع مربع اللون المخطط اللوني لأن الخاصية المخصّصة تتبعه. -->
<tanrei-swatch color="var(--tanrei-sys-color-primary)" label="أساسي"></tanrei-swatch>

<!-- لا مكان للاسم: العيّنة وحدها، ولها اسم للتقنيات المساعدة. -->
<tanrei-swatch color="#e11d48" label="خلل" shape="circle" size="small" label-hidden></tanrei-swatch>

<!-- بجانب القيمة نفسها مكتوبةً: زخرفي، فيُقرأ مرة واحدة. -->
<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="أخضر مزرق 700" supportingText="#0f766e" />

المواصفات

ثلاثة أحجام، وشكلان، ومربع لون فارغ

البنية

الجزء	الوصف
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` · اختياري	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` · اختياري	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` · اختياري	The color's name, beside the sample: what the color is called where it is shown ("Teal 700", "Primary", "Bug").
6 `supporting-text` · اختياري	A line under the name: the color's value, the token it comes from, or where it is used.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
`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.

الحالات

السلوك

متطلبات بصيغة EARS. يُختبر تنفيذ كل منصة مقابل هذه المعرّفات. يُعرض نص المتطلبات كما ورد في ملف المواصفة، بالإنجليزية.

المعرّف	المتطلب
`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.

مطابقة الأسماء بين المنصات

التكافؤ لا يعني واجهات برمجية متطابقة. تعبّر كل منصة عن العقد نفسه بأسلوبها.

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	`tanrei-swatch`	`TanreiSwatch`	`TanreiSwatch`	`TanreiSwatch`	`Swatch`
`color` · الخاصية	`color`	`color`	`color`	`color`	`color`
`label` · الخاصية	`label`	`label`	`label`	`label`	`label`
`supportingText` · الخاصية	`supportingText`	`supportingText`	`supportingText`	`supportingText`	`supportingText`
`labelHidden` · الخاصية	`labelHidden`	`labelHidden`	`labelHidden`	`labelHidden`	`labelHidden`
`decorative` · الخاصية	`decorative`	`isDecorative`	`decorative`	`decorative`	`decorative`
`size` · الخاصية	`size`	`size`	`size`	`size`	`size`
`shape` · الخاصية	`shape`	`shape`	`shape`	`shape`	`shape`
ملاحظات	`<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"`.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
`--tanrei-comp-swatch-checkerboard-alternate-color`	`sys.color.surface-container-highest`	#eeeeee
`--tanrei-comp-swatch-checkerboard-color`	`sys.color.surface`	#ffffff
`--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`	#1b1b1b
`--tanrei-comp-swatch-outline-color`	`sys.color.outline-variant`	#000000 · 8%
`--tanrei-comp-swatch-outline-width`	`sys.border.hairline`	1px
`--tanrei-comp-swatch-supporting-text-color`	`sys.color.on-surface-variant`	#4b4b4b
`--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

نماذج الاختبار

عروض مرجعية. تلتقط كل المنصات لقطة لكل نموذج بالمعرّف نفسه حتى يمكن مقارنة النتائج.

`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

مولَّد من specs/swatch.spec.json, tokens/comp/swatch.tokens.json, design/tokens/

الإرشادات

متى تُستخدم

استخدم مربع اللون حيثما يُعرض لون ولا يُغيَّر: لوحة ألوان، أو نظرة عامة على سمة، أو اللون الذي أعطاه شخص لتصنيف أو لتقويم، أو مفتاح رسم بياني. هو صورة لون مع كلمات، ولا شيء أكثر.

تحتاج إلى	استخدم
لون يستطيع الشخص كتابته أو لصقه أو اختياره	حقل اللون، أو حقل إدخال اللون في صف يسمّي اللون أصلًا.
لون يقود إلى مكان ما أو يفتح شيئًا	رابطًا أو زرًّا يحمل مربع اللون.
لون واحد يُختار من مجموعة ألوان	ليس هذا المكوّن: مجموعة مربعات ألوان يُختار منها واحد هي منتقٍ، له قيمة ومفاتيح مجموعة أزرار الاختيار. وإلى أن يتضمن Tanrei منتقيًا كهذا، استخدم مجموعة أزرار الاختيار التي يحمل كل خيار فيها مربع لون زخرفيًّا بجانب اسمه.
حالة (خطأ، نجاح)	وسمًا أو تنويهًا: الكلمات تقول الحالة، واللون يضيف إليها فقط.

ما يرسمه

اللون، تمامًا. لا يُمزج فيه شيء: لا صبغة، ولا حالة، ولا تغيّر بين الفاتح والداكن. أعطِ الخاصية المخصّصة لدور (var(--tanrei-sys-color-primary)) حيث ينبغي أن يتبع مربع اللون السمة، وقيمة ثابتة حيث يعرض تلك القيمة.
رقعة شطرنج تحته. اللون نصف الشفاف تظهر رقعة الشطرنج من خلاله، فيُقرأ نصف شفاف. واللون المعتم يغطيها.
حدّ. خط رفيع واحد داخل حافة العيّنة، بلون الفاصل، ليظهر أين ينتهي الأبيض على صفحة بيضاء، أو اللون القريب من لون السطح.
بلا لون. القيمة الفارغة للخاصية color ترسم الحدّ وحده. قل في التسمية ما يعنيه ذلك («بلا لون»، «موروث»).

كل المنصات تقرأ اللون مكتوبًا بأرقام سداسية عشرية: #0f766e، ومع قناة ألفا #0f766e80. وعلى الويب يصلح أيضًا أي لون من ألوان CSS.

الأحجام والأشكال

`size`	الضلع	يُستخدم لـ
`small`	16	بجانب سطر واحد من النص الصغير: خلية جدول، أو صف كثيف، أو مفتاح رسم بياني.
`medium` (الافتراضي)	24	بجانب سطر من نص المتن: صف في قائمة، أو إعداد.
`large`	32	حيث يُنظر إلى اللون نفسه: لوحة ألوان، أو نظرة عامة على سمة.

`shape`	يُستخدم لـ
`square` (الافتراضي)	بلاطة من اللون: لوحة ألوان، أو سمة.
`circle`	نقطة تعلّم شيئًا آخر بلون: تصنيف، أو تقويم، أو سلسلة بيانات في رسم بياني.

الاسم والنص المساعد يتبعان الحجم.

الاسم

اكتب اسم اللون كما يسمّيه الناس في منتجك: «أخضر مزرق 700»، «أساسي»، «خلل». والقيمة مثل #0f766e ليست اسمًا، فضعها في supportingText تحت الاسم. ولا يصنع مربع اللون اسمًا من اللون أبدًا: فما يُسمّى به اللون يتوقف على اللغة وعلى المنتج.

افعل

أعطِ كل مربع لون label، واتركها ظاهرة حيث يتسع المكان.
عيِّن decorative على مربع اللون الذي يقف بجانب الاسم نفسه أو القيمة نفسها مكتوبين.
ضع في supportingText القيمة التي قد ينسخها الناس أو يقارنون بينها.

لا تفعل

لا تضع معالجًا على مربع اللون. ضعه في رابط أو زر، ففيهما الحالات ومؤشر التركيز.
لا تعتمد على اللون وحده لتقول ما هو الشيء. فالاسم هو الذي يقول ذلك.
لا تبنِ منتقي ألوان من مربعات ألوان بمعالجات من عندك.

إمكانية الوصول

الدور: img
التسمية: 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 32px · pointer 44px · spacing 8px · touch 48px

لوحة المفاتيح

المفاتيح	الإجراء

ملاحظات

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.

مولَّد من specs/swatch.spec.json, tokens/sys/measure.tokens.json

ما يتكفل به المكوّن

حين يُرسم اسمه، يكون مربع اللون ذلك النص: الاسم ثم النص المساعد، يُقرآن حيث يقف مربع اللون. والعيّنة مخفيّة، لأن الكلمات تقولها أصلًا.
مع labelHidden يكون صورة واحدة تسمّيها الخاصية label ويصفها supportingText.
مع decorative يكون مخفيًّا عن التقنيات المساعدة ولا يرسم نصًّا.
مربع اللون الذي ليس له تسمية ولا نص مساعد يُخفى، ويُبلَّغ عنه في بنيات التنقيح (debug).
لا يأخذ إدخالًا ولا تركيزًا، فلا يضيف موضع توقف إلى ترتيب التركيز. وداخل رابط أو زر، ما يُعرض للتقنيات المساعدة هو اسم ذلك العنصر.
مع النص المكبَّر تحتفظ العيّنة بحجمها، كما تفعل الأيقونة، ويكبر النص بجانبها.
في وضع الألوان المفروضة (forced colors) يبقى اللون كما هو، لأنه المحتوى، ويأخذ الحدّ لون النص.
في تخطيط من اليمين إلى اليسار تقع العيّنة على اليمين. والقيمة مثل #0f766e تحتفظ بترتيبها.

ما عليك فعله

قرِّر لكل مربع لون أهو مسمّى أم زخرفي. والقاعدة: إن كان حذف مربع اللون يُضيع اسمًا فهو مسمّى. وإلا فهو زخرفي.
فضِّل الاسم الظاهر على labelHidden. فالاسم المخفي يخبر التقنيات المساعدة باللون، لكنه لا يخبر شخصًا يرى العيّنة ولا يستطيع تمييزها من جارتها. وحيث لا مكان، أظهر الاسم عند الطلب، في تلميح على العنصر الذي يحمل مربع اللون.
افحص تباين أي نص ترسمه على الألوان التي تعرضها. مربع اللون يعرض الألوان، ولا يفحصها.

الشيفرة المصدرية والمشكلات على GitHub