@charcuterie/ui 3.6.0 → 3.7.0

package/dist/slotProps.js.map

@@ -1 +1 @@
-{"version":3,"file":"slotProps.js","sourceRoot":"","sources":["../src/slotProps.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AA6FjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAG5B,aAAwB,EACxB,QAAkB,EACI,EAAE;IACxB,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CACxC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CACnC,CACU,CAAA;IAEb,MAAM,WAAW,GAAG;QAClB,aAAa,CAAC,kBAAkB,CAAC;QACjC,QAAQ,CAAC,kBAAkB,CAAC;KAC7B;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO;QACL,GAAG,aAAa;QAChB,GAAG,eAAe;QAClB,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QAC9C,sDAAsD;QACtD,6DAA6D;QAC7D,8BAA8B;QAC9B,GAAG,eAAe,CAChB,aAAwC,EACxC,eAAe,CAChB;KACF,CAAA;AACH,CAAC,CAAA"}
+{"version":3,"file":"slotProps.js","sourceRoot":"","sources":["../src/slotProps.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AA6FjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAI5B,aAA4B,EAC5B,QAAkB,EACQ,EAAE;IAC5B,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CACxC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CACnC,CACU,CAAA;IAEb,MAAM,WAAW,GAAG;QAClB,aAAa,CAAC,kBAAkB,CAAC;QACjC,QAAQ,CAAC,kBAAkB,CAAC;KAC7B;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAA;IAEZ,OAAO;QACL,GAAG,aAAa;QAChB,GAAG,eAAe;QAClB,kBAAkB,EAChB,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QAC9C,sDAAsD;QACtD,6DAA6D;QAC7D,8BAA8B;QAC9B,GAAG,eAAe,CAChB,aAAwC,EACxC,eAAe,CAChB;KACF,CAAA;AACH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@charcuterie/ui",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "The Charcuterie components. Tokens for look, @charcuterie/logic for state, ARIA that agents can actually drive.",
   "license": "MIT",
   "type": "module",

package/src/Checkbox/Checkbox.mdx

@@ -86,6 +86,38 @@ does not become one. `isChecked` still seeds the box, `onChange` still reports a
 
 <Canvas of={CheckboxStories.WithValues} />
 
+## A hint follows the box
+
+`description` is standing help bound with `aria-describedby`, so a screen reader reads it
+**with** the control rather than announcing it from nowhere — the same slot, the same words
+and the same announcement order as [`Field`](/docs/components-field--docs)'s.
+
+`Field` has had one since it shipped and this component had none, which is a gap you only
+feel in a mixed box: a hint after a checkbox had to be the app's own paragraph while the
+hint after the `Field` two rows down came from the library, and the two disagreed about how
+big a hint is. One control's help looking unlike its neighbour's, in the same editor.
+
+The hint renders **outside** the `<label>`, which is the only place it can go. A `<label>`'s
+text content *is* the control's accessible name, so a hint inside it would be announced
+twice — once inside the name, once again as the description — and a pointer press on a
+sentence of explanation would toggle the box. So the `<label>` is no longer the outermost
+element this component renders: a `<div>` holds the row and the hint, and `className` moves
+out to it, because `className` is the outermost box a component renders and that rule does
+not bend for this one.
+
+Two smaller decisions inside it:
+
+- **`opacity-60` stays on the `<label>`** and does not reach the hint. axe exempts a
+  disabled control and its own label from the colour-contrast rule and exempts nothing else,
+  so dimming the hint with the box measures **3.77:1** on `midnight` against a 4.5
+  threshold. A hint nobody can read is worse than a hint that does not dim, and a turned-off
+  box is exactly when that sentence gets read.
+- **There is no `error` to go with it.** `Field` derives `aria-invalid` from its error, and a
+  lone boolean is almost never the invalid thing — a *group* of them is, and a group's error
+  belongs on the `FieldGroup` around it, described rather than asserted.
+
+<Canvas of={CheckboxStories.WithDescriptions} />
+
 ## Checkbox or `Switch`
 
 Same state kind, different meaning. A checkbox is a value you **submit** — "delete

package/src/Checkbox/Checkbox.stories.tsx

@@ -6,6 +6,7 @@ import {
   StoryGrid,
   StorySection,
 } from "../board.storyHelpers.tsx"
+import { FieldGroup } from "../Field/FieldGroup.tsx"
 import { Checkbox } from "./Checkbox.tsx"
 
 const meta = {
@@ -162,3 +163,76 @@ export const WithValues: Story = {
     </StorySection>
   ),
 }
+
+/**
+ * `description` is standing help that follows the box, bound with
+ * `aria-describedby` so a screen reader reads it **with** the control
+ * — the same slot, the same words and the same announcement order as
+ * `Field`'s.
+ *
+ * It renders outside the `<label>`, which is the only place it can go:
+ * a `<label>`'s text content *is* the control's accessible name, so a
+ * hint inside it would be announced twice and a pointer press on it
+ * would toggle the box.
+ *
+ * The gap this closes is a mixed box. Before it, a hint after a
+ * checkbox had to be the app's own paragraph while the hint after the
+ * `Field` two rows down came from the library, and the two disagreed
+ * about the size of a hint — one control's help looking unlike its
+ * neighbour's, in the same editor.
+ */
+export const WithDescriptions: Story = {
+  args: { label: "Delete originals after import" },
+  render: (controlProps) => (
+    <StorySection title="One hint typography for the whole library: `text-sm`, `content-secondary`, hung under the label text rather than under the box.">
+      <StoryGrid columns={2}>
+        <StoryCell label="described">
+          <Checkbox
+            {...controlProps}
+            description="The source files are removed once every title has been written."
+            label="Delete originals after import"
+          />
+        </StoryCell>
+
+        <StoryCell label="described and checked">
+          <Checkbox
+            {...controlProps}
+            description="Nothing plays after the last title finishes."
+            isChecked
+            label="Turn everything off when it finishes"
+          />
+        </StoryCell>
+
+        <StoryCell label="described and disabled">
+          <Checkbox
+            {...controlProps}
+            description="A turned-off box is exactly when this sentence gets read, so it keeps full contrast."
+            isDisabled
+            label="Re-encode to the archive profile"
+          />
+        </StoryCell>
+
+        <StoryCell label="described, in a group">
+          <FieldGroup
+            description="A group's own help sits under all of it."
+            label="After a rip"
+          >
+            <Checkbox
+              {...controlProps}
+              description="Written beside the video, not into it."
+              label="Keep chapter markers"
+              size="sm"
+            />
+
+            <Checkbox
+              {...controlProps}
+              description="Costs a second pass over each title."
+              label="Verify the checksum"
+              size="sm"
+            />
+          </FieldGroup>
+        </StoryCell>
+      </StoryGrid>
+    </StorySection>
+  ),
+}

package/src/Checkbox/Checkbox.test.tsx

@@ -7,8 +7,13 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./Checkbox.stories.tsx"
 
-const { AllStates, Default, Interactive, WithValues } =
-  composeStories(stories)
+const {
+  AllStates,
+  Default,
+  Interactive,
+  WithDescriptions,
+  WithValues,
+} = composeStories(stories)
 
 test("it is a checkbox a screen reader can name", async () => {
   const { canvas, canvasElement } =
@@ -158,3 +163,106 @@ test("a box with no value stays out of the way", async () => {
     }),
   ).not.toHaveAttribute("value")
 })
+
+/**
+ * The description is *announced*, which is the only claim worth
+ * asserting — a hint that renders and is not bound to the control is
+ * decoration, and that is what an app-styled paragraph beside a
+ * checkbox already was.
+ *
+ * The second half is the trap: the hint must be **outside** the
+ * `<label>`. A `<label>`'s text content is the control's accessible
+ * name, so a hint inside it would be read once inside the name and
+ * once again as the description, and the name assertion below is what
+ * catches that — it fails on "Delete originals after import The source
+ * files are removed…".
+ */
+test("a description is announced with the box, and stays out of its name", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    WithDescriptions,
+  )
+
+  const checkbox = expectAgentDrivable(canvas, {
+    name: "Delete originals after import",
+    role: "checkbox",
+  })
+
+  await expect(
+    document.getElementById(
+      checkbox.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent(
+    "The source files are removed once every title has been written.",
+  )
+
+  // The hint is a sibling of the `<label>`, not a descendant of it.
+  await expect(checkbox.closest("label")?.textContent).toBe(
+    "Delete originals after import",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * A group of described boxes inside a `FieldGroup` — the shape the
+ * downstream editor wanted and could not write, because one hint out
+ * of three had to be the app's own paragraph.
+ *
+ * Each box names its own hint and the group names the group's, so
+ * three `aria-describedby` values point at three different nodes and
+ * none of them collide.
+ */
+test("each box owns its own description, and the group owns the group's", async () => {
+  const { canvas, canvasElement } = await mountStory(
+    WithDescriptions,
+  )
+
+  const group = expectAgentDrivable(canvas, {
+    name: "After a rip",
+    role: "group",
+  })
+
+  await expect(
+    document.getElementById(
+      group.getAttribute("aria-describedby") ?? "",
+    ),
+  ).toHaveTextContent(
+    "A group's own help sits under all of it.",
+  )
+
+  const describedIds = [
+    "Keep chapter markers",
+    "Verify the checksum",
+  ].map((name) =>
+    expectAgentDrivable(canvas, {
+      name,
+      role: "checkbox",
+    }).getAttribute("aria-describedby"),
+  )
+
+  await expect(new Set(describedIds).size).toBe(2)
+
+  await expect(
+    document.getElementById(describedIds[0] ?? ""),
+  ).toHaveTextContent(
+    "Written beside the video, not into it.",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a box with no description writes no aria-describedby", async () => {
+  const { canvas } = await mountStory(Default)
+
+  // The slot is opt-in. React drops an `undefined` attribute rather
+  // than writing an empty string, so a box without a hint points at
+  // nothing — an `aria-describedby` naming an id that is not in the
+  // document is the defect `Field` was built to prevent, and it would
+  // arrive here the moment the id were written unconditionally.
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Delete originals after import",
+      role: "checkbox",
+    }),
+  ).not.toHaveAttribute("aria-describedby")
+})

package/src/Checkbox/Checkbox.tsx

@@ -1,3 +1,4 @@
+import { useUniqueId } from "@charcuterie/logic"
 import type { ControlSize } from "@charcuterie/tokens"
 import type { ChangeEvent, ReactNode } from "react"
 
@@ -6,6 +7,20 @@ import { toClassName } from "../toClassName.ts"
 
 export type CheckboxProps = {
   className?: string
+  /**
+   * Standing help under the box — units, a consequence, a warning
+   * about what ticking it does. Same slot, same words and same
+   * announcement order as `Field`'s: bound with `aria-describedby`,
+   * so a screen reader reads it **with** the control rather than
+   * announcing it from nowhere.
+   *
+   * It renders **outside** the `<label>` on purpose. A `<label>`'s
+   * text content *is* the control's accessible name, so a hint put
+   * inside it would be read twice — once as part of the name, once as
+   * the description — and a pointer press anywhere on the hint would
+   * toggle the box.
+   */
+  description?: ReactNode
   /**
    * The caller's own id, when it has one — a stable target for an
    * autofill hint or a deep link. Left to React's `useId` on the
@@ -77,6 +92,25 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
   lg: "text-lg",
 }
 
+/**
+ * The description hangs under the **label text**, not under the box,
+ * so the hint and the words it explains share a left edge.
+ *
+ * Written out per size rather than computed, because the offset is
+ * `BOX_SIZE_CLASS` plus the label row's `gap-2` and a class name is
+ * never interpolated — `` `ps-${…}` `` generates nothing and fails
+ * silently. sm is 0.875rem + 0.5rem, md is 1rem + 0.5rem, lg is
+ * 1.25rem + 0.5rem.
+ */
+const DESCRIPTION_INDENT_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "ps-5.5",
+  md: "ps-6",
+  lg: "ps-7",
+}
+
 /**
  * A single boolean, on or off, that owns nothing but itself.
  *
@@ -97,6 +131,30 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
  * also the one label association that needs no `for` at all, so there
  * is no minted-then-dropped id to get wrong.
  *
+ * ### A description is the one thing that cannot go in the `<label>`
+ *
+ * `Field` has had a `description` since it shipped and this component
+ * had none, so a hint could not follow its checkbox. Downstream that
+ * meant one hint out of three in a group stayed an app-styled
+ * paragraph and the box carried two hint typographies.
+ *
+ * The slot is here now, and it renders **outside** the `<label>`.
+ * A `<label>`'s text content is the control's accessible name, so a
+ * hint inside it is announced twice — once inside the name, once
+ * again as the description — and a pointer press on the hint toggles
+ * the box, which is not what a sentence of explanation should do. So
+ * the `<label>` is no longer the outermost element: a `<div>` holds
+ * the row and the hint, `className` moves out to it (`className` is
+ * the outermost box a component renders, and that rule does not bend
+ * for this one), and `aria-describedby` binds the two back together.
+ *
+ * There is no `error` here to go with it. `Field` derives
+ * `aria-invalid` from its error, and a lone boolean is almost never
+ * the invalid thing — a **group** of them is, and a group's error
+ * belongs on the `FieldGroup` around it, described rather than
+ * asserted. Adding one per box would put `aria-invalid` on a control
+ * that is not itself wrong.
+ *
  * ### The `<input>` is the store
  *
  * `defaultChecked`, not `checked`. The DOM owns a checkbox's state
@@ -108,6 +166,7 @@ const TEXT_SIZE_CLASS: Record<ControlSize, string> = {
  */
 export const Checkbox = ({
   className,
+  description,
   id,
   isChecked = false,
   isDisabled = false,
@@ -116,142 +175,192 @@ export const Checkbox = ({
   onChange,
   size = "md",
   value,
-}: CheckboxProps): ReactNode => (
-  <label
-    className={toClassName(
-      "inline-flex items-center gap-2 text-content-secondary select-none",
-      TEXT_SIZE_CLASS[size],
-      // One cursor, chosen by state — two cursor utilities of the same
-      // specificity do not resolve by class-list order.
-      isDisabled
-        ? "cursor-not-allowed"
-        : isReadOnly
-          ? "cursor-default"
-          : "cursor-pointer",
-      // Disabled dims the whole control with opacity rather than fading
-      // the box to a quieter token. The token scale has no step between
-      // `border-default` and `border-strong`, so a muted outline was
-      // either invisible or indistinguishable from enabled; `opacity-60`
-      // keeps the full shape and colour and just turns them down, which
-      // is the "present but inactive" the box actually is. Read-only is
-      // *not* dimmed — its whole point is that the value stays readable.
-      // The same treatment is on `Switch` and `RadioGroup`.
-      isDisabled && "opacity-60",
-      className,
-    )}
-  >
-    <span className="relative grid shrink-0 place-items-center">
-      <input
-        aria-readonly={isReadOnly || undefined}
+}: CheckboxProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const descriptionId = `${baseId}-description`
+
+  return (
+    <div
+      className={toClassName(
+        // The row and its hint stack, and the box stays inline-level so
+        // a `Checkbox` still sits in a sentence, a table cell or a flex
+        // row exactly where the bare `<label>` used to.
+        "inline-flex flex-col gap-1",
+        className,
+      )}
+    >
+      <label
         className={toClassName(
-          // `border-2` is the family's shared weight — the `Switch`
-          // track's `ring-2` and the `RadioGroup` ring match it, so the
-          // three read as one set — and a 2px edge is also what keeps a
-          // disabled box visible where a 1px one washed out.
-          "peer appearance-none rounded-sm border-2 bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard",
-          // Read-only wears the **neutral** intent, not the accent: full
-          // contrast (so the value reads) but plainly not an actionable
-          // accent control, with a softer `border-default` resting edge.
-          // Three distinct states result — enabled (accent, crisp),
-          // disabled (accent, dimmed by the wrapper), read-only (neutral).
-          // No `disabled:` colour override; the wrapper's `opacity-60`
-          // does the dimming, and doubling it on the box is what made a
-          // disabled checkbox vanish.
-          // `indeterminate:` wears the same fill as `checked:`. It is
-          // the state a *group* box is in when some of its members are
-          // ticked, and it cannot be written in markup at all —
-          // `indeterminate` is a DOM property with no HTML attribute —
-          // so the only way to reach it is a consumer writing to the
-          // input. `DataTable`'s select-all box does exactly that, and
-          // before this line it painted **nothing**: the property was
-          // set, screen readers announced "mixed", and the box on
-          // screen was indistinguishable from empty.
-          isReadOnly
-            ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid indeterminate:border-intent-neutral-solid indeterminate:bg-intent-neutral-solid"
-            : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid indeterminate:border-intent-accent-solid indeterminate:bg-intent-accent-solid",
+          "inline-flex items-center gap-2 text-content-secondary select-none",
+          TEXT_SIZE_CLASS[size],
+          // One cursor, chosen by state — two cursor utilities of the same
+          // specificity do not resolve by class-list order.
           isDisabled
             ? "cursor-not-allowed"
             : isReadOnly
               ? "cursor-default"
               : "cursor-pointer",
-          BOX_SIZE_CLASS[size],
-          FOCUS_RING_CLASS,
+          // Disabled dims the whole control with opacity rather than fading
+          // the box to a quieter token. The token scale has no step between
+          // `border-default` and `border-strong`, so a muted outline was
+          // either invisible or indistinguishable from enabled; `opacity-60`
+          // keeps the full shape and colour and just turns them down, which
+          // is the "present but inactive" the box actually is. Read-only is
+          // *not* dimmed — its whole point is that the value stays readable.
+          // The same treatment is on `Switch` and `RadioGroup`.
+          //
+          // It stays on the `<label>` and does NOT reach the description
+          // below, which is a contrast decision rather than an oversight.
+          // axe exempts a disabled control and its own label from the
+          // colour-contrast rule; a sibling paragraph gets no such
+          // exemption, and `content-secondary` at 60% measures **3.77:1**
+          // on `midnight` against a 4.5 threshold. A hint nobody can read
+          // is worse than a hint that does not dim with its control, and
+          // the hint is the part a user reads precisely when they are
+          // asking why the box is turned off.
+          isDisabled && "opacity-60",
         )}
-        defaultChecked={isChecked}
-        disabled={isDisabled}
-        id={id}
-        onChange={(
-          event: ChangeEvent<HTMLInputElement>,
-        ) => {
-          if (isReadOnly) {
-            return
-          }
+      >
+        <span className="relative grid shrink-0 place-items-center">
+          <input
+            aria-describedby={
+              description === undefined
+                ? undefined
+                : descriptionId
+            }
+            aria-readonly={isReadOnly || undefined}
+            className={toClassName(
+              // `border-2` is the family's shared weight — the `Switch`
+              // track's `ring-2` and the `RadioGroup` ring match it, so the
+              // three read as one set — and a 2px edge is also what keeps a
+              // disabled box visible where a 1px one washed out.
+              "peer appearance-none rounded-sm border-2 bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard",
+              // Read-only wears the **neutral** intent, not the accent: full
+              // contrast (so the value reads) but plainly not an actionable
+              // accent control, with a softer `border-default` resting edge.
+              // Three distinct states result — enabled (accent, crisp),
+              // disabled (accent, dimmed by the wrapper), read-only (neutral).
+              // No `disabled:` colour override; the wrapper's `opacity-60`
+              // does the dimming, and doubling it on the box is what made a
+              // disabled checkbox vanish.
+              // `indeterminate:` wears the same fill as `checked:`. It is
+              // the state a *group* box is in when some of its members are
+              // ticked, and it cannot be written in markup at all —
+              // `indeterminate` is a DOM property with no HTML attribute —
+              // so the only way to reach it is a consumer writing to the
+              // input. `DataTable`'s select-all box does exactly that, and
+              // before this line it painted **nothing**: the property was
+              // set, screen readers announced "mixed", and the box on
+              // screen was indistinguishable from empty.
+              isReadOnly
+                ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid indeterminate:border-intent-neutral-solid indeterminate:bg-intent-neutral-solid"
+                : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid indeterminate:border-intent-accent-solid indeterminate:bg-intent-accent-solid",
+              isDisabled
+                ? "cursor-not-allowed"
+                : isReadOnly
+                  ? "cursor-default"
+                  : "cursor-pointer",
+              BOX_SIZE_CLASS[size],
+              FOCUS_RING_CLASS,
+            )}
+            defaultChecked={isChecked}
+            disabled={isDisabled}
+            id={id}
+            onChange={(
+              event: ChangeEvent<HTMLInputElement>,
+            ) => {
+              if (isReadOnly) {
+                return
+              }
 
-          onChange?.(event.target.checked)
-        }}
-        onClick={(clickEvent) => {
-          // Native checkboxes have no `readonly`, so the toggle is
-          // blocked here — `preventDefault` on the click stops the
-          // checked flip a pointer would make.
-          if (isReadOnly) {
-            clickEvent.preventDefault()
-          }
-        }}
-        onKeyDown={(keyEvent) => {
-          // …and Space, the keyboard toggle a click block does not
-          // cover.
-          if (isReadOnly && keyEvent.key === " ") {
-            keyEvent.preventDefault()
-          }
-        }}
-        type="checkbox"
-        value={value}
-      />
+              onChange?.(event.target.checked)
+            }}
+            onClick={(clickEvent) => {
+              // Native checkboxes have no `readonly`, so the toggle is
+              // blocked here — `preventDefault` on the click stops the
+              // checked flip a pointer would make.
+              if (isReadOnly) {
+                clickEvent.preventDefault()
+              }
+            }}
+            onKeyDown={(keyEvent) => {
+              // …and Space, the keyboard toggle a click block does not
+              // cover.
+              if (isReadOnly && keyEvent.key === " ") {
+                keyEvent.preventDefault()
+              }
+            }}
+            type="checkbox"
+            value={value}
+          />
 
-      <svg
-        aria-hidden="true"
-        className={toClassName(
-          "pointer-events-none invisible absolute peer-checked:visible peer-indeterminate:invisible",
-          // Matches whichever fill the box wears, so the tick keeps its
-          // guaranteed on-solid contrast in either intent.
-          isReadOnly
-            ? "text-intent-neutral-on-solid"
-            : "text-intent-accent-on-solid",
-          CHECK_SIZE_CLASS[size],
-        )}
-        fill="none"
-        stroke="currentColor"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-        strokeWidth={3}
-        viewBox="0 0 24 24"
-      >
-        <path d="M20 6 9 17l-5-5" />
-      </svg>
+          <svg
+            aria-hidden="true"
+            className={toClassName(
+              "pointer-events-none invisible absolute peer-checked:visible peer-indeterminate:invisible",
+              // Matches whichever fill the box wears, so the tick keeps its
+              // guaranteed on-solid contrast in either intent.
+              isReadOnly
+                ? "text-intent-neutral-on-solid"
+                : "text-intent-accent-on-solid",
+              CHECK_SIZE_CLASS[size],
+            )}
+            fill="none"
+            stroke="currentColor"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={3}
+            viewBox="0 0 24 24"
+          >
+            <path d="M20 6 9 17l-5-5" />
+          </svg>
 
-      {/* The mixed mark — a dash, not a tick. Its own element rather
+          {/* The mixed mark — a dash, not a tick. Its own element rather
           than a second `<path>` in the tick's `<svg>`, because the
           two states have to be able to hide independently and a
           `<path>` cannot carry a `peer-*` variant of its own. */}
-      <svg
-        aria-hidden="true"
-        className={toClassName(
-          "pointer-events-none invisible absolute peer-indeterminate:visible",
-          isReadOnly
-            ? "text-intent-neutral-on-solid"
-            : "text-intent-accent-on-solid",
-          CHECK_SIZE_CLASS[size],
-        )}
-        fill="none"
-        stroke="currentColor"
-        strokeLinecap="round"
-        strokeWidth={3}
-        viewBox="0 0 24 24"
-      >
-        <path d="M6 12h12" />
-      </svg>
-    </span>
+          <svg
+            aria-hidden="true"
+            className={toClassName(
+              "pointer-events-none invisible absolute peer-indeterminate:visible",
+              isReadOnly
+                ? "text-intent-neutral-on-solid"
+                : "text-intent-accent-on-solid",
+              CHECK_SIZE_CLASS[size],
+            )}
+            fill="none"
+            stroke="currentColor"
+            strokeLinecap="round"
+            strokeWidth={3}
+            viewBox="0 0 24 24"
+          >
+            <path d="M6 12h12" />
+          </svg>
+        </span>
 
-    <span>{label}</span>
-  </label>
-)
+        <span>{label}</span>
+      </label>
+
+      {/*
+        `text-sm` and `content-secondary`, the same two the `Field`
+        description wears — one hint typography for the whole library,
+        so a `Checkbox` and a `Field` in the same box do not disagree
+        about how big a hint is. That disagreement is what kept
+        queuepilot's dyn editor on an app-styled `<p>` for one hint out
+        of three.
+      */}
+      {description === undefined ? null : (
+        <p
+          className={toClassName(
+            "text-content-secondary text-sm",
+            DESCRIPTION_INDENT_CLASS[size],
+          )}
+          id={descriptionId}
+        >
+          {description}
+        </p>
+      )}
+    </div>
+  )
+}