@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/checkbox.json

@@ -0,0 +1,511 @@
+{
+  "family": "checkbox",
+  "ui": "checkbox",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Box that turns one option on or off."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "tile"
+    ],
+    "labelPlacement": [
+      "end",
+      "start"
+    ]
+  },
+  "members": {
+    "checkbox": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "plain",
+        "labelPlacement": "end",
+        "indeterminate": false,
+        "parent": false
+      },
+      "capabilities": [
+        "checked",
+        "size",
+        "appearance",
+        "placement",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "checked",
+        "indeterminate"
+      ],
+      "parts": [
+        "root",
+        "label",
+        "control",
+        "indicator",
+        "description"
+      ]
+    }
+  },
+  "docs": {
+    "checkbox": {
+      "imports": {
+        "source": "import { Checkbox, CheckboxDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The two-column grid: the box in one column, the label and the description in the other. It carries data-ui=\"checkbox\", data-size, data-variant and data-label-placement, and data-checked, data-indeterminate, data-disabled, data-invalid and data-readonly. It has no role, so the native control is the only element announced. className and style reach this element."
+        },
+        {
+          "part": "control",
+          "element": "input type=\"checkbox\"",
+          "required": true,
+          "purpose": "The native checkbox. It holds the value, the name and the identifier, and receives every native attribute you write: form, required, autoFocus, every aria-* attribute and every handler. It draws the box itself with appearance: none. ref reaches it, so focus() and click() are the element’s own."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": true,
+          "purpose": "The mark, drawn over the control as a mask from the glyph scale: a check when checked, a dash when mixed. It is a sibling element rather than a pseudo-element, because Firefox renders neither ::before nor ::after on an input. It takes no pointer events, so every press reaches the control underneath."
+        },
+        {
+          "part": "label",
+          "element": "label",
+          "required": false,
+          "purpose": "Names the control through for. It carries the target and the hover wash: a 24-pixel square around the box, and a wash behind the box and the text that extends half the control gap past the box and half as far again past the text. It is as wide as its text, so the empty space beside it does not toggle the box. It renders without children too, for a box named by aria-label, and the wash then closes around the box. When its only content is visually hidden text, the root carries data-label-hidden and the wash closes the same way."
+        },
+        {
+          "part": "description",
+          "element": "p",
+          "required": false,
+          "purpose": "Help text under the label, aligned to the label rather than to the box, and referenced by aria-describedby. It sits outside the label: inside, it would join the accessible name, and a press on it would toggle the value."
+        }
+      ],
+      "api": [
+        {
+          "name": "checked",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "Makes the state controlled for the life of the component. Without it the input keeps its own state, and a native form reset restores defaultChecked. Inside a checkbox group, the group’s selection decides instead."
+        },
+        {
+          "name": "defaultChecked",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Checkbox",
+          "description": "The state an uncontrolled box starts from. It is read once and written to the input as the native attribute, which is what a form reset returns to."
+        },
+        {
+          "name": "indeterminate",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Checkbox",
+          "description": "The mixed state, drawn as a dash and announced as mixed. It is a state, not a third value of checked: the submitted value stays boolean, because indeterminate is a DOM property that leaves checked unchanged."
+        },
+        {
+          "name": "parent",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Checkbox",
+          "description": "Makes the box command the set its checkbox group lists in allValues. It is checked when every value is selected and mixed when some are, and a press selects or clears the whole set. Outside a group with allValues it has no effect."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Checkbox, CheckboxDefaultsProvider",
+          "description": "The step of the control scale. When unset, the box takes the size of its checkbox group, then of its field or field group, then of the provider. The theme restates the scale per density."
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'tile'",
+          "defaultValue": "plain",
+          "appliesTo": "Checkbox, CheckboxDefaultsProvider",
+          "description": "How the choice is drawn. tile frames it and makes the whole surface the target; the label still names the control, so the keyboard and the accessible name are unchanged. When unset, the box takes the variant of its checkbox group, then of the provider."
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'end' | 'start'",
+          "defaultValue": "end",
+          "appliesTo": "Checkbox, CheckboxDefaultsProvider",
+          "description": "Which side of its label the box sits on. When unset, the box takes the placement of its checkbox group, then of the provider. It is never read from a field, whose labelPlacement places the field’s own label."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the group or field, or false",
+          "appliesTo": "Checkbox",
+          "description": "Unset rather than false, so the box follows its checkbox group or field. Written as the native attribute, which removes the box from the tab order and from form submission."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the group or field, or false",
+          "appliesTo": "Checkbox",
+          "description": "Unset rather than false. A native checkbox has no readonly, so Checkbox refuses every change and writes aria-readonly. The box keeps its tab stop, its focus ring and its contrast, and its value is still submitted."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the group or field, or false",
+          "appliesTo": "Checkbox",
+          "description": "Unset rather than false. Writes aria-invalid on the input and data-invalid on the root, which draws a thicker border in the danger tone."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "The native attribute, passed through unchanged; Checkbox never writes it. A field marks necessity with aria-required instead, because the native attribute turns on browser constraint validation."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "Help text under the label, referenced by aria-describedby. It sits outside the label, so it describes the control instead of naming it."
+        },
+        {
+          "name": "name / value",
+          "type": "string",
+          "defaultValue": "— / on",
+          "appliesTo": "Checkbox",
+          "description": "The native submission pair: a checked box submits value under name. Inside a checkbox group, a box without a name takes the group’s, and value is the entry the group’s selection holds."
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: CheckboxRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "Replaces the root element and receives every attribute it would carry. The props are typed against HTMLAttributes<HTMLElement>, so they can be spread onto a li or a label. The input cannot be replaced, because it holds the value and the platform’s keyboard behaviour."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "Reaches the input. focus() and click() are the element’s own methods."
+        },
+        {
+          "name": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "Checkbox",
+          "description": "Reach the root. Every other native prop reaches the input."
+        },
+        {
+          "name": "CheckboxDefaultsProvider",
+          "type": "{ size, variant, labelPlacement }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets size, variant and labelPlacement once for every box under it, merged over an outer provider. A box that states a value keeps it. A checkbox group around the box outranks the provider for all three, and a field or field group outranks it for size."
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What the box reads from a field: its disabled, readOnly, invalid and required states, its description and error, and its size. The box never takes the field’s identifier: it has its own label, and the field’s label would name the same control twice."
+        }
+      ],
+      "events": [
+        {
+          "name": "onCheckedChange",
+          "payload": "(checked: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before the box moves. request.value is the new state and request.previous the state it replaces. request.reason is pointer or keyboard, read from the click’s detail, and request.source is the originating event. request.cancel() refuses the change before anything commits, including the platform’s own toggle."
+        },
+        {
+          "name": "onChange, onClick, onFocus, onBlur",
+          "payload": "the element’s own events",
+          "when": "Whenever the input fires them. Checkbox composes your handler with its own instead of replacing it: yours runs first, and always runs. Calling preventDefault() in onClick stops the change as well."
+        }
+      ],
+      "accessibility": [
+        "Checkbox follows the WAI-ARIA Authoring Practices checkbox pattern (w3.org/WAI/ARIA/apg/patterns/checkbox/), and the native input supplies every part of it: the role, the checked and mixed states, Space to toggle, Enter left to the form, and disabled behaviour. Checkbox adds no key listener, so the keyboard behaviour is the platform’s in every language and in right-to-left documents.",
+        "The label names the control through for, which points at an identifier Checkbox generates when you pass no id. The description sits outside the label and reaches the control through aria-describedby, so it is read as a description, and a press on it toggles nothing.",
+        "Inside a required field the control carries aria-required, never the native required, because the native attribute turns on browser constraint validation and changes how the form submits. Pass required on the box to opt into the platform’s validation; Checkbox leaves it unchanged. disabled is the native attribute.",
+        "A native checkbox has no read-only state, so Checkbox enforces one: it refuses the click that a pointer and Space both produce, and aria-readonly announces the state. The box keeps its tab stop, its focus ring and its full contrast, because a read-only value is real and must not look disabled.",
+        "The invalid state does not rely on colour alone. In the high-contrast scheme the theme paints every border the same colour, so an invalid box also draws a thicker border. The message that says what is wrong belongs to the field or field group.",
+        "The target is larger than the box. A 24-pixel square around the box meets WCAG 2.2 success criterion 2.5.8 at every size and density, including size=\"sm\", where the box is 14 pixels. The label extends the target to the end of its text, and the hover wash covers exactly that area. The target is drawn around the box, so the row keeps its line height.",
+        "The mark stays visible under forced colours. It is a mask over a background colour, and forced colours replace both, so Checkbox restates the pair in system colours."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-width-medium",
+    "--slotted-border-width-thick",
+    "--slotted-checkbox-active-background",
+    "--slotted-checkbox-background",
+    "--slotted-checkbox-border-color",
+    "--slotted-checkbox-border-width",
+    "--slotted-checkbox-checked-active-background",
+    "--slotted-checkbox-checked-background",
+    "--slotted-checkbox-checked-border-color",
+    "--slotted-checkbox-checked-hover-background",
+    "--slotted-checkbox-color",
+    "--slotted-checkbox-description-color",
+    "--slotted-checkbox-description-font-size",
+    "--slotted-checkbox-disabled-background",
+    "--slotted-checkbox-disabled-border-color",
+    "--slotted-checkbox-disabled-color",
+    "--slotted-checkbox-disabled-mark-color",
+    "--slotted-checkbox-halo-color",
+    "--slotted-checkbox-hover-border-color",
+    "--slotted-checkbox-invalid-border-color",
+    "--slotted-checkbox-invalid-checked-background",
+    "--slotted-checkbox-invalid-edge-width",
+    "--slotted-checkbox-invalid-focus-ring-color",
+    "--slotted-checkbox-line-height",
+    "--slotted-checkbox-mark-color",
+    "--slotted-checkbox-mark-inset",
+    "--slotted-checkbox-radius",
+    "--slotted-checkbox-readonly-background",
+    "--slotted-checkbox-size",
+    "--slotted-checkbox-tile-active-background",
+    "--slotted-checkbox-tile-background",
+    "--slotted-checkbox-tile-border-color",
+    "--slotted-checkbox-tile-checked-background",
+    "--slotted-checkbox-tile-checked-border-color",
+    "--slotted-checkbox-tile-checked-hover-border-color",
+    "--slotted-checkbox-tile-description-gap",
+    "--slotted-checkbox-tile-disabled-background",
+    "--slotted-checkbox-tile-disabled-border-color",
+    "--slotted-checkbox-tile-hover-background",
+    "--slotted-checkbox-tile-hover-border-color",
+    "--slotted-checkbox-tile-inset",
+    "--slotted-checkbox-tile-invalid-border-color",
+    "--slotted-checkbox-tile-invalid-checked-background",
+    "--slotted-checkbox-tile-invalid-checked-border-color",
+    "--slotted-checkbox-tile-radius",
+    "--slotted-checkbox-tile-readonly-background",
+    "--slotted-checkbox-tile-readonly-border-color",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-label-gap-lg",
+    "--slotted-control-label-gap-md",
+    "--slotted-control-label-gap-sm",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-shadow",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-medium",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-xs",
+    "--slotted-line-height-md",
+    "--slotted-line-height-xs",
+    "--slotted-radius-md",
+    "--slotted-radius-xs",
+    "--slotted-selection-halo-opacity",
+    "--slotted-selection-size-lg",
+    "--slotted-selection-size-md",
+    "--slotted-selection-size-sm",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-surface",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-on-solid",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-accent-solid-active",
+    "--slotted-tone-accent-solid-hover",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-solid",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One box with every axis on it, driven by the controls below the canvas. Click the label, not only the box: the target runs from the square to the end of the text.",
+      "language": "tsx",
+      "source": "<Checkbox description=\"Enviaremos o recibo por e-mail.\" defaultChecked>\n  Enviar recibo\n</Checkbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the box sits at",
+      "note": "The square is the control glyph scale, so the three steps shrink together with the type and the gap when the toolbar switches to dense — and the label keeps its 24-pixel target at every one of them.",
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxSizes() {\n  return (\n    <Stack gap={4}>\n      <Checkbox size=\"sm\" defaultChecked>\n        Show archived orders\n      </Checkbox>\n      <Checkbox size=\"md\" defaultChecked>\n        Notify the warehouse\n      </Checkbox>\n      <Checkbox size=\"lg\" defaultChecked>\n        Remember this device\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tile",
+      "title": "The choice as a framed surface",
+      "note": "Click anywhere inside a tile, not only the box: the label’s hit area stretches over the whole surface, so the target is the frame. Chosen says it with a two-pixel accent edge as well as a tint, because the high-contrast scheme flattens every tint to white and only the width survives.",
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Grid } from '@slotted/react/grid';\n\nexport default function CheckboxTile() {\n  return (\n    <Grid gap={4} minItemWidth=\"sm\">\n      <Checkbox variant=\"tile\" defaultChecked description=\"One copy a day, kept for 30 days.\">\n        Daily backup\n      </Checkbox>\n      <Checkbox variant=\"tile\" description=\"Who changed what, and when, exported as CSV.\">\n        Audit log\n      </Checkbox>\n      <Checkbox variant=\"tile\" disabled description=\"Available on the Scale plan.\">\n        Secondary region\n      </Checkbox>\n    </Grid>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "Every state the box paints",
+      "note": "Read-only keeps full-strength ink, its ring and its tab stop, because the value is real and still submitted; disabled loses all three. Invalid thickens the border as well as reddening it, because the high-contrast scheme paints every border the same black.",
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxStates() {\n  return (\n    <Stack gap={4}>\n      <Checkbox readOnly defaultChecked description=\"Set by the customer's tax certificate.\">\n        Tax exempt\n      </Checkbox>\n      <Checkbox disabled description=\"Not offered from the Seattle warehouse.\">\n        Same-day delivery\n      </Checkbox>\n      <Checkbox invalid description=\"Confirm the count before closing the cycle.\">\n        I counted every item on shelf A-14\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "indeterminate",
+      "title": "The mixed state, and the box that commands a set",
+      "note": "Mixed is a state and never a third value: the form still submits a boolean. Tick the parent and the whole set follows; untick one child and the parent goes back to the dash on its own.",
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\n\nfunction summary(taxable: boolean | 'mixed'): string {\n  if (taxable === 'mixed') return 'Taxed on 2 of the 3 selected products.';\n  return taxable\n    ? 'All 3 selected products will be taxed.'\n    : 'None of the 3 selected products will be taxed.';\n}\n\nexport default function CheckboxIndeterminate() {\n  const [taxable, setTaxable] = useState<boolean | 'mixed'>('mixed');\n\n  return (\n    <Stack gap={3}>\n      <Text weight=\"medium\">Edit 3 products</Text>\n      <Checkbox\n        checked={taxable === true}\n        indeterminate={taxable === 'mixed'}\n        onCheckedChange={(checked) => setTaxable(checked)}\n        description={summary(taxable)}\n      >\n        Taxable\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "placement",
+      "title": "Which side of its label the box is on",
+      "note": "start pushes the box to the end of the row, which is where a settings list puts a control — and it is why the column is a fraction rather than the label’s own width: five boxes have to line up with each other.",
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxPlacement() {\n  return (\n    <Stack gap={3}>\n      <Checkbox labelPlacement=\"start\" defaultChecked>\n        Email when an order ships\n      </Checkbox>\n      <Checkbox labelPlacement=\"start\">Email when stock runs low</Checkbox>\n      <Checkbox labelPlacement=\"start\" defaultChecked>\n        Weekly sales digest\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "description",
+      "title": "Saying more than the label does",
+      "note": "The description aligns under the label rather than under the box, in both placements and both writing directions, and it is announced as the control’s description rather than as part of its name.",
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxDescription() {\n  return (\n    <Stack gap={4}>\n      <Checkbox\n        defaultChecked\n        description=\"One message per failed payment, sent to the billing contact.\"\n      >\n        Email me when a payment fails\n      </Checkbox>\n      <Checkbox description=\"Sent at 08:00 in the account's time zone, and skipped on days with no failures.\">\n        Send a daily summary instead\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "field",
+      "title": "Inside a field, and inside a group of fields",
+      "note": "The box reads the field for its step and its four shared states and never for its identifier: it owns its own label, and a field’s label would name the same control twice.",
+      "language": "tsx",
+      "source": "<FieldGroup required>\n  <FieldGroupLegend>Notificações</FieldGroupLegend>\n  <CheckboxGroup name=\"alerts\">\n    <Checkbox value=\"approved\">Pedido aprovado</Checkbox>\n    <Checkbox value=\"refused\">Pedido recusado</Checkbox>\n  </CheckboxGroup>\n</FieldGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A label that wraps to three lines keeps the box on the first of them rather than in the middle of the block, an unbroken token breaks instead of taking the page with it, and a right-to-left label mirrors the whole row.",
+      "language": "tsx",
+      "source": "<Checkbox description=\"A caixa continua na primeira linha do rótulo.\">\n  Concordo em receber comunicações sobre alterações contratuais, prazos de entrega e mudanças na\n  política de devolução.\n</Checkbox>;\n\n<Checkbox dir=\"rtl\">أوافق على تلقي رسائل حول التغييرات في العقد.</Checkbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "The provider carries the two decisions an application takes once; render substitutes the root so a box can be a list item; ref reaches the element, which already has focus and click.",
+      "language": "tsx",
+      "source": "<CheckboxDefaultsProvider labelPlacement=\"start\" size=\"sm\">\n  <Checkbox>Herda os dois</Checkbox>\n</CheckboxDefaultsProvider>;\n\nconst ref = useRef<HTMLInputElement>(null);\n<Checkbox ref={ref} onCheckedChange={() => ref.current?.focus()} />;\n\n// The root becomes the consumer's own element, with every attribute.\n<Checkbox render={(props) => <li {...props} />}>Um item</Checkbox>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and who implements it",
+      "note": "Space toggles and Enter submits the form, and neither is a listener this family writes: the control is a native checkbox, so the whole table is the platform’s and arrives translated and mirrored for free.",
+      "language": "tsx",
+      "source": "// Space and a pointer arrive as one click. A click synthesised by the\n// keyboard reports no detail, which is how the reason is told apart\n// without a key listener existing anywhere in the family.\n<Checkbox\n  onCheckedChange={(checked, request) => {\n    console.log(request.reason); // \"keyboard\" | \"pointer\"\n  }}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxBasic() {\n  return (\n    <Stack gap={3}>\n      <Checkbox defaultChecked>Email the invoice to the customer</Checkbox>\n      <Checkbox defaultChecked>Include a packing slip</Checkbox>\n      <Checkbox>Gift-wrap the order</Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Stack } from '@slotted/react/stack';\nimport { TextField } from '@slotted/react/text-field';\n\nexport default function CheckboxControlled() {\n  const [sameAddress, setSameAddress] = useState(true);\n\n  return (\n    <Stack gap={4}>\n      <Checkbox\n        checked={sameAddress}\n        onCheckedChange={(checked) => setSameAddress(checked)}\n        description=\"Ships to 12 Orchestra Terrace, Walla Walla, WA 99362.\"\n      >\n        Bill to the shipping address\n      </Checkbox>\n      {sameAddress ? null : (\n        <Field required>\n          <FieldLabel>Billing address</FieldLabel>\n          <TextField autoComplete=\"billing street-address\" />\n        </Field>\n      )}\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox, CheckboxDefaultsProvider } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxDefaults() {\n  return (\n    <CheckboxDefaultsProvider size=\"sm\" labelPlacement=\"start\">\n      <Stack gap={2}>\n        <Checkbox defaultChecked>Show prices with tax</Checkbox>\n        <Checkbox>Show discontinued products</Checkbox>\n        <Checkbox defaultChecked>Group orders by customer</Checkbox>\n      </Stack>\n    </CheckboxDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "form",
+      "title": "form.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\n\nexport default function CheckboxForm() {\n  const [saved, setSaved] = useState<string | null>(null);\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    const reports = new FormData(event.currentTarget).getAll('reports');\n    setSaved(reports.length === 0 ? 'none' : reports.join(', '));\n  };\n\n  return (\n    <form onSubmit={submit} onReset={() => setSaved(null)}>\n      <Stack gap={4}>\n        <FieldGroup>\n          <FieldGroupLegend>Reports emailed each morning</FieldGroupLegend>\n          <FieldGroupContent>\n            <Stack gap={2}>\n              <Checkbox name=\"reports\" value=\"daily-sales\" defaultChecked>\n                Daily sales\n              </Checkbox>\n              <Checkbox name=\"reports\" value=\"low-stock\">\n                Low stock\n              </Checkbox>\n              <Checkbox name=\"reports\" value=\"payouts\" defaultChecked>\n                Payouts\n              </Checkbox>\n            </Stack>\n          </FieldGroupContent>\n        </FieldGroup>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Save</Button>\n          <Button type=\"reset\" variant=\"outline\" tone=\"secondary\">\n            Reset\n          </Button>\n        </Inline>\n        <Text size=\"sm\" tone=\"muted\" role=\"status\">\n          {saved === null ? '' : `Submitted reports: ${saved}.`}\n        </Text>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "hidden-label",
+      "title": "hidden-label.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\nimport { VisuallyHidden } from '@slotted/react/visually-hidden';\n\nconst INVOICES = [\n  { id: 'INV-1042', customer: 'Alfreds Futterkiste', amount: '$1,250.00' },\n  { id: 'INV-1043', customer: 'Ernst Handel', amount: '$4,318.40' },\n  { id: 'INV-1044', customer: 'Island Trading', amount: '$872.15' },\n];\n\nexport default function CheckboxHiddenLabel() {\n  return (\n    <Stack gap={2}>\n      {INVOICES.map((invoice) => (\n        <Inline key={invoice.id} gap={3} align=\"center\">\n          <Checkbox size=\"sm\" value={invoice.id}>\n            <VisuallyHidden>Select {invoice.id}</VisuallyHidden>\n          </Checkbox>\n          <Text numeric=\"tabular\">{invoice.id}</Text>\n          <Text tone=\"muted\">{invoice.customer}</Text>\n          <Text numeric=\"tabular\">{invoice.amount}</Text>\n        </Inline>\n      ))}\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "long-label",
+      "title": "long-label.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxLongLabel() {\n  return (\n    <Stack gap={4}>\n      <Checkbox defaultChecked description=\"Notices go to the billing contact on the account.\">\n        Send notices about contract changes, delivery deadlines and changes to the return policy for\n        this store and every other store in the group\n      </Checkbox>\n      <Checkbox>\n        Forward order events to https://hooks.northwind.example/orders/fulfilment-updates\n      </Checkbox>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "parent",
+      "title": "parent.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nconst WEEKDAYS = ['mon', 'tue', 'wed', 'thu', 'fri'];\n\nexport default function CheckboxParent() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Delivery days</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup allValues={WEEKDAYS} defaultValue={['mon', 'wed', 'fri']} name=\"days\">\n          <Checkbox parent>Every weekday</Checkbox>\n          <Checkbox value=\"mon\">Monday</Checkbox>\n          <Checkbox value=\"tue\">Tuesday</Checkbox>\n          <Checkbox value=\"wed\">Wednesday</Checkbox>\n          <Checkbox value=\"thu\">Thursday</Checkbox>\n          <Checkbox value=\"fri\">Friday</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { Field, FieldError } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxValidation() {\n  const [accepted, setAccepted] = useState(false);\n  const [submitted, setSubmitted] = useState(false);\n  const [placed, setPlaced] = useState(false);\n  const error = submitted && !accepted ? 'Accept the supplier terms to place the order.' : '';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    setPlaced(accepted);\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <Field required invalid={error !== '' ? true : undefined}>\n          <Checkbox\n            checked={accepted}\n            onCheckedChange={(checked) => {\n              setAccepted(checked);\n              setPlaced(false);\n            }}\n          >\n            I accept the supplier terms for this purchase order\n          </Checkbox>\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Place order</Button>\n          {placed ? <span role=\"status\">Order placed.</span> : null}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}

package/dist/docs/checkbox.md

@@ -0,0 +1,95 @@
+<!-- index: ./index.md -->
+# checkbox
+
+`data-ui="checkbox"` · Box that turns one option on or off.
+
+## Import
+
+```tsx
+import { Checkbox, CheckboxDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Checkbox } from '@slotted/react/checkbox';
+import { Stack } from '@slotted/react/stack';
+
+export default function CheckboxBasic() {
+  return (
+    <Stack gap={3}>
+      <Checkbox defaultChecked>Email the invoice to the customer</Checkbox>
+      <Checkbox defaultChecked>Include a packing slip</Checkbox>
+      <Checkbox>Gift-wrap the order</Checkbox>
+    </Stack>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `control` | input type="checkbox" | yes |
+| `indicator` | span | yes |
+| `label` | label | no |
+| `description` | p | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean` | — | Checkbox | Makes the state controlled for the life of the component. Without it the input keeps its own state, and a native form reset restores defaultChecked. Inside a checkbox group, the group’s selection decides instead. |
+| `defaultChecked` | `boolean` | false | Checkbox | The state an uncontrolled box starts from. It is read once and written to the input as the native attribute, which is what a form reset returns to. |
+| `indeterminate` | `boolean` | false | Checkbox | The mixed state, drawn as a dash and announced as mixed. It is a state, not a third value of checked: the submitted value stays boolean, because indeterminate is a DOM property that leaves checked unchanged. |
+| `parent` | `boolean` | false | Checkbox | Makes the box command the set its checkbox group lists in allValues. It is checked when every value is selected and mixed when some are, and a press selects or clears the whole set. Outside a group with allValues it has no effect. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Checkbox, CheckboxDefaultsProvider | The step of the control scale. When unset, the box takes the size of its checkbox group, then of its field or field group, then of the provider. The theme restates the scale per density. |
+| `variant` | `'plain' \| 'tile'` | plain | Checkbox, CheckboxDefaultsProvider | How the choice is drawn. tile frames it and makes the whole surface the target; the label still names the control, so the keyboard and the accessible name are unchanged. When unset, the box takes the variant of its checkbox group, then of the provider. |
+| `labelPlacement` | `'end' \| 'start'` | end | Checkbox, CheckboxDefaultsProvider | Which side of its label the box sits on. When unset, the box takes the placement of its checkbox group, then of the provider. It is never read from a field, whose labelPlacement places the field’s own label. |
+| `disabled` | `boolean` | from the group or field, or false | Checkbox | Unset rather than false, so the box follows its checkbox group or field. Written as the native attribute, which removes the box from the tab order and from form submission. |
+| `readOnly` | `boolean` | from the group or field, or false | Checkbox | Unset rather than false. A native checkbox has no readonly, so Checkbox refuses every change and writes aria-readonly. The box keeps its tab stop, its focus ring and its contrast, and its value is still submitted. |
+| `invalid` | `boolean` | from the group or field, or false | Checkbox | Unset rather than false. Writes aria-invalid on the input and data-invalid on the root, which draws a thicker border in the danger tone. |
+| `required` | `boolean` | — | Checkbox | The native attribute, passed through unchanged; Checkbox never writes it. A field marks necessity with aria-required instead, because the native attribute turns on browser constraint validation. |
+| `description` | `ReactNode` | — | Checkbox | Help text under the label, referenced by aria-describedby. It sits outside the label, so it describes the control instead of naming it. |
+| `name / value` | `string` | — / on | Checkbox | The native submission pair: a checked box submits value under name. Inside a checkbox group, a box without a name takes the group’s, and value is the entry the group’s selection holds. |
+| `render` | `(props: CheckboxRootProps) => ReactNode` | — | Checkbox | Replaces the root element and receives every attribute it would carry. The props are typed against HTMLAttributes<HTMLElement>, so they can be spread onto a li or a label. The input cannot be replaced, because it holds the value and the platform’s keyboard behaviour. |
+| `ref` | `Ref<HTMLInputElement>` | — | Checkbox | Reaches the input. focus() and click() are the element’s own methods. |
+| `className / style` | `string / CSSProperties` | — | Checkbox | Reach the root. Every other native prop reaches the input. |
+| `CheckboxDefaultsProvider` | `{ size, variant, labelPlacement }` | — | a subtree | Sets size, variant and labelPlacement once for every box under it, merged over an outer provider. A box that states a value keeps it. A checkbox group around the box outranks the provider for all three, and a field or field group outranks it for size. |
+| `useField()` | `() => FieldContextValue \| undefined` | — | inside a Field | What the box reads from a field: its disabled, readOnly, invalid and required states, its description and error, and its size. The box never takes the field’s identifier: it has its own label, and the field’s label would name the same control twice. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onCheckedChange` | `(checked: boolean, request: ChangeRequest<boolean>)` | Before the box moves. request.value is the new state and request.previous the state it replaces. request.reason is pointer or keyboard, read from the click’s detail, and request.source is the originating event. request.cancel() refuses the change before anything commits, including the platform’s own toggle. |
+| `onChange, onClick, onFocus, onBlur` | `the element’s own events` | Whenever the input fires them. Checkbox composes your handler with its own instead of replacing it: yours runs first, and always runs. Calling preventDefault() in onClick stops the change as well. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `tile` | `plain` |
+| `labelPlacement` | `end`, `start` | `end` |
+
+## Rules
+
+- Checkbox follows the WAI-ARIA Authoring Practices checkbox pattern (w3.org/WAI/ARIA/apg/patterns/checkbox/), and the native input supplies every part of it: the role, the checked and mixed states, Space to toggle, Enter left to the form, and disabled behaviour. Checkbox adds no key listener, so the keyboard behaviour is the platform’s in every language and in right-to-left documents.
+- The label names the control through for, which points at an identifier Checkbox generates when you pass no id. The description sits outside the label and reaches the control through aria-describedby, so it is read as a description, and a press on it toggles nothing.
+- Inside a required field the control carries aria-required, never the native required, because the native attribute turns on browser constraint validation and changes how the form submits. Pass required on the box to opt into the platform’s validation; Checkbox leaves it unchanged. disabled is the native attribute.
+- A native checkbox has no read-only state, so Checkbox enforces one: it refuses the click that a pointer and Space both produce, and aria-readonly announces the state. The box keeps its tab stop, its focus ring and its full contrast, because a read-only value is real and must not look disabled.
+- The invalid state does not rely on colour alone. In the high-contrast scheme the theme paints every border the same colour, so an invalid box also draws a thicker border. The message that says what is wrong belongs to the field or field group.
+- The target is larger than the box. A 24-pixel square around the box meets WCAG 2.2 success criterion 2.5.8 at every size and density, including size="sm", where the box is 14 pixels. The label extends the target to the end of its text, and the hover wash covers exactly that area. The target is drawn around the box, so the row keeps its line height.
+- The mark stays visible under forced colours. It is a mask over a background colour, and forced colours replace both, so Checkbox restates the pair in system colours.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-checkbox-active-background`, `--slotted-checkbox-background`, `--slotted-checkbox-border-color`, `--slotted-checkbox-border-width`, `--slotted-checkbox-checked-active-background`, `--slotted-checkbox-checked-background`, `--slotted-checkbox-checked-border-color`, `--slotted-checkbox-checked-hover-background`, `--slotted-checkbox-color`, `--slotted-checkbox-description-color`, `--slotted-checkbox-description-font-size`, `--slotted-checkbox-disabled-background`, `--slotted-checkbox-disabled-border-color`, `--slotted-checkbox-disabled-color`, `--slotted-checkbox-disabled-mark-color`, `--slotted-checkbox-halo-color`, `--slotted-checkbox-hover-border-color`, `--slotted-checkbox-invalid-border-color`, `--slotted-checkbox-invalid-checked-background`, `--slotted-checkbox-invalid-edge-width`, `--slotted-checkbox-invalid-focus-ring-color`, `--slotted-checkbox-line-height`, `--slotted-checkbox-mark-color`, `--slotted-checkbox-mark-inset`, `--slotted-checkbox-radius`, `--slotted-checkbox-readonly-background`, `--slotted-checkbox-size`, `--slotted-checkbox-tile-active-background`, `--slotted-checkbox-tile-background`, `--slotted-checkbox-tile-border-color`, `--slotted-checkbox-tile-checked-background`, `--slotted-checkbox-tile-checked-border-color`, `--slotted-checkbox-tile-checked-hover-border-color`, `--slotted-checkbox-tile-description-gap`, `--slotted-checkbox-tile-disabled-background`, `--slotted-checkbox-tile-disabled-border-color`, `--slotted-checkbox-tile-hover-background`, `--slotted-checkbox-tile-hover-border-color`, `--slotted-checkbox-tile-inset`, `--slotted-checkbox-tile-invalid-border-color`, `--slotted-checkbox-tile-invalid-checked-background`, `--slotted-checkbox-tile-invalid-checked-border-color`, `--slotted-checkbox-tile-radius`, `--slotted-checkbox-tile-readonly-background`, `--slotted-checkbox-tile-readonly-border-color`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-label-gap-lg`, `--slotted-control-label-gap-md`, `--slotted-control-label-gap-sm`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-radius-md`, `--slotted-radius-xs`, `--slotted-selection-halo-opacity`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [checkbox.examples.md](./checkbox.examples.md).