@create-ui/cli 0.5.7 → 0.5.9

package/dist/skills/createui/reference/breadcrumb.md

@@ -0,0 +1,153 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/breadcrumb.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/breadcrumb.md -->
+
+# breadcrumb
+
+Path navigation with BreadcrumbItem, BreadcrumbSeparator (chevron, slash or dot) and BreadcrumbEllipsis for collapsing
+
+Install: `npx @create-ui/cli add breadcrumb`
+
+## Import
+
+```tsx
+import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbSeparator } from "@/components/ui/breadcrumb"
+```
+
+Also exported: `breadcrumbEllipsisVariants`, `breadcrumbItemVariants`, `breadcrumbSeparatorVariants`, `useBreadcrumbContext`
+
+## Breadcrumb props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral` | - |
+| appearance | `solid \| outline \| ghost` | - |
+| size | `xs \| sm \| md` | - |
+| shape | `rounded \| pill` | - |
+| separator | `chevron \| slash \| dot` (Root-level prop; sets the glyph for every child BreadcrumbSeparator via context. On BreadcrumbSeparator itself the same axis is named variant.) | - |
+
+Extends `React.ComponentProps<"nav">`.
+
+## BreadcrumbEllipsis props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral` | `primary` |
+| appearance | `solid \| outline \| ghost` | `ghost` |
+| size | `xs \| sm \| md` | `md` |
+| shape | `rounded \| pill` | `rounded` |
+| disabled | `boolean` | - |
+| current | `boolean` (Sets aria-current to page, strongest text color, and pointer-events-none; the item stops behaving like a link. Replaces shadcn's BreadcrumbPage.) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## BreadcrumbItem props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral` | `primary` |
+| appearance | `solid \| outline \| ghost` | `ghost` |
+| size | `xs \| sm \| md` | `md` |
+| shape | `rounded \| pill` | `rounded` |
+| asChild | `boolean` (Renders children raw through Slot: leadingIcon/trailingIcon and the icon/content/caret slot wrappers are skipped, so icons inside the child lose the automatic per-size svg sizing.) | `false` |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+| disabled | `boolean` | - |
+| current | `boolean` (Sets aria-current to page, strongest text color, and pointer-events-none; the item stops behaving like a link. Replaces shadcn's BreadcrumbPage.) | - |
+
+Extends `React.ComponentProps<"a">`.
+
+## BreadcrumbSeparator props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `chevron \| slash \| dot` | `chevron` |
+| size | `xs \| sm \| md` | `md` |
+
+Extends `React.ComponentProps<"span">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `BreadcrumbItem` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `breadcrumb-demo`:
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb"
+
+export default function BreadcrumbDemo() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbItem variant="neutral" href="#">
+        Workspace
+      </BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem variant="neutral" href="#">
+        Settings
+      </BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem variant="neutral" href="#">
+        Team
+      </BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem variant="neutral" href="#" current>
+        Members
+      </BreadcrumbItem>
+    </Breadcrumb>
+  )
+}
+```
+
+From `breadcrumb-overflow`:
+
+```tsx
+import {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbSeparator,
+} from "@/components/ui/breadcrumb"
+
+export default function BreadcrumbOverflow() {
+  return (
+    <Breadcrumb>
+      <BreadcrumbItem href="#">Workspace</BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbEllipsis />
+      <BreadcrumbSeparator />
+      <BreadcrumbItem href="#">Team</BreadcrumbItem>
+      <BreadcrumbSeparator />
+      <BreadcrumbItem href="#" current>
+        Members
+      </BreadcrumbItem>
+    </Breadcrumb>
+  )
+}
+```
+
+More: `npx @create-ui/cli view breadcrumb` or MCP `get_item_examples_from_registries` with "breadcrumb-demo" / "breadcrumb-example".
+
+## When to use
+Hierarchical "where am I" trail for screens several levels deep (workspace > project > page), with one-click navigation back up the tree. Do NOT use it for paging through a list (use Pagination) or for switching between sibling views (use TabMenu). For a single back-to-parent affordance, a Button with a leading chevron is lighter.
+
+## Gotchas
+- No BreadcrumbList / BreadcrumbLink / BreadcrumbPage (shadcn parts do not exist). Items and separators are direct children of Breadcrumb (a flat nav, no ol/li). The link IS BreadcrumbItem (renders an anchor by default), and the current page is BreadcrumbItem current, not a separate component.
+- Separators are never auto-injected; interleave BreadcrumbSeparator between items yourself. Set the glyph once via separator on the root; BreadcrumbSeparator reads glyph and size from context.
+- Root Breadcrumb props cascade via context: items and ellipsis inherit variant/appearance/size/shape, separators inherit only size and the separator glyph. Per-child props override (explicit ?? ctx ?? default), so set axes once on the root.
+- BreadcrumbEllipsis is a static span containing "...": no asChild, not a button or link. It carries item hover/cursor styling so it looks clickable, but opening a menu of collapsed items requires your own interactive wrapper.
+- The root nav is flex-nowrap with overflow-x-auto and a hidden scrollbar: long trails scroll horizontally instead of wrapping.
+- Items accept arbitrary children (Avatar, Badge) next to the label, but you must size-pair them manually (e.g. Avatar size="xs" inside an md item); nothing cascades into non-breadcrumb children.
+
+```tsx
+<Breadcrumb variant="neutral" size="sm" separator="slash">
+  <BreadcrumbItem asChild>
+    <Link href="/">Home</Link>
+  </BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem href="/settings" current>Settings</BreadcrumbItem>
+</Breadcrumb>
+```

package/dist/skills/createui/reference/button-group.md

@@ -0,0 +1,116 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/button-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/button-group.md -->
+
+# button-group
+
+Row of attached ButtonGroupItem buttons sharing borders; per-item active, loading and iconOnly, ideal for toolbars
+
+Install: `npx @create-ui/cli add button-group`
+
+## Import
+
+```tsx
+import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"
+```
+
+Also exported: `buttonGroupVariants`, `buttonGroupItemVariants`
+
+## ButtonGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| soft` | `primary` |
+| shape | `rounded \| pill \| square` | `rounded` |
+| size | `xs \| sm \| md \| lg \| xl` | `md` |
+
+Extends `React.ComponentProps<"div">`.
+
+## ButtonGroupItem props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| soft` | `primary` |
+| size | `xs \| sm \| md \| lg \| xl` | `md` |
+| iconOnly | `boolean` (renders children as a single centered icon (like Button); leadingIcon/trailingIcon are ignored; add aria-label) | `false` |
+| asChild | `boolean` | `false` |
+| loading | `boolean` (Also blocks interaction (native disabled, or aria-disabled + tabIndex -1 under asChild); the spinner replaces trailingIcon, or the icon child when iconOnly) | `false` |
+| active | `boolean` (Styling via data-active plus aria-pressed (aria-pressed is skipped under asChild); the group has no value/onValueChange - selection state is the caller's job) | `false` |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `ButtonGroupItem` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `button-group-demo`:
+
+```tsx
+import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"
+
+export default function ButtonGroupDemo() {
+  return (
+    <ButtonGroup>
+      <ButtonGroupItem>List</ButtonGroupItem>
+      <ButtonGroupItem active>Grid</ButtonGroupItem>
+      <ButtonGroupItem>Gallery</ButtonGroupItem>
+    </ButtonGroup>
+  )
+}
+```
+
+From `button-group-composition`:
+
+```tsx
+"use client"
+
+import { RiExternalLinkLine } from "@create-ui/assets/icons"
+
+import { Badge } from "@/components/ui/badge"
+import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"
+
+export default function ButtonGroupComposition() {
+  return (
+    <ButtonGroup>
+      <ButtonGroupItem>
+        Inbox
+        <Badge variant="neutral" appearance="soft" size="xs" numberOnly>
+          7
+        </Badge>
+      </ButtonGroupItem>
+      <ButtonGroupItem active>
+        Drafts
+        <Badge variant="primary" appearance="soft" size="xs" numberOnly>
+          2
+        </Badge>
+      </ButtonGroupItem>
+      <ButtonGroupItem asChild trailingIcon={<RiExternalLinkLine />}>
+        <a href="#archive">Archive</a>
+      </ButtonGroupItem>
+    </ButtonGroup>
+  )
+}
+```
+
+More: `npx @create-ui/cli view button-group` or MCP `get_item_examples_from_registries` with "button-group-demo" / "button-group-example".
+
+## When to use
+A joined row of sibling actions on one bordered surface: view switchers (list/grid), inline action clusters, formatting toolbars. The root broadcasts `variant` and `size` to every item via context, so set them once on `ButtonGroup`. Not for a single standalone action (use `Button`), not for exclusive selection with managed state (use `SegmentedControl`, which has `value`/`onValueChange`), not for page navigation (use `Pagination`), not for overflow actions (use `DropdownMenu`).
+
+## Gotchas
+- Items must be DIRECT children of `ButtonGroup`: the joined border, outer radius, and dividers come from `[&>*:first-child]` / `[&>*:last-child]` selectors on the root, so any wrapper element between group and item breaks the surface.
+- Never place `<Button>` inside `ButtonGroup` (shadcn habit); `ButtonGroupItem` is the only component that reads the group context. There is also no `orientation` prop, no `ButtonGroupSeparator`, no `ButtonGroupText`.
+- Item `variant`/`size` resolve as explicit prop ?? group context ?? default, so per-item overrides are possible but rarely wanted.
+- With `asChild`, the child element's own children become the label and the component clones the child to re-render icons + label inside it. Icons go on `ButtonGroupItem` props, never inside the anchor:
+
+```tsx
+<ButtonGroupItem asChild leadingIcon={<RiSettings6Fill />}>
+  <a href="#settings">Settings</a>
+</ButtonGroupItem>
+```
+
+- `asChild` with bare-text children (no element) silently falls back to rendering a plain `<button>`.
+- `iconOnly` renders `children` as a single centered icon, exactly like `Button` - put the icon in `children`, not `leadingIcon` (which is ignored in this mode); the text label is gone, so add `aria-label`. With `loading`, the spinner replaces the icon child. For `asChild` + `iconOnly`, the icon goes inside the wrapped element.
+- `iconOnly` items are a FIXED square (`size-N`). A full-width action bar (`ButtonGroup className="w-full"` with `flex-1` items, dropping to `xl:flex-none` for square on desktop) is the deliberate, correct use of `flex-1` here. But adding `flex-1` / `w-full` to an iconOnly item in a COMPACT group stretches the square into a wide rectangle - leave the width class off unless you actually want full-width equal segments.

package/dist/skills/createui/reference/button.md

@@ -0,0 +1,104 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/button.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/button.md -->
+
+# button
+
+Action button with variant, appearance, size and shape axes; leadingIcon, trailingIcon and loading props
+
+Install: `npx @create-ui/cli add button`
+
+## Import
+
+```tsx
+import { Button } from "@/components/ui/button"
+```
+
+Also exported: `buttonVariants`
+
+## Button props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral-solid \| neutral-light \| danger \| success \| inverse-solid \| inverse-light` (color intent; combine with appearance for the visual weight) | `primary` |
+| appearance | `solid \| outline \| ghost \| soft` | `solid` |
+| size | `xs \| sm \| md \| lg \| xl` | `lg` |
+| shape | `rounded \| pill \| square` | `rounded` |
+| iconOnly | `boolean` (icon goes as children; leadingIcon/trailingIcon are silently ignored in this mode) | `false` |
+| asChild | `boolean` | `false` |
+| loading | `boolean` (built-in spinner + disabled state; never compose your own) | `false` |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+
+Extends `React.ComponentProps<"button">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `Button` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `button-demo`:
+
+```tsx
+import { RiArrowRightLine, RiSparklingFill } from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+
+export default function ButtonDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button>Save changes</Button>
+      <Button variant="neutral-light" appearance="soft">
+        Cancel
+      </Button>
+      <Button
+        variant="primary"
+        appearance="outline"
+        trailingIcon={<RiArrowRightLine />}
+      >
+        Continue
+      </Button>
+      <Button variant="primary" iconOnly aria-label="Sparkle">
+        <RiSparklingFill />
+      </Button>
+    </div>
+  )
+}
+```
+
+From `button-with-icon`:
+
+```tsx
+import { RiAddCircleFill, RiArrowRightLine } from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+
+export default function ButtonWithIcon() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button leadingIcon={<RiAddCircleFill />}>Leading</Button>
+      <Button trailingIcon={<RiArrowRightLine />}>Trailing</Button>
+      <Button
+        leadingIcon={<RiAddCircleFill />}
+        trailingIcon={<RiArrowRightLine />}
+      >
+        Both
+      </Button>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view button` or MCP `get_item_examples_from_registries` with "button-demo" / "button-example".
+
+## When to use
+
+Any action: form submits, dialog triggers, async operations. Button-styled links use `asChild` with your router's Link. NOT for links inside prose (use `TextLink`), clustered action rows (use `ButtonGroup`), a dedicated dismiss control (use `CloseButton`), or non-interactive status labels (use `Badge`).
+
+## Gotchas
+
+- There is NO `variant="outline"` / `"secondary"` / `"destructive"`: outline is `appearance="outline"`, destructive is `variant="danger"`, secondary is usually `variant="neutral-light"` or `appearance="soft"` / `"ghost"`.
+- Icons go through `leadingIcon` / `trailingIcon`, never as children next to text, and never with sizing classes; the component sizes them per `size` via `[&_svg]:size-*`.
+- `iconOnly` renders `children` as the icon and silently ignores `leadingIcon` / `trailingIcon`; the component adds no accessible text itself, so pass `aria-label`. With `loading` it swaps the icon for the spinner plus an sr-only "Loading".
+- `loading` blocks interaction: native `disabled` (or `aria-disabled` + `tabIndex={-1}` under `asChild`) plus `aria-busy`. In text buttons the spinner replaces the leadingIcon slot while the label stays visible; spinner variant and size are auto-matched to the active variant/appearance/size.
+- `asChild` clones the child and re-injects Button's own label/icon spans, so `leadingIcon` / `trailingIcon` / `loading` all still work on an `<a>`; the child's children become the label.
+- The root is `inline-flex`: intrinsic-width in normal flow, but as a flex/grid child under the default `align-items: stretch` (e.g. inside a `flex flex-col` card) it fills the container and looks full-width. Add `w-fit` or `self-start` to keep it intrinsic - this is required on `DropdownMenu`/`Popover` triggers placed in a stacked layout - or `w-full` for an intentionally full-width button.

package/dist/skills/createui/reference/checkbox-group.md

@@ -0,0 +1,118 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/checkbox-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/checkbox-group.md -->
+
+# checkbox-group
+
+Field wrapper that labels a Checkbox and cascades variant, size and shape via context; placement left or right
+
+Install: `npx @create-ui/cli add checkbox-group`
+
+## Import
+
+```tsx
+import { CheckboxGroup } from "@/components/ui/checkbox-group"
+```
+
+Also exported: `checkboxGroupVariants`
+
+## CheckboxGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| danger` (danger only recolors FieldFooter text and cascades a danger checkbox; it does not set invalid) | `primary` |
+| size | `xs \| sm \| md` (cascades to the child Checkbox via context (a bare Checkbox defaults to sm) and is forwarded to Field, so label and description scale with it) | `md` |
+| shape | `CheckboxShape` | `rounded` |
+| placement | `left \| right` (right is flex-row-reverse: visual flip only; keep the Checkbox first in the DOM) | `left` |
+
+Extends `React.ComponentProps<typeof Field>`.
+
+## Examples
+
+From `checkbox-group-demo`:
+
+```tsx
+import { Checkbox } from "@/components/ui/checkbox"
+import { CheckboxGroup } from "@/components/ui/checkbox-group"
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+
+export default function CheckboxGroupDemo() {
+  return (
+    <CheckboxGroup className="w-[340px]">
+      <Checkbox id="cb-demo" defaultChecked />
+      <FieldContent>
+        <LabelMain>
+          <Label htmlFor="cb-demo">Email notifications</Label>
+          <LabelDescription>
+            Get a digest of product updates once a week.
+          </LabelDescription>
+        </LabelMain>
+      </FieldContent>
+    </CheckboxGroup>
+  )
+}
+```
+
+From `checkbox-group-variants`:
+
+```tsx
+import { Checkbox } from "@/components/ui/checkbox"
+import { CheckboxGroup } from "@/components/ui/checkbox-group"
+import { FieldContent, FieldFooter } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+
+export default function CheckboxGroupVariants() {
+  return (
+    <div className="flex flex-col gap-6">
+      <CheckboxGroup variant="primary" className="w-[340px]">
+        <Checkbox id="cb-variant-primary" defaultChecked />
+        <FieldContent>
+          <LabelMain>
+            <Label htmlFor="cb-variant-primary">Marketing emails</Label>
+            <LabelDescription>
+              We&apos;ll only send the things you ask for.
+            </LabelDescription>
+          </LabelMain>
+        </FieldContent>
+      </CheckboxGroup>
+
+      <CheckboxGroup variant="danger" invalid className="w-[340px]">
+        <Checkbox id="cb-variant-error" />
+        <FieldContent>
+          <LabelMain>
+            <Label htmlFor="cb-variant-error">Accept the terms</Label>
+            <LabelDescription>
+              You must agree to the terms before continuing.
+            </LabelDescription>
+          </LabelMain>
+          <FieldFooter>Required field.</FieldFooter>
+        </FieldContent>
+      </CheckboxGroup>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view checkbox-group` or MCP `get_item_examples_from_registries` with "checkbox-group-demo" / "checkbox-group-example".
+
+## When to use
+A single labelled boolean row: one Checkbox plus label, description, and optional footer, composed as a Field locked to horizontal orientation. Use it for settings rows, consent lines, and opt-ins; for a multi-select list, stack several CheckboxGroup rows inside a FieldSet. It is NOT a one-of-many control (use RadioGroup) and not for bare unlabelled checks in dense table rows or toolbars (use Checkbox directly).
+## Gotchas
+- Despite the name, it manages ONE checkbox, not a set. The group has no value/onValueChange; checked state lives entirely on the child Checkbox you render. A shadcn-style "stateful group container" assumption is wrong here.
+- It renders no Checkbox itself; you compose the anatomy and wire id/htmlFor manually (the group does not auto-link them):
+
+```tsx
+<CheckboxGroup>
+  <Checkbox id="x" />
+  <FieldContent>
+    <LabelMain>
+      <Label htmlFor="x">Title</Label>
+      <LabelDescription>Help text</LabelDescription>
+    </LabelMain>
+  </FieldContent>
+</CheckboxGroup>
+```
+
+- variant, size, and shape reach the child Checkbox through CheckboxContext (resolution: explicit prop ?? context ?? default). Never repeat them on the Checkbox; an explicit child prop wins and breaks the single point of configuration.
+- variant="danger" is visual only: it paints [data-slot=field-footer] text error-base and cascades a danger checkbox. It does not flip the Field invalid flag; pass invalid (inherited Field prop) yourself when you need the data-invalid cascade on label and description.
+- disabled on the group only fades label/description through Field's data-disabled; CheckboxContext carries no disabled, so the input stays focusable and toggleable. Set disabled on the child Checkbox too (the shipped disabled examples set both).
+- Field's orientation and size props are stripped from the type: orientation is hardcoded to horizontal, and the group's own size is forwarded to Field, so text spacing scales without extra wiring.

package/dist/skills/createui/reference/checkbox.md

@@ -0,0 +1,79 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/checkbox.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/checkbox.md -->
+
+# checkbox
+
+Binary check control with indeterminate state; six variants, xs/sm/md sizes and rounded/pill/square shapes
+
+Install: `npx @create-ui/cli add checkbox`
+
+## Import
+
+```tsx
+import { Checkbox } from "@/components/ui/checkbox"
+```
+
+Also exported: `CheckboxContext`, `checkboxVariants`
+
+## Checkbox props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| inverse \| danger \| success \| info` (inverse is built for dark surfaces: its focus and disabled backgrounds are static black. It is not a generic outlined style.) | `primary` |
+| size | `xs \| sm \| md` | `sm` |
+| shape | `rounded \| pill \| square` | `rounded` |
+
+Extends `React.ComponentProps<typeof CheckboxPrimitive.Root>`.
+
+## Examples
+
+From `checkbox-demo`:
+
+```tsx
+import { Checkbox } from "@/components/ui/checkbox"
+
+export default function CheckboxDemo() {
+  return <Checkbox defaultChecked aria-label="Accept terms" />
+}
+```
+
+From `checkbox-controlled`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { Checkbox } from "@/components/ui/checkbox"
+
+type CheckedState = boolean | "indeterminate"
+
+export default function CheckboxControlled() {
+  const [checked, setChecked] = React.useState<CheckedState>("indeterminate")
+
+  return (
+    <div className="flex w-40 items-center gap-3">
+      <Checkbox
+        checked={checked}
+        onCheckedChange={setChecked}
+        aria-label="Controlled checkbox"
+      />
+      <p className="text-placeholder text-ui-control-sm">
+        State: <span className="text-body font-medium">{String(checked)}</span>
+      </p>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view checkbox` or MCP `get_item_examples_from_registries` with "checkbox-demo" / "checkbox-example".
+
+## When to use
+Checkbox is one independent boolean (accept terms, include a row in a bulk action); `checked="indeterminate"` is for a parent summarizing partially selected children. For a labelled row with label, description, or footer, compose it inside CheckboxGroup (with FieldContent + Label) instead. Do not use it for settings that apply immediately (Switch) or single-select choices (RadioGroup).
+
+## Gotchas
+- The check and indeterminate icons are built in (RiCheckLine / RiSubtractFill, swapped via `data-state`). Do not port shadcn's pattern of passing an icon child or a `CheckboxIndicator`; there is no indicator export, and any children you pass are overridden by the internal indicator.
+- variant/size/shape resolve as explicit prop ?? CheckboxContext ?? default. CheckboxGroup provides that context (and defaults to size md, unlike a bare Checkbox), so set size/shape once on the group and leave the inner Checkbox bare. The group's own variant only covers primary/danger; other variants go on the Checkbox itself. Field does not cascade into Checkbox.
+- It renders only the box, no label slot. Pair it with `<label htmlFor>` or `aria-label`. Field's invalid/disabled state does not restyle the box; mirror `aria-invalid` / `disabled` on the Checkbox itself.
+- `aria-invalid` adds the red error outline on any variant. `variant="danger"` only recolors the checked fill and focus outline; the unchecked resting border stays neutral, so it is not the validation state.
+- Focus styling is outline-based (`outline-2` on the root). className overrides must use `outline-*` utilities, never `ring-*`.
+- The root carries the `peer` class, so a sibling label can style against state (e.g. `peer-data-[state=checked]:line-through`) with no extra wiring.