خانة الاختيار — مكوّن واجهة مستخدم يراعي إمكانية الوصول

الفئة: الاختيار
الرموز: comp.checkbox
المستوى: أساسي
يُستخدم في: Checkbox group

نظرة عامة

Web: tanrei-checkbox; schedule
SwiftUI: TanreiCheckbox; schedule
Jetpack Compose: TanreiCheckbox; schedule
Flutter: TanreiCheckbox; schedule
React Native: Checkbox; schedule

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

غير محدَّدة ومحدَّدة وفي حالة غير محسومة

الاستخدام

المراجعة التي أعطت خانة الاختيار مقاساتها الحالية ورسوم مجموعة الأيقونات لم تغيّر إلا مظهرها وحركتها، فكل العيّنات أدناه سارية. يرسمها الويب ويحرّكها كما تقول المواصفة. أما SwiftUI و Compose و Flutter و React Native فمتأخرة: تأخذ المقاسات الجديدة منذ الآن، لكنها ما زالت ترسم علامة الصح والشَّرطة بعلامات خاصة بها وتحرّكها بطريقتها إلى أن تلحق. وهناك تحسينان لاحقان موجودان على الويب وحده حتى الآن: لعلامة الصح والشَّرطة وزن خاص بهما أثقل، وحدّ المربع وتعبئته يُرسمان شكلًا واحدًا.

<tanrei-checkbox label="أرسلوا لي التحديثات بالبريد"></tanrei-checkbox>
<tanrei-checkbox checked label="أرسلوا لي التحديثات بالبريد"></tanrei-checkbox>

<!-- أبٌ أبناؤه مختلطون. تفعيله يحدّده ويمسح indeterminate. -->
<tanrei-checkbox indeterminate label="تحديد الكل"></tanrei-checkbox>

<!-- داخل نموذج يرسل value (الافتراضي "on") تحت name ما دام محدَّدًا، ويراعي required. -->
<form>
  <tanrei-checkbox name="terms" required label="أوافق على الشروط"></tanrei-checkbox>
</form>

<script type="module">
  import '@tanrei/web/components/checkbox';
  // يبدّل العنصر قيمة checked بنفسه قبل أن يُصدر change.
  document.querySelector('tanrei-checkbox').addEventListener('change', (e) => save(e.detail.checked));
  const terms = document.querySelector('[name="terms"]');
  terms.error = submitted && !terms.checked;
</script>

import { Checkbox } from '@tanrei/react';

<Checkbox checked={updates} label="أرسلوا لي التحديثات بالبريد" onChange={(e) => setUpdates(e.detail.checked)} />
<Checkbox checked={all} indeterminate={some && !all} label="تحديد الكل" onChange={(e) => selectAll(e.detail.checked)} />
<Checkbox checked={terms} error={submitted && !terms} label="أوافق على الشروط" onChange={(e) => setTerms(e.detail.checked)} />

import Tanrei

TanreiCheckbox("أرسلوا لي التحديثات بالبريد", isOn: $updates)

// تأتي isIndeterminate من بياناتك. تفعيله يجعل isOn تساوي true؛ ثم تمسحها بياناتك.
TanreiCheckbox("تحديد الكل", isOn: $allSelected, isIndeterminate: someSelected)

import androidx.compose.ui.state.ToggleableState
import io.github.chnotchy.tanrei.components.TanreiCheckbox

TanreiCheckbox(checked = updates, onCheckedChange = { updates = it }, label = "أرسلوا لي التحديثات بالبريد")

// الأب الذي قد يكون مفعَّلًا جزئيًّا يأخذ ToggleableState. والمستدعي يحسب الحالة التالية:
// تفعيل خانة اختيار في حالة غير محسومة يجعلها On.
TanreiCheckbox(
    state = allState,
    onClick = { selectAll(allState != ToggleableState.On) },
    label = "تحديد الكل",
)

TanreiCheckbox(
    checked = terms,
    onCheckedChange = { terms = it },
    label = "أوافق على الشروط",
    isError = submitted && !terms,
)

import 'package:tanrei/tanrei.dart';

TanreiCheckbox(
  value: updates,
  onChanged: (bool value) => setState(() => updates = value), // القيمة null تعطّلها
  label: 'أرسلوا لي التحديثات بالبريد',
);

// مع tristate، القيمة null حالة غير محسومة. تفعيلها يستدعي onChanged(true).
TanreiCheckbox(
  value: allSelected, // bool?: القيمة null ما دام بعضها فقط محدَّدًا
  tristate: true,
  onChanged: (bool value) => setState(() => selectAll(value)),
  label: 'تحديد الكل',
);

TanreiCheckbox(
  value: terms,
  onChanged: (bool value) => setState(() => terms = value),
  isError: submitted && !terms,
  label: 'أوافق على الشروط',
);

import { Checkbox } from '@tanrei/react-native';

<Checkbox value={updates} onValueChange={setUpdates} label="أرسلوا لي التحديثات بالبريد" />
<Checkbox value={all} indeterminate={some && !all} onValueChange={selectAll} label="تحديد الكل" />
<Checkbox value={terms} onValueChange={setTerms} error={submitted && !terms} label="أوافق على الشروط" />

المواصفات

الأوضاع والخطأ والتعطيل

في النظام الافتراضي خانة الاختيار مربع بمقاس 18 بحدّ عرضه 2 وزاوية 2، على طبقة حالة دائرية بمقاس 40، مع هدف بمقاس 48. ومع التسمية يكون ارتفاعها 40. علامة الصح والشَّرطة هما الرسمان check و remove من مجموعة أيقونات النظام، مرسومان بمقاس 20 فوق المربع. ولهما وزن خاص بهما أثقل من سائر أيقونات النظام: 500 في النظام الافتراضي حيث الأيقونات 300. عند هذا المقاس يكون الخط بوزن الأيقونات بعرض بكسل واحد تقريبًا وتصعب رؤيته، ولذلك كانت العلامة أثقل مع بقاء مقاسها كما هو. والإعداد الجاهز يحتفظ بوزن أيقوناته. لا ترسم خانة الاختيار علامة خاصة بها، فنظام التصميم الذي يغيّر مجموعة أيقوناته يغيّر هذين الرسمين مع سائر الرسوم. وحدّ المربع وتعبئته شكل واحد: لا يظهر بينهما شيء مما خلف المربع عند أي تكبير أو أي كثافة عرض، والمربع المحدَّد لون واحد متساوٍ من حافته إلى علامته. وتحت cupertino تحتفظ خانة الاختيار بمربعها الأصغر وبرسم بمقاس 16.

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

البنية

مرسوم فوق نموذج الاختبار unselected كما ترسمه حزمة الويب.

الجزء	الوصف
1 `container`	The round state layer behind the box (Material Design 3's 40). It carries hover, focus and press and is invisible at rest.
2 `box`	The small square that shows the condition (Material Design 3's 18, with a 2 corner): empty with an outline when unchecked, filled when checked or indeterminate.
3 `outline`	The border of the box, drawn inside its edge. The fill sits inside the border, so a translucent fill and border never overlap; where the two meet they are drawn as one shape, so nothing behind the box shows between them.
4 `mark`	The glyph check (checked) or the glyph remove (indeterminate) of the system's icon set, centered on the box and drawn with the icon set's family, fill and optical size at the mark's own weight, comp.checkbox.mark.weight: in the default system heavier than the system's icons, because the mark is a thin stroke on a small filled box and is what tells checked from indeterminate. The checkbox draws no mark of its own; a system that wants another check chooses another icon set. The glyph is decorative: the condition is announced from the state.
5 `label` · اختياري	The visible text that names the choice. A click on it toggles the checkbox.
6 `focus-ring`	Gap-then-ring indicator shown for keyboard focus, following the box's shape.

القياسات

الطول	الرمز	القيمة (px)
`container` size	`tanrei.comp.checkbox.container.size`	40
`box` size	`tanrei.comp.checkbox.box.size`	18
`mark` size	`tanrei.comp.checkbox.mark.size`	20

مرسوم فوق نموذج الاختبار unselected كما ترسمه حزمة الويب.

الخصائص

الخاصية	النوع	القيمة الافتراضية	الوصف
`checked`	`boolean`	`false`	Whether the choice is on.
`indeterminate`	`boolean`	`false`	Shows the choice as partly on (a parent whose children are mixed). Wins over checked for what is drawn and announced; activation clears it.
`error`	`boolean`	`false`	Marks the choice as invalid (a required choice left unmade). Draws the error form of the condition and is exposed as invalid; the message itself belongs to the surrounding form.
`disabled`	`boolean`	`false`	Prevents interaction and removes the checkbox from the focus order.
`readOnly`	`boolean`	`false`	Shows the choice and keeps it: the checkbox can be focused and read and is submitted with its form, but the person cannot switch it. Drawn as an enabled checkbox, without the hover and press answers (CHK-24).
`label`	`string`	`""`	The text that names the choice: drawn next to the box and used as the accessible name.
`labelHidden`	`boolean`	`false`	Draws no visible label but keeps label as the accessible name (a row-selection checkbox in a table whose row already says what it is).

الأحداث

الحدث	الوصف
`change`	The user switched the checkbox; carries the new value of checked (indeterminate is then false).

الحالات

السلوك

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

المعرّف	المتطلب
`CHK-1`	WHEN the user activates the checkbox by pointer, touch, Space, assistive technology or a click on its label THE checkbox SHALL switch checked and emit change exactly once with the new value; Enter SHALL activate it only on a platform whose convention activates any focused control with Enter (Android, tvOS), and SHALL NOT on the web, where Enter submits the form.
`CHK-2`	WHEN the user activates the checkbox while indeterminate is true THE checkbox SHALL set checked to true, clear indeterminate, and emit change with true.
`CHK-3`	WHILE disabled is true THE checkbox SHALL NOT change or emit change, SHALL NOT be focusable, SHALL ignore clicks on its label and SHALL expose the disabled state to assistive technology.
`CHK-4`	THE checkbox SHALL draw the condition its props select: indeterminate when indeterminate is true, otherwise selected when checked is true, otherwise unselected; and the error- form of that condition while error is true.
`CHK-5`	WHILE hovered, keyboard-focused or pressed THE checkbox SHALL render its container, box, mark, outline, label and opacity from the component tokens of its condition in the highest-precedence active state, with precedence pressed over focused over hovered; focus gained by pointer or touch SHALL NOT select the focused state. A part the interaction states recolor changes over the component's state motion, as the container does; only a change of condition uses the selection motion.
`CHK-6`	WHEN the checkbox receives keyboard focus THE checkbox SHALL show the focus ring around its box without animation; focus gained by pointer or touch SHALL NOT show it.
`CHK-7`	WHERE the visual size is below the minimum target THE checkbox SHALL extend its hit area on both axes to sys.target.touch for touch input and sys.target.pointer for fine pointers, without changing its visual size; a platform that cannot tell the input type SHALL use sys.target.touch. The visible label SHALL be part of the hit area as well.
`CHK-8`	WHILE disabled is true THE checkbox SHALL render its container, box, mark, outline, label and opacity from the disabled component tokens of its condition.
`CHK-9`	WHEN the checkbox is pressed by pointer, touch or Space, or by Enter where Enter activates it (Android, tvOS; never on the web, where Enter submits the form) THE checkbox SHALL show the pressed state without delay and SHALL keep it visible for at least sys.motion.duration.press-hold, even when the press ends sooner.
`CHK-10`	WHILE pressed THE checkbox SHALL answer as sys.behavior.pressed-feedback names: overlay applies the pressed tokens to the whole container at once; ripple grows the pressed state layer from the point of contact (from the center for keyboard activation; a press outside the container (on the label) grows it from the container's center); dim applies the pressed opacity to the whole control and draws no state layer; none draws no answer to the press. Under ripple and dim only the container color stays with the state under the press; box, mark, outline, label, opacity and shape still come from the pressed tokens. Under none every part stays with the state under the press. The ripple grows over comp.checkbox.motion.feedback-duration with motion.state-easing, fades over motion.state-duration with motion.state-easing once the press has ended and press-hold has passed, and appears whole where motion is reduced.
`CHK-11`	THE checkbox SHALL ease its container and box corners by sys.shape.corner-smoothing (0 is a quarter circle, 0.6 the iOS continuous corner; a platform with only the OS curve draws it for any amount above 0) and show its keyboard focus as sys.behavior.focus-style names (ring or glow); a platform that cannot draw a choice SHALL fall back to the first value and state that in its README.
`CHK-12`	THE checkbox SHALL draw a box of side comp.checkbox.box.size with corners comp.checkbox.box.shape, centered in a round container of diameter comp.checkbox.container.size; its outline of width comp.checkbox.outline.width SHALL lie inside the box's edge and its fill inside the outline, never under it. Its mark SHALL be a glyph of the system's icon set, check while selected and remove while indeterminate, and SHALL NOT be drawn while unselected: centered on the box at comp.checkbox.mark.size, with sys.icon.family.selected, sys.icon.fill.selected, the weight comp.checkbox.mark.weight (not sys.icon.weight) and an optical size clamped between sys.icon.optical-size.min and sys.icon.optical-size.max, not clipped by the box, and hidden from assistive technology. THE checkbox SHALL draw no mark of its own (no path, shape or character of its own for the check or the dash). The weight SHALL change the stroke of the glyph only: the glyph box stays comp.checkbox.mark.size, and the box, the container and the place of the glyph are the same at every weight.
`CHK-13`	WHEN the condition changes after the checkbox was first drawn THE checkbox SHALL change the box, outline and mark colors over comp.checkbox.motion.selection-duration with comp.checkbox.motion.selection-easing; a glyph that appears SHALL fade in over the same duration and curve while growing about the box's center from comp.checkbox.motion.mark-enter-scale of its size to its full size over comp.checkbox.motion.mark-scale-duration with comp.checkbox.motion.mark-scale-easing, and a glyph that goes SHALL fade out and shrink to comp.checkbox.motion.mark-enter-scale the same way; between checked and indeterminate the check goes and the dash appears at the same time. A change of error alone SHALL only recolor, and the box and container SHALL NOT change size or move.
`CHK-14`	THE checkbox SHALL expose the role checkbox with the state checked, not checked or mixed (mixed while indeterminate is true), and SHALL expose the invalid state while error is true.
`CHK-15`	WHILE label is not empty and labelHidden is false THE checkbox SHALL draw label at the inline end of the container, comp.checkbox.label.gap away, in comp.checkbox.label.typescale, wrapping rather than truncating, the control centered on the label's first line; right-to-left layouts SHALL mirror the order.
`CHK-16`	WHILE labelHidden is true THE checkbox SHALL draw no label and SHALL still expose label as its accessible name; WHILE label is not empty, or a Field that frames it gives it a label, THE checkbox SHALL expose that label as its accessible name, over a name the product gives it on the element (aria-label or aria-labelledby); WHILE label is empty and the product gives the checkbox a name of its own on the element — aria-label, or aria-labelledby naming an element — THE checkbox SHALL expose that name as its accessible name; WHILE label is empty and the product gives it none THE checkbox SHALL still render, and in debug builds report that it has no accessible name.
`CHK-17`	WHERE motion is reduced THE checkbox SHALL draw the new condition whole in the first frame after the change: the box, outline and mark colors of the new condition, the new glyph at its full size and full opacity, and the old glyph gone, with no frame in between; a change that arrives while a selection motion is running SHALL end that motion in the same frame. The change SHALL be neither delayed nor skipped.
`CHK-18`	WHEN the condition changes again before the selection motion of CHK-13 has ended THE checkbox SHALL move from what it draws at that moment to the latest condition, never first jumping to the end of the earlier change, and SHALL end on the latest condition's colors and glyph alone.
`CHK-19`	IF the icon set cannot draw the glyph yet (its font is still loading or failed to load) THE checkbox SHALL draw nothing in the glyph's place, never the glyph's name as text, SHALL still draw the box, its fill and its outline and expose its state, and SHALL show the glyph once the icon set can draw it, without the selection motion.
`CHK-20`	THE checkbox 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 checkbox is shown THE checkbox SHALL draw itself for the new direction at once, without a motion of its own, keeping its selection and its focus.
`CHK-21`	THE checkbox SHALL lay out its label as text of its own direction, isolated from the text around it: each takes the base direction of its first strong character, or the layout direction where it has none, so that a left-to-right word, a number with its sign or unit, a telephone number and an address keep their own order in a right-to-left layout and reorder nothing beside them; THE checkbox SHALL still place the label and align its lines by the layout direction, not by the text's own.
`CHK-22`	THE checkbox SHALL draw the outline and the fill of its box as one shape: every point inside the box's outer edge SHALL be painted by the outline, by the fill, or, along the line where the two meet, by both in shares that add up to the whole, so that nothing behind the box shows between them at any zoom, display density or fractional position, in any frame of the selection motion (CHK-13), and so that a box whose outline and fill have the same color is that one color, evenly, from its edge to its mark; the two SHALL NOT be painted over one another either (CHK-12), so that a translucent outline or fill is nowhere darker than its token.
`CHK-23`	WHILE the checkbox stands in a checkbox group THE checkbox SHALL take its checked from the group's value and from the value the group reads from it (CKG-2), SHALL be disabled WHILE the group is (CKG-6), SHALL have its switching by the person reported by the group's change and by no event of its own that a listener on the group would receive as well (CKG-4), and WHERE the platform has forms SHALL submit nothing of its own, whatever name it carries (CKG-8). WHERE the checkbox stands in no checkbox group it SHALL be as it is anywhere — in a field, in a field group, in a table's row or alone: checked is its own, change is its own, and on the web it submits its own entry under its own name.
`CHK-24`	WHILE readOnly is true and disabled is false THE checkbox SHALL stay focusable and in the focus order; SHALL NOT change checked or indeterminate, and SHALL NOT emit change, on any activation — pointer, touch, Space, Enter where Enter activates it, assistive technology, a click on its label or a click dispatched on the element; SHALL expose the read-only state to assistive technology beside its checked, not checked or mixed state; WHERE the platform has forms SHALL be submitted with its form as it is drawn, and SHALL NOT report a missing value to the form's own validation, because the person cannot give one; and SHALL be drawn from the resting component tokens of its condition — the enabled ones, never the disabled ones — and SHALL show no hovered and no pressed state, under any pressed feedback (no overlay, no ripple, no dim), while keyboard focus still selects the focused state and shows the focus ring (CHK-5, CHK-6). The product may still set checked and indeterminate, which then take the selection motion (CHK-13). WHILE disabled is true as well, disabled wins (CHK-3).
`CHK-25`	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE checkbox SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the checkbox is invalid — except those the checkbox owns (aria-checked, aria-pressed, aria-disabled), which it SHALL move and not expose. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE checkbox SHALL take it off that element. WHEN the product sets an aria- attribute the checkbox owns THE checkbox SHALL report it in debug builds.

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

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

المواصفة	Web	SwiftUI	Jetpack Compose	Flutter	React Native
المكوّن	`tanrei-checkbox`	`TanreiCheckbox`	`TanreiCheckbox`	`TanreiCheckbox`	`Checkbox`
`checked` · الخاصية	`checked`	`isOn`	`checked`	`value`	`value`
`indeterminate` · الخاصية	`indeterminate`	`isIndeterminate`	`state`	`tristate`	`indeterminate`
`error` · الخاصية	`error`	`isError`	`isError`	`isError`	`error`
`disabled` · الخاصية	`disabled`	`disabled`	`enabled`	`onChanged`	`disabled`
`readOnly` · الخاصية	`readOnly`	`readOnly`	`readOnly`	`readOnly`	`readOnly`
`label` · الخاصية	`label`	`title`	`label`	`label`	`label`
`labelHidden` · الخاصية	`labelHidden`	`labelsHidden`	`labelHidden`	`labelHidden`	`labelHidden`
`change` · الحدث	`change`	`isOn`	`onCheckedChange`	`onChanged`	`onValueChange`
ملاحظات	Form-associated (ElementInternals): it takes part in a form with `name` and `value` (default "on"), resets with it, and honours `required` as the native checkbox does; those three are web attributes, not spec props. It switches its own `checked` before firing `change` (and `input`), as a native checkbox does. `labelHidden` is the `label-hidden` attribute. Inside a `tanrei-checkbox-group` (found with `closest()` when it connects) it takes `checked` from the group, ignores `name` and `required`, submits nothing and fires no `input` or `change` of its own (CHK-23); a `value` attribute it does not carry is no value there, not "on". `readOnly` is the `readonly` attribute (HTML's name; the native attribute does not apply to a checkbox, so the element cancels the activation itself and writes `aria-readonly` on its native checkbox).	Toggle idiom: `TanreiCheckbox(_ title:, isOn: Binding<Bool>, isIndeterminate: Bool = false)`; activation writes the binding, which is the change event. `isIndeterminate` is a value the caller derives from its data (a select-all is derived state), so activation sets `isOn` to true and the caller's data clears it. `disabled` follows `.disabled(_:)`; `labelsHidden` follows `.labelsHidden()`.	Two overloads, as Compose's own: `TanreiCheckbox(checked, onCheckedChange, …)` and, for a parent that can be indeterminate, `TanreiCheckbox(state: ToggleableState, onClick, …)` in the `TriStateCheckbox` idiom, where the caller computes the next state (CHK-2 says it is `On`). `enabled` is the inverse flag; a null `onCheckedChange` draws a checkbox that only displays.	Flutter idiom: `value` is `bool?`; with `tristate: true` a null `value` is indeterminate. Unlike Flutter's Material checkbox, which cycles null → false, activation from null calls `onChanged(true)` (CHK-2). A null `onChanged` disables it.	Controlled, in React Native's `value` / `onValueChange` idiom: the caller sets `value` from the callback.

الرموز

الرمز	يشير إلى	القيمة المحلولة (فاتح)
`--tanrei-comp-checkbox-box-shape`	—	2px
`--tanrei-comp-checkbox-box-size`	—	18px
`--tanrei-comp-checkbox-container-shape`	`sys.shape.corner.full`	9999px
`--tanrei-comp-checkbox-container-size`	—	40px
`--tanrei-comp-checkbox-disabled-container-shape`	—	9999px
`--tanrei-comp-checkbox-disabled-opacity`	—	1
`--tanrei-comp-checkbox-error-indeterminate-box-color`	`sys.color.error`	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-indeterminate-disabled-box-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-indeterminate-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-indeterminate-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-indeterminate-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-indeterminate-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-indeterminate-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-indeterminate-focused-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-focused-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-indeterminate-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-indeterminate-focused-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-indeterminate-focused-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-focused-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-hovered-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-hovered-container-color`	—	#cd262f · 8%
`--tanrei-comp-checkbox-error-indeterminate-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-indeterminate-hovered-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-indeterminate-hovered-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-hovered-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-error-indeterminate-mark-color`	`sys.color.on-error`	#ffffff
`--tanrei-comp-checkbox-error-indeterminate-outline-color`	`sys.color.error`	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-pressed-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-pressed-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-indeterminate-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-indeterminate-pressed-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-indeterminate-pressed-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-pressed-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-indeterminate-state-layer-color`	`comp.checkbox.error-indeterminate.outline.color`	#cd262f
`--tanrei-comp-checkbox-error-selected-box-color`	`sys.color.error`	#cd262f
`--tanrei-comp-checkbox-error-selected-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-selected-disabled-box-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-selected-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-selected-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-selected-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-selected-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-selected-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-selected-focused-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-focused-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-selected-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-selected-focused-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-selected-focused-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-focused-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-hovered-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-hovered-container-color`	—	#cd262f · 8%
`--tanrei-comp-checkbox-error-selected-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-selected-hovered-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-selected-hovered-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-hovered-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-error-selected-mark-color`	`sys.color.on-error`	#ffffff
`--tanrei-comp-checkbox-error-selected-outline-color`	`sys.color.error`	#cd262f
`--tanrei-comp-checkbox-error-selected-pressed-box-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-pressed-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-selected-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-selected-pressed-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-selected-pressed-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-pressed-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-selected-state-layer-color`	`comp.checkbox.error-selected.outline.color`	#cd262f
`--tanrei-comp-checkbox-error-unselected-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-disabled-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-unselected-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-error-unselected-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-unselected-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-error-unselected-focused-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-focused-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-unselected-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-unselected-focused-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-focused-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-focused-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-hovered-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-hovered-container-color`	—	#cd262f · 8%
`--tanrei-comp-checkbox-error-unselected-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-unselected-hovered-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-hovered-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-hovered-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-error-unselected-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-outline-color`	`sys.color.error`	#cd262f
`--tanrei-comp-checkbox-error-unselected-pressed-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-pressed-container-color`	—	#cd262f · 10%
`--tanrei-comp-checkbox-error-unselected-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-error-unselected-pressed-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-error-unselected-pressed-outline-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-pressed-state-layer-color`	—	#cd262f
`--tanrei-comp-checkbox-error-unselected-state-layer-color`	`comp.checkbox.error-unselected.outline.color`	#cd262f
`--tanrei-comp-checkbox-focused-container-shape`	—	9999px
`--tanrei-comp-checkbox-focused-opacity`	—	1
`--tanrei-comp-checkbox-hovered-container-shape`	—	9999px
`--tanrei-comp-checkbox-hovered-opacity`	—	1
`--tanrei-comp-checkbox-indeterminate-box-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-indeterminate-disabled-box-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-indeterminate-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-indeterminate-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-indeterminate-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-indeterminate-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-indeterminate-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-indeterminate-focused-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-focused-container-color`	—	#1b1b1b · 10%
`--tanrei-comp-checkbox-indeterminate-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-focused-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-indeterminate-focused-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-focused-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-hovered-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-hovered-container-color`	—	#1b1b1b · 8%
`--tanrei-comp-checkbox-indeterminate-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-hovered-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-indeterminate-hovered-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-hovered-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-mark-color`	`sys.color.on-primary`	#ffffff
`--tanrei-comp-checkbox-indeterminate-outline-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-pressed-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-pressed-container-color`	—	#1b1b1b · 10%
`--tanrei-comp-checkbox-indeterminate-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-pressed-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-indeterminate-pressed-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-pressed-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-indeterminate-state-layer-color`	`comp.checkbox.indeterminate.outline.color`	#1b1b1b
`--tanrei-comp-checkbox-label-gap`	`sys.space.space50`	4px
`--tanrei-comp-checkbox-mark-size`	`sys.icon.small`	20px
`--tanrei-comp-checkbox-mark-weight`	`sys.icon.mark.weight`	500
`--tanrei-comp-checkbox-motion-feedback-duration`	`sys.motion.role.feedback`	450ms
`--tanrei-comp-checkbox-motion-mark-enter-scale`	—	0.5
`--tanrei-comp-checkbox-motion-mark-scale-duration`	`sys.motion.role.selection.mark`	250ms
`--tanrei-comp-checkbox-motion-mark-scale-easing`	`sys.motion.easing.spatial`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-checkbox-motion-selection-duration`	`sys.motion.role.selection.mark`	250ms
`--tanrei-comp-checkbox-motion-selection-easing`	`sys.motion.easing.state`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-checkbox-motion-state-duration`	`sys.motion.role.state.compact`	200ms
`--tanrei-comp-checkbox-motion-state-easing`	`sys.motion.easing.state`	cubic-bezier(0.2, 0, 0, 1)
`--tanrei-comp-checkbox-outline-width`	`sys.border.thick`	2px
`--tanrei-comp-checkbox-pressed-container-shape`	—	9999px
`--tanrei-comp-checkbox-pressed-opacity`	—	1
`--tanrei-comp-checkbox-selected-box-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-checkbox-selected-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-selected-disabled-box-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-selected-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-selected-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-selected-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-selected-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-selected-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-selected-focused-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-focused-container-color`	—	#1b1b1b · 10%
`--tanrei-comp-checkbox-selected-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-focused-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-selected-focused-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-focused-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-hovered-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-hovered-container-color`	—	#1b1b1b · 8%
`--tanrei-comp-checkbox-selected-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-hovered-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-selected-hovered-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-hovered-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-selected-mark-color`	`sys.color.on-primary`	#ffffff
`--tanrei-comp-checkbox-selected-outline-color`	`sys.color.primary`	#1b1b1b
`--tanrei-comp-checkbox-selected-pressed-box-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-pressed-container-color`	—	#1b1b1b · 10%
`--tanrei-comp-checkbox-selected-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-pressed-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-selected-pressed-outline-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-pressed-state-layer-color`	—	#1b1b1b
`--tanrei-comp-checkbox-selected-state-layer-color`	`comp.checkbox.selected.outline.color`	#1b1b1b
`--tanrei-comp-checkbox-unselected-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-disabled-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-disabled-container-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-disabled-label-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-unselected-disabled-mark-color`	—	#ffffff
`--tanrei-comp-checkbox-unselected-disabled-outline-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-unselected-disabled-state-layer-color`	—	#1b1b1b · 38%
`--tanrei-comp-checkbox-unselected-focused-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-focused-container-color`	—	#848484 · 10%
`--tanrei-comp-checkbox-unselected-focused-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-unselected-focused-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-focused-outline-color`	—	#848484
`--tanrei-comp-checkbox-unselected-focused-state-layer-color`	—	#848484
`--tanrei-comp-checkbox-unselected-hovered-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-hovered-container-color`	—	#848484 · 8%
`--tanrei-comp-checkbox-unselected-hovered-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-unselected-hovered-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-hovered-outline-color`	—	#848484
`--tanrei-comp-checkbox-unselected-hovered-state-layer-color`	—	#848484
`--tanrei-comp-checkbox-unselected-label-color`	`sys.color.on-surface`	#1b1b1b
`--tanrei-comp-checkbox-unselected-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-outline-color`	`sys.color.outline`	#848484
`--tanrei-comp-checkbox-unselected-pressed-box-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-pressed-container-color`	—	#848484 · 10%
`--tanrei-comp-checkbox-unselected-pressed-label-color`	—	#1b1b1b
`--tanrei-comp-checkbox-unselected-pressed-mark-color`	—	#000000 · 0%
`--tanrei-comp-checkbox-unselected-pressed-outline-color`	—	#848484
`--tanrei-comp-checkbox-unselected-pressed-state-layer-color`	—	#848484
`--tanrei-comp-checkbox-unselected-state-layer-color`	`comp.checkbox.unselected.outline.color`	#848484
`--tanrei-comp-checkbox-label-typescale`	`sys.typescale.body`	400 14px/1.5714

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

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

unselected

label: Email me updates

selected

checked: true label: Email me updates

indeterminate

indeterminate: true label: Select all

error-unselected

error: true label: I accept the terms

error-selected

checked: true error: true label: I accept the terms

error-indeterminate

indeterminate: true error: true label: Select all

disabled-unselected

disabled: true label: Email me updates

disabled-selected

checked: true disabled: true label: Email me updates

disabled-indeterminate

indeterminate: true disabled: true label: Select all

label-hidden

checked: true label: Select row labelHidden: true

read-only-selected

checked: true readOnly: true label: Send me a receipt

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

الإرشادات

متى يُستخدم

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

الحالة غير المحسومة تخص خانة اختيار أبًا أبناؤها محدَّدون جزئيًّا، مثل «تحديد الكل» فوق قائمة. وليست جوابًا ثالثًا يستطيع الشخص أن يختاره.

للقراءة فقط

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

خانة اختيار أم زر اختيار أم مفتاح تبديل

عنصر التحكم	الخيارات	متى يسري	يُستخدم لـ
خانة الاختيار	أي عدد من الاختيارات المستقلة، ومنه لا شيء	حين يؤكد الشخص	خيارات في نموذج، الموافقة على الشروط، تحديد الصفوف
زر الاختيار	واحد بالضبط من مجموعة صغيرة كلها معروضة	حين يؤكد الشخص، في الغالب	جواب واحد عن سؤال واحد
مفتاح التبديل	إعداد واحد، مفعَّل أو موقوف	فورًا	الإعدادات التي تُطبَّق فور تغيّرها

افعل

اكتب التسمية على أنها الاختيار نفسه، بصيغة الإثبات: «أرسلوا لي التحديثات بالبريد»، لا «لا ترسلوا لي بريدًا».
رُصَّ قائمة خانات الاختيار عموديًّا، واحدة في كل سطر، لتبدأ كل تسمية من الموضع نفسه.
اشتقّ الحالة غير المحسومة من الأبناء. وحين يُفعَّل الأب حدِّد كل ابن.
حين تُترك خانة اختيار مطلوبة غير محدَّدة، عيِّن error وقل السبب في رسالة النموذج.

لا تفعل

لا تستخدم خانة اختيار لتغيير يُطبَّق فورًا. استخدم مفتاح تبديل.
لا تستخدم خانات الاختيار لخيارات يستبعد بعضها بعضًا. استخدم أزرار الاختيار.
لا تضع روابط ولا عناصر تحكم أخرى داخل التسمية. النقر على التسمية يبدّل خانة الاختيار.
لا تُخفِ التسمية إلا إذا كان الصف المحيط بخانة الاختيار يقول أصلًا ما الذي تحدّده.

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

الدور: checkbox
التسمية: label is the accessible name, visible or not (labelHidden). A click on the visible label toggles the checkbox, as a native label does. A checkbox with no label is reported in debug builds.
الحد الأدنى للهدف: تستوفي مساحة اللمس الحد الأدنى لحجم الهدف حتى لو كان الحجم المرئي أصغر. minimum 32px · pointer 44px · spacing 8px · touch 48px

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

المفاتيح	الإجراء
`Tab`	Moves focus to the checkbox.
`Space`	Switches it (an indeterminate checkbox becomes checked); nothing while it is read-only.
`Enter`	Nothing on the web (it submits the form); switches it where the platform activates any focused control with Enter (Android, tvOS).

ملاحظات

The mixed state is announced as such (aria-checked="mixed" on the web, a toggleable state of Indeterminate on Android, a Semantics mixed value in Flutter, accessibilityState checked "mixed" in React Native). SwiftUI has no mixed trait on iOS: the value is announced as "mixed" through accessibilityValue.
error is exposed as invalid (aria-invalid on the web, the error semantics on Android and Flutter). The reason is text the form shows and associates with the checkbox; the checkbox does not draw it.
Read-only (CHK-24) is a checkbox that shows an answer in place and keeps it in the focus order, so that it is read with its form — on a review step, or where only some people may change it. HTML's readonly attribute does not apply to a checkbox, so a read-only checkbox is not a native one's: on the web it keeps the native checkbox enabled, cancels its activation and says read-only with aria-readonly, which WAI-ARIA allows on the checkbox role; React Aria's isReadOnly is the same: focusable, announced with its value, not changeable. Where the answer needs no control at all, write it as text; where the person may not reach it at all, it is disabled.
Several checkboxes that answer one question are a checkbox group: it names the set, holds the list of the checked values under one name and says the set's error (CHK-23). A checkbox stands alone where it is one choice of its own — a consent, a setting — and in a field group where each checkbox of a set has a name of its own.
The check and the dash are decorative glyphs of the icon set, hidden from assistive technology: where a glyph is written as a ligature (the web), its name ("check", "remove") is never announced or shown as text (CHK-12, CHK-19). Checked and indeterminate differ by the glyph alone, and both are exposed as states (CHK-14).
The mark is drawn at its own weight (comp.checkbox.mark.weight, CHK-12), heavier than the system's icons in the default system. Its color already has the contrast of content on its fill; what a light weight loses is the stroke, which at this size is about one pixel wide and is drawn in a mix of the mark's color and the fill's. A system that sets a lighter weight should look at the dash in particular: it is one stroke, and it is all that tells indeterminate from checked.
The selection motion is decoration too: under reduced motion the new condition is drawn whole at once, never later (CHK-17).
The label wraps at 200% text size; the box does not grow with text, because it is a control, not text.
How a state looks is a value decision of the active design system; components read the state's tokens and never compute the effect themselves.

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

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

يعرض دور خانة الاختيار (checkbox) مع حالتها (محدَّدة، أو غير محدَّدة، أو مختلطة ما دامت غير محسومة)، وحالة التعطيل، وحالة عدم الصلاحية (invalid) ما دامت error معيَّنة. ليس في React Native حالة عدم صلاحية، فالخطأ هناك يُرسم ولا يُعلَن.
التسمية هي الاسم المتاح للتقنيات المساعدة، سواء رُسمت أم أُخفيت بالخاصية labelHidden. والنص المرسوم مخفيّ عن التقنيات المساعدة، فيُقرأ الاسم مرة واحدة.
النقر أو اللمس على التسمية يبدّل خانة الاختيار. التسمية جزء من مساحة اللمس، ومساحة اللمس تستوفي الحد الأدنى للهدف.
المفتاح Space يبدّلها. والمفتاح Enter لا يبدّلها إلا حيث تفعّل المنصة أي عنصر تحكم عليه التركيز بالمفتاح Enter (Android و tvOS)؛ أما على الويب فالمفتاح Enter يرسل النموذج.
ما دامت readOnly مضبوطة تبقى قابلة للتركيز ويُعلَن عنها بأنها للقراءة فقط إلى جانب حالتها. لا يغيّرها ضغط ولا المفتاح Space ولا نقرة على التسمية ولا click()، ولا تُظهر استجابة للتمرير أو الضغط. وعلى الويب تبقى قيمتها تُرسَل، ولا تُبلغ المطلوبة منها عن قيمة ناقصة. لا تنطبق readonly في HTML على خانة الاختيار، فيتولى المكوّن ذلك بنفسه.
يعرض مؤشر التركيز حول المربع، لتركيز لوحة المفاتيح فقط.
علامة الصح والشَّرطة مخفيّتان عن التقنيات المساعدة. والحالتان المحدَّدة والمختلطة تُعلَنان من الحالة، لا من اسم الرسم أبدًا.
حيث تكون الحركة مقلَّلة يُرسم الوضع الجديد كاملًا في أول إطار بعد التغيّر، ولا يُؤخَّر ولا يُرسم نصفه أبدًا. والتغيّر الذي يقع في أثناء تغيّر آخر يكمل مما هو مرسوم في تلك اللحظة.
ما دام خط الأيقونات لا يستطيع عرض الرسم بعد، لا ترسم خانة الاختيار شيئًا مكانه، ولا ترسم الكلمة «check» أبدًا، وتظل ترسم مربعها المعبَّأ وتعرض حالتها. ويظهر الرسم فور تحميل الخط.
على الويب تشارك في النموذج كخانة اختيار أصلية: name و value و required وإعادة التعيين.
التسمية الناقصة يُبلَّغ عنها في بنيات التنقيح (debug).

فجوات معروفة في المنصات:

ما زالت SwiftUI و Compose و Flutter و React Native ترسم علامة الصح والشَّرطة بعلامات خاصة بها وتحرّكها بطريقتها، من دون الوزن الخاص بالعلامة ومن دون المربع ذي الشكل الواحد.
readOnly موجودة على الويب وحده حتى الآن: لا تملكها SwiftUI و Compose و Flutter و React Native بعد.
تحت m3-like علامة الصح هي رسم مجموعة الأيقونات وتتدرّج في الظهور وتكبر، حيث يرسم Material علامته الخاصة ضربة ضربة ويثنيها إلى الشَّرطة (فجوة المحاكاة checkbox-mark-drawn-on).

ما عليك فعله

حمِّل خط الأيقونات. إلى أن يُحمَّل تبدو خانة الاختيار المحدَّدة وغير المحسومة سواء: كلتاهما مربع معبَّأ بلا رسم. وتظل حالتاهما تُعلَنان.
إن عيَّن نظام تصميمك وزنًا أخف للعلامة (comp.checkbox.mark.weight) فانظر إلى الشَّرطة: هي خط واحد، وهي كل ما يميّز بالنظر الحالة غير المحسومة من المحدَّدة.
اكتب تسمية تسمّي الاختيار، وأبقِها كما هي سواء كانت خانة الاختيار محدَّدة أم لا. المنصة تُعلِن الحالة.
حين تكون error معيَّنة، اعرض السبب نصًّا بجانب خانة الاختيار أو في ملخّص النموذج، واربطه بخانة الاختيار. خانة الاختيار تقول إنها غير صالحة، لا لماذا. وعلى React Native الرسالة هي الطريقة الوحيدة لسماع الخطأ.
أعطِ مجموعة خانات الاختيار التي تجيب عن سؤال واحد اسمًا: على الويب، <fieldset> مع <legend>.

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