@smicolon/fasla-ui 0.5.1 → 0.7.0

package/registry/ui/checkbox/checkbox.test.tsx

@@ -1,7 +1,323 @@
-import { describe, it, expect } from "vitest"
-import { render, screen } from "@testing-library/react"
+import * as React from "react"
+import { describe, it, expect, vi } from "vitest"
+import { render, screen, fireEvent } from "@testing-library/react"
+import { renderToString } from "react-dom/server"
 import { Checkbox } from "./checkbox"
 
+/**
+ * What these tests can and cannot prove.
+ *
+ * jsdom has no layout engine and no style resolution: it does not match
+ * `:hover`, `:focus-visible` or `:has()` selectors and does not apply a
+ * stylesheet. So the styling tests below assert **class presence only** — that
+ * the component emits the right utility on the right element. They do NOT
+ * prove the rule was generated by Tailwind or that anything is painted.
+ *
+ * Rendered proof — box and glyph geometry, fills per state, focus rings, the
+ * box aligned to the first label line in both scripts — was checked in a real
+ * browser against Storybook. Treat a green run here as "the contract is
+ * wired", not "it looks right".
+ */
+
+/** label ▸ input ▸ focusRing ▸ band ▸ [halo, control ▸ [check, minus]] */
+const parts = (input: HTMLElement) => {
+  const root = input.closest("label") as HTMLElement
+  const control = root.querySelector("[data-slot=control]") as HTMLElement
+  const siblings = [...(input.parentElement?.children ?? [])] as HTMLElement[]
+  return {
+    root,
+    control,
+    band: control.parentElement as HTMLElement,
+    halo: root.querySelector("[data-slot=halo]") as HTMLElement | null,
+    focusRing:
+      siblings.find((el) => el.className.includes("peer-focus-visible:opacity-100")) ?? null,
+    check: control.querySelector("[data-slot=check]") as SVGElement,
+    minus: control.querySelector("[data-slot=minus]") as SVGElement,
+  }
+}
+
+const checkbox = () => screen.getByRole("checkbox") as HTMLInputElement
+
+describe("Checkbox", () => {
+  it("renders a checkbox input", () => {
+    render(<Checkbox aria-label="Accept" />)
+    expect(checkbox()).toBeInTheDocument()
+  })
+
+  it("is unchecked by default and reflects defaultChecked", () => {
+    const { unmount } = render(<Checkbox aria-label="Accept" />)
+    expect(checkbox()).not.toBeChecked()
+    unmount()
+
+    render(<Checkbox aria-label="Accept" defaultChecked />)
+    expect(checkbox()).toBeChecked()
+  })
+
+  it("sizes the box, glyph and halo per Figma: 16/20/24, glyph 4px smaller, halo 8px larger", () => {
+    const cases = [
+      ["sm", "size-4", "size-3", "size-6"],
+      ["md", "size-5", "size-4", "size-7"],
+      ["lg", "size-6", "size-5", "size-8"],
+    ] as const
+    for (const [size, box, glyph, halo] of cases) {
+      const { unmount } = render(<Checkbox size={size} label="Option" />)
+      const p = parts(checkbox())
+      expect(p.control).toHaveClass(box)
+      expect(p.check).toHaveClass(glyph)
+      expect(p.minus).toHaveClass(glyph)
+      expect(p.halo).toHaveClass(halo)
+      unmount()
+    }
+  })
+
+  it("grows the row to the box at lg and drops the text to stay centred", () => {
+    // A 24px box overhangs a 20px English line. Figma's lg row is 24px, with
+    // 8px from box to border in the Layout card.
+    render(<Checkbox size="lg" label="Option" />)
+    const { band, root } = parts(checkbox())
+    expect(band).toHaveClass("min-h-6")
+    const text = screen.getByText("Option").parentElement as HTMLElement
+    expect(text.className).toMatch(/\bpt-\[max\(0px,/)
+    expect(root.querySelector(".min-h-6")).not.toBeNull()
+  })
+
+  it("leaves the row one label line tall at sm and md", () => {
+    for (const size of ["sm", "md"] as const) {
+      const { unmount } = render(<Checkbox size={size} label="Option" />)
+      const { band } = parts(checkbox())
+      expect(band).not.toHaveClass("min-h-6")
+      expect((screen.getByText("Option").parentElement as HTMLElement).className).not.toMatch(/\bpt-/)
+      unmount()
+    }
+  })
+
+  it("defaults to md", () => {
+    render(<Checkbox label="Option" />)
+    expect(parts(checkbox()).control).toHaveClass("size-5")
+  })
+
+  it("falls back to md for an unknown size", () => {
+    // @ts-expect-error an untyped caller passing a typo
+    render(<Checkbox label="Option" size="xl" />)
+    expect(parts(checkbox()).control).toHaveClass("size-5")
+  })
+
+  it("fills the box with primary when checked or indeterminate", () => {
+    render(<Checkbox label="Option" />)
+    const { control } = parts(checkbox())
+    // `rounded` is a fixed 4px, as Figma binds it; `rounded-sm` would follow --radius.
+    expect(control).toHaveClass("rounded", "border-input", "text-primary-foreground")
+    expect(control).not.toHaveClass("rounded-sm")
+    expect(control).toHaveClass(
+      "group-has-[:checked]/checkbox:bg-primary",
+      "group-has-[:indeterminate]/checkbox:bg-primary"
+    )
+  })
+
+  it("shows the tick only when checked and not indeterminate", () => {
+    // Without the `:not(:indeterminate)` a checked *and* indeterminate input
+    // would paint both glyphs on top of each other.
+    render(<Checkbox label="Option" />)
+    const { check, minus } = parts(checkbox())
+    expect(check).toHaveClass(
+      "group-has-[:checked:not(:indeterminate):not([data-indeterminate])]/checkbox:opacity-100"
+    )
+    expect(minus).toHaveClass("group-has-[:indeterminate]/checkbox:opacity-100")
+  })
+
+  it("sets the indeterminate DOM property and keeps it in step with the prop", () => {
+    const { rerender } = render(<Checkbox label="Select all" indeterminate />)
+    expect(checkbox().indeterminate).toBe(true)
+
+    rerender(<Checkbox label="Select all" indeterminate={false} />)
+    expect(checkbox().indeterminate).toBe(false)
+  })
+
+  it("restores indeterminate when a click clears it but the prop stays true", () => {
+    // A parent that ignores the click re-renders with the same prop value.
+    const Parent = () => {
+      const [, force] = React.useState(0)
+      return <Checkbox label="Select all" indeterminate onChange={() => force((n) => n + 1)} />
+    }
+    render(<Parent />)
+    fireEvent.click(checkbox())
+    expect(checkbox().indeterminate).toBe(true)
+  })
+
+  it("shows the dash in server-rendered HTML, before the DOM property exists", () => {
+    // `indeterminate` has no attribute, so the first HTML of a static page
+    // would otherwise show an unchecked-looking box until hydration.
+    const html = renderToString(<Checkbox label="Select all" indeterminate />)
+    expect(html).toContain("data-indeterminate")
+    const { check, minus, control } = parts(
+      (() => {
+        render(<Checkbox label="Select all" indeterminate />)
+        return checkbox()
+      })()
+    )
+    expect(minus).toHaveClass("group-has-[[data-indeterminate]]/checkbox:opacity-100")
+    expect(control).toHaveClass("group-has-[[data-indeterminate]]/checkbox:bg-primary")
+    expect(check).toHaveClass(
+      "group-has-[:checked:not(:indeterminate):not([data-indeterminate])]/checkbox:opacity-100"
+    )
+  })
+
+  it("swaps the attribute for the DOM property once mounted", () => {
+    // Left in place, the attribute would keep the dash after a click clears
+    // the property, and the box would disagree with assistive technology.
+    render(<Checkbox label="Select all" indeterminate />)
+    expect(checkbox().indeterminate).toBe(true)
+    expect(checkbox()).not.toHaveAttribute("data-indeterminate")
+  })
+
+  it("is not indeterminate by default", () => {
+    render(<Checkbox label="Option" />)
+    expect(checkbox().indeterminate).toBe(false)
+  })
+
+  it("does not mirror the glyphs in RTL", () => {
+    render(<Checkbox label="Option" />)
+    const { check, minus } = parts(checkbox())
+    for (const glyph of [check, minus]) {
+      expect(glyph.getAttribute("class")).not.toMatch(/rtl:|scale-x|rotate/)
+    }
+  })
+
+  it("uses logical properties only — no rtl: overrides", () => {
+    for (const variant of ["default", "layout"] as const) {
+      const { unmount } = render(<Checkbox variant={variant} label="Option" description="Detail" />)
+      expect(parts(checkbox()).root.outerHTML).not.toMatch(/\brtl:|\bltr:|\bleft-|\bright-/)
+      unmount()
+    }
+  })
+
+  it("lets the type ramp own the label leading", () => {
+    // The ramp makes `text-sm` direction-aware (20px English, 24px Arabic). A
+    // hardcoded leading would override it and clip Arabic.
+    render(<Checkbox label="Option" description="Detail" size="sm" />)
+    for (const el of [screen.getByText("Option"), screen.getByText("Detail")]) {
+      expect(el).toHaveClass("text-sm")
+      expect(el.className).not.toMatch(/\bleading-/)
+    }
+    expect(screen.getByText("Option")).toHaveClass("font-medium", "text-foreground")
+    expect(screen.getByText("Detail")).toHaveClass("text-muted-foreground")
+  })
+
+  it("rings the box for the default variant, and haloes it on hover", () => {
+    render(<Checkbox label="Option" />)
+    const { root, focusRing, halo, control } = parts(checkbox())
+    expect(focusRing).not.toBeNull()
+    const ring = focusRing!.firstElementChild as HTMLElement
+    expect(ring).toHaveClass("rounded", "ring-2", "ring-ring", "ring-offset-2", "size-5")
+    // Tailwind's default offset colour is white, which shows as a halo in Dark.
+    expect(ring).toHaveClass("ring-offset-background")
+    // Figma: a rounded square, box + 8px, radius 8, accent, behind the box.
+    expect(halo).toHaveClass(
+      "absolute",
+      "pointer-events-none",
+      "rounded-[0.5rem]",
+      "bg-accent",
+      "opacity-0",
+      "group-hover/checkbox:opacity-100",
+      "-start-1"
+    )
+    expect(halo!.nextElementSibling).toBe(control)
+    expect(root).not.toHaveClass("hover:bg-accent")
+  })
+
+  it("rings and fills the card for the layout variant, with no halo", () => {
+    render(<Checkbox variant="layout" label="Option" />)
+    const { root, focusRing, halo } = parts(checkbox())
+    expect(root).toHaveClass("rounded-md", "border", "p-2", "hover:bg-accent")
+    expect(focusRing).toHaveClass("-inset-[2px]", "ring-2", "ring-ring")
+    expect(halo).toBeNull()
+  })
+
+  it("drives focus without a has-[] utility", () => {
+    // `:has()` is invisible to the pseudo-state renderer behind the Storybook
+    // states grid, so focus must be `peer`-driven.
+    for (const variant of ["default", "layout"] as const) {
+      const { unmount } = render(<Checkbox variant={variant} label="Option" />)
+      const html = parts(checkbox()).root.outerHTML
+      expect(html).not.toMatch(/has-\[:hover\]|has-\[:focus-visible\]/)
+      unmount()
+    }
+  })
+
+  it("falls back to the default variant for null", () => {
+    // @ts-expect-error `variant` is declared on CheckboxProps, not widened with `| null`
+    render(<Checkbox label="Option" variant={null} />)
+    expect(parts(checkbox()).root).not.toHaveClass("border")
+  })
+
+  it("toggles when its label is clicked", () => {
+    render(<Checkbox label="Accept terms" />)
+    fireEvent.click(screen.getByText("Accept terms"))
+    expect(checkbox()).toBeChecked()
+  })
+
+  it("is named by the label alone and described by the description", () => {
+    render(<Checkbox label="Marketing emails" description="About new features" />)
+    expect(checkbox()).toHaveAccessibleName("Marketing emails")
+    expect(checkbox()).toHaveAccessibleDescription("About new features")
+  })
+
+  it("keeps a caller's aria-label and aria-describedby", () => {
+    render(
+      <>
+        <p id="extra">Extra</p>
+        <Checkbox aria-label="Custom" description="Detail" aria-describedby="extra" />
+      </>
+    )
+    expect(checkbox()).toHaveAccessibleName("Custom")
+    expect(checkbox()).toHaveAccessibleDescription("Detail Extra")
+  })
+
+  it("keeps the box and glyphs out of the accessibility tree", () => {
+    render(<Checkbox label="Option" />)
+    expect(parts(checkbox()).band).toHaveAttribute("aria-hidden", "true")
+  })
+
+  it("renders no text column without a label or description", () => {
+    render(<Checkbox aria-label="Bare" />)
+    // input, focus ring, box band — and no text column.
+    expect(checkbox().parentElement?.childElementCount).toBe(3)
+  })
+
+  it("handles onChange", () => {
+    const handleChange = vi.fn()
+    render(<Checkbox label="Option" onChange={handleChange} />)
+    fireEvent.click(checkbox())
+    expect(handleChange).toHaveBeenCalled()
+  })
+
+  it("dims and blocks the whole component when disabled", () => {
+    render(<Checkbox label="Option" disabled />)
+    expect(checkbox()).toBeDisabled()
+    expect(parts(checkbox()).root).toHaveClass(
+      "has-[:disabled]:opacity-50",
+      "has-[:disabled]:pointer-events-none"
+    )
+  })
+
+  it("applies className to the root", () => {
+    render(<Checkbox label="Option" className="custom-class" />)
+    expect(parts(checkbox()).root).toHaveClass("custom-class")
+  })
+
+  it("forwards its ref to the input", () => {
+    const ref = React.createRef<HTMLInputElement>()
+    render(<Checkbox aria-label="Option" ref={ref} />)
+    expect(ref.current).toBe(checkbox())
+  })
+
+  it("uses the given id and links the label to it", () => {
+    render(<Checkbox id="terms" label="Terms" />)
+    expect(checkbox()).toHaveAttribute("id", "terms")
+    expect(parts(checkbox()).root).toHaveAttribute("for", "terms")
+  })
+})
+
 describe("Checkbox id", () => {
   it("uses the id it is given", () => {
     render(<Checkbox id="terms" label="Accept the terms" />)

package/registry/ui/checkbox/checkbox.tsx

@@ -1,102 +1,288 @@
 import * as React from "react"
+import { cva } from "class-variance-authority"
 import { CheckIcon, MinusIcon } from "lucide-react"
 import { cn } from "../../../src/lib/utils"
 
+/**
+ * The height of one line of label text, in whichever script is rendering —
+ * 20px for Geist, 24px for Cairo. The ramp publishes `--leading-sm` as a
+ * unitless ratio and re-points it under `[dir="rtl"]`, so nothing here is
+ * direction-specific. The fallback, English's 20 / 14, is for a project that
+ * does not load the Fasla preset. Same derivation as Radio's LINE_BOX.
+ */
+const LINE_BOX = "h-[calc(var(--leading-sm,calc(20/14))*0.875rem)]"
+
+/**
+ * Half of what a 24px box overhangs one label line: 2px in English, 0 in
+ * Arabic, whose line is already 24px. At `lg` it drops the text column by that
+ * much, so the first line stays centred on the box once the row grows to the
+ * box's height.
+ */
+const LG_TEXT_OFFSET =
+  "pt-[max(0px,calc((1.5rem_-_var(--leading-sm,calc(20/14))*0.875rem)/2))]"
+
+/*
+ * `indeterminate` has no HTML attribute, so server-rendered HTML cannot carry
+ * it. The component renders `data-indeterminate` instead and removes it once
+ * the DOM property is set. A layout effect, so the swap lands before paint.
+ */
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect
+
+/**
+ * Root layout. Figma's two Types:
+ *  - `default`: box, then label, no frame.
+ *  - `layout`: the same row inside a bordered card — 1px `border`, 8px
+ *    padding, 6px radius (`rounded-md`). The whole card is the target, so
+ *    hover fills it, as Radio's Layout card does.
+ *
+ * `group/checkbox` is a *named* group so the `:has()` lookups below can never
+ * be answered by an unrelated input in some outer `.group`.
+ *
+ * Disabled dims the whole component, like Radio and Switch. Figma dims the box
+ * and label but not the description or the card border; with the description
+ * already muted the difference is slight, and one disabled treatment across
+ * the selection controls is worth more.
+ */
+const checkboxVariants = cva(
+  "group/checkbox relative inline-flex cursor-pointer items-start gap-3 has-[:disabled]:pointer-events-none has-[:disabled]:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "",
+        layout:
+          "rounded-md border p-2 transition-colors motion-reduce:transition-none hover:bg-accent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+/**
+ * Box, glyph and hover halo per size, straight from the Figma set. The glyph is
+ * always the box less 4px; the halo is always the box plus 8px. Figma draws
+ * lucide's `check` and `minus` with a 1px stroke at 16px — 1.5 on lucide's
+ * 24-unit grid — and scales it, so the stroke is the same 1.5 at every size.
+ *
+ * `row` and `text` matter at `lg` only: the 24px box is taller than a 20px
+ * English line, so the row grows to the box (Figma's 24px row, and 8px from
+ * box to border in the Layout card) and the text drops to stay centred.
+ */
+const sizeClasses = {
+  sm: { box: "size-4", glyph: "size-3", halo: "size-6", row: "", text: "" },
+  md: { box: "size-5", glyph: "size-4", halo: "size-7", row: "", text: "" },
+  lg: { box: "size-6", glyph: "size-5", halo: "size-8", row: "min-h-6", text: LG_TEXT_OFFSET },
+}
+
 export interface CheckboxProps
-  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> {
-  /** Label text */
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+  /**
+   * Visual treatment. `layout` wraps the box and text in a bordered card.
+   * Declared here rather than inherited from `VariantProps`, which widens every
+   * variant with `| null` and shows a meaningless third option in Storybook.
+   */
+  variant?: "default" | "layout"
+  /** Size variant */
+  size?: "sm" | "md" | "lg"
+  /** Label text. Without it (or `description`) pass `aria-label` for an accessible name. */
   label?: string
-  /** Description text */
+  /** Secondary line below the label */
   description?: string
-  /** Error state */
-  error?: boolean
-  /** Indeterminate state */
+  /**
+   * Shows the "some, not all" dash — for a parent of a partly selected list.
+   * Sets the input's `indeterminate` property, so assistive technology hears
+   * "mixed". A click clears it, as the browser does natively; keep the prop in
+   * step from your own state.
+   */
   indeterminate?: boolean
 }
 
+/**
+ * A native checkbox with an optional label and description, in Figma's two
+ * types (`default`, `layout`) and three sizes. Checked, indeterminate, hover,
+ * focus and disabled are CSS states of the real `<input>`, so the box always
+ * shows what the browser and assistive technology see.
+ */
 const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
-  ({ className, label, description, error, indeterminate, id, ...props }, ref) => {
+  (
+    {
+      className,
+      variant = "default",
+      size = "md",
+      label,
+      description,
+      indeterminate = false,
+      id,
+      "aria-label": ariaLabel,
+      "aria-labelledby": ariaLabelledBy,
+      "aria-describedby": ariaDescribedBy,
+      ...props
+    },
+    ref
+  ) => {
     const inputRef = React.useRef<HTMLInputElement>(null)
+    React.useImperativeHandle(ref, () => inputRef.current as HTMLInputElement)
 
-    React.useImperativeHandle(ref, () => inputRef.current!)
-
-    React.useEffect(() => {
-      if (inputRef.current) {
-        inputRef.current.indeterminate = indeterminate ?? false
-      }
-    }, [indeterminate])
+    /*
+     * `indeterminate` is a DOM property with no attribute, so it is set here —
+     * on every render, not only when the prop changes. A click clears it in the
+     * DOM; if the parent re-renders with the prop still true, a deps-guarded
+     * effect would never run again and the box would stay ticked.
+     */
+    useIsomorphicLayoutEffect(() => {
+      const input = inputRef.current
+      if (!input) return
+      input.indeterminate = indeterminate
+      input.removeAttribute("data-indeterminate")
+    })
 
     // Called on every render, so the hook order holds when id comes and goes
     const generatedId = React.useId()
     const inputId = id || generatedId
+    const labelId = `${inputId}-label`
+    const descriptionId = `${inputId}-description`
 
-    const checkbox = (
-      <div className="relative flex items-center">
+    /*
+     * The wrapping <label> would name the checkbox with *all* its text, label
+     * and description together, while `aria-describedby` reads the description
+     * again. So the name points at the label alone, unless the caller named
+     * the checkbox themselves; and the description is linked only when the
+     * name comes from somewhere else. Same rule as Switch.
+     */
+    const labelledBy = ariaLabelledBy ?? (label && !ariaLabel ? labelId : undefined)
+    const isNamedElsewhere = Boolean(label || ariaLabel || ariaLabelledBy)
+    // Plain join: these are ids, and `cn` would merge them as classes.
+    const describedBy =
+      [description && isNamedElsewhere ? descriptionId : undefined, ariaDescribedBy]
+        .filter(Boolean)
+        .join(" ") || undefined
+
+    // Fall back to the defaults for an untyped caller passing null or a typo.
+    const sizes = sizeClasses[size] ?? sizeClasses.md
+    const isLayout = variant === "layout"
+
+    return (
+      <label
+        htmlFor={inputId}
+        className={cn(checkboxVariants({ variant: isLayout ? "layout" : "default" }), className)}
+      >
         <input
           type="checkbox"
           ref={inputRef}
           id={inputId}
           className="peer sr-only"
+          aria-label={ariaLabel}
+          aria-labelledby={labelledBy}
+          aria-describedby={describedBy}
+          data-indeterminate={indeterminate ? "" : undefined}
           {...props}
         />
-        <div
-          className={cn(
-            "flex h-4 w-4 shrink-0 items-center justify-center rounded-sm border transition-colors",
-            "peer-focus-visible:outline-none peer-focus-visible:ring-2 peer-focus-visible:ring-ring peer-focus-visible:ring-offset-2",
-            "peer-checked:border-primary peer-checked:bg-primary peer-checked:text-primary-foreground",
-            "peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
-            error
-              ? "border-destructive peer-checked:border-destructive peer-checked:bg-destructive"
-              : "border-input",
-            className
-          )}
-        >
-          <CheckIcon
-            size={12}
-            strokeWidth={1.5}
+        {/*
+         * Focus rings are real elements and *direct siblings of the input*, so
+         * a plain `peer-focus-visible:opacity-100` drives them — the one form
+         * the pseudo-states addon behind the Storybook states grid can force.
+         * Layout rings the card; Default rings the box with a 2px gap. Figma
+         * has no focus variant; this matches Radio's.
+         */}
+        {isLayout ? (
+          <span
+            aria-hidden="true"
+            // −2px, not −1px: an absolute child is offset from the padding
+            // box, which sits 1px inside the border.
+            className="pointer-events-none absolute -inset-[2px] rounded-[calc(var(--radius)-1px)] opacity-0 ring-2 ring-ring peer-focus-visible:opacity-100"
+          />
+        ) : (
+          <span
+            aria-hidden="true"
             className={cn(
-              "opacity-0 peer-checked:opacity-100",
-              indeterminate ? "hidden" : "block"
+              "pointer-events-none absolute start-0 top-0 flex items-center opacity-0 peer-focus-visible:opacity-100",
+              LINE_BOX,
+              sizes.row
             )}
-          />
-          {indeterminate && (
-            <MinusIcon size={12} strokeWidth={1.5} />
-          )}
-        </div>
-      </div>
-    )
-
-    if (!label && !description) {
-      return checkbox
-    }
-
-    // The label takes the type ramp's leading (24px Arabic, 20px English), so a
-    // wrapped label never overlaps. The box sits in a box one line tall, as
-    // Radio's control does, so it stays centred on the first line.
-    return (
-      <div className="flex items-start gap-3">
-        {/* One label line tall, as Radio's control; falls back to English's 20 / 14 without the Fasla preset */}
-        <div className="flex h-[calc(var(--leading-sm,calc(20/14))*0.875rem)] shrink-0 items-center">{checkbox}</div>
-        <div className="grid gap-1">
-          {label && (
-            <label
-              htmlFor={inputId}
+          >
+            {/* The 2px gap takes the page colour; Tailwind's default offset is white, which shows in Dark. */}
+            <span
               className={cn(
-                "text-sm font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
-                error && "text-destructive"
+                "rounded ring-2 ring-ring ring-offset-2 ring-offset-background",
+                sizes.box
               )}
-            >
-              {label}
-            </label>
-          )}
-          {description && (
-            <p className="text-xs text-muted-foreground">{description}</p>
+            />
+          </span>
+        )}
+        {/*
+         * The box sits in a band one label line tall and centres itself in it,
+         * so it lines up with the *first* line of a wrapped label. At `lg` the
+         * band grows to the 24px box instead of letting it overhang a 20px
+         * English line, and the text column drops to match.
+         */}
+        <span
+          aria-hidden="true"
+          className={cn("relative flex shrink-0 items-center", LINE_BOX, sizes.row)}
+        >
+          {/*
+           * Hover halo — Default only; in Layout the card fills instead. The
+           * band is exactly as wide as the box, so `-start-1` centres the halo
+           * in both directions. Absolute, so it never moves anything: every
+           * Figma Interaction variant has the same frame size.
+           */}
+          {!isLayout && (
+            <span
+              data-slot="halo"
+              className={cn(
+                "pointer-events-none absolute -start-1 top-1/2 -translate-y-1/2 rounded-[0.5rem] bg-accent opacity-0 transition-opacity motion-reduce:transition-none group-hover/checkbox:opacity-100",
+                sizes.halo
+              )}
+            />
           )}
-        </div>
-      </div>
+          <span
+            data-slot="control"
+            className={cn(
+              "relative flex shrink-0 items-center justify-center rounded border border-input text-primary-foreground transition-colors motion-reduce:transition-none",
+              "group-has-[:checked]/checkbox:border-primary group-has-[:checked]/checkbox:bg-primary",
+              "group-has-[:indeterminate]/checkbox:border-primary group-has-[:indeterminate]/checkbox:bg-primary",
+              "group-has-[[data-indeterminate]]/checkbox:border-primary group-has-[[data-indeterminate]]/checkbox:bg-primary",
+              sizes.box
+            )}
+          >
+            {/* Neither glyph mirrors in RTL: a tick and a dash have no direction. */}
+            <CheckIcon
+              data-slot="check"
+              strokeWidth={1.5}
+              className={cn(
+                "absolute opacity-0 group-has-[:checked:not(:indeterminate):not([data-indeterminate])]/checkbox:opacity-100",
+                sizes.glyph
+              )}
+            />
+            <MinusIcon
+              data-slot="minus"
+              strokeWidth={1.5}
+              className={cn(
+                "absolute opacity-0 group-has-[:indeterminate]/checkbox:opacity-100 group-has-[[data-indeterminate]]/checkbox:opacity-100",
+                sizes.glyph
+              )}
+            />
+          </span>
+        </span>
+        {(label || description) && (
+          <span className={cn("flex min-w-0 flex-col gap-2", sizes.text)}>
+            {label && (
+              <span id={labelId} className="text-sm font-medium text-foreground">
+                {label}
+              </span>
+            )}
+            {description && (
+              <span id={descriptionId} className="text-sm text-muted-foreground">
+                {description}
+              </span>
+            )}
+          </span>
+        )}
+      </label>
     )
   }
 )
 Checkbox.displayName = "Checkbox"
 
-export { Checkbox }
+export { Checkbox, checkboxVariants }