@create-ui/cli 0.5.7 → 0.5.9

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

@@ -0,0 +1,171 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-group.md -->
+
+# input-group
+
+Composable input shell with slots for icons, addons, selects, buttons, kbd hints and card badges around the control
+
+Install: `npx @create-ui/cli add input-group`
+
+## Import
+
+```tsx
+import { InputGroup, InputGroupProvider, InputGroupShell, InputGroupSlot, InputGroupControl, InputGroupTextarea, InputGroupToolbar, InputGroupLeadingIcon, InputGroupAddon, InputGroupSelect, InputGroupButton, InputGroupCard, InputGroupKbd, InputGroupHelperIcon, InputGroupField } from "@/components/ui/input-group"
+```
+
+Also exported: `useInputGroup`, `useOptionalInputGroup`
+
+## InputGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| loading | `boolean` | - |
+| multiline | `boolean` (switches the shell to flex-col; pair with InputGroupTextarea instead of InputGroupControl) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## InputGroupProvider props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | `sm` |
+| invalid | `boolean` | - |
+| disabled | `boolean` | `false` |
+| loading | `boolean` | `false` |
+| children | `ReactNode` | - |
+
+## InputGroupToolbar props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| position | `start \| end \| between` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## InputGroupSelect props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| className | `string` | - |
+| triggerClassName | `string` | - |
+| placeholder | `ReactNode` | - |
+| prefix | `ReactNode` | - |
+| valueChildren | `ReactNode` | - |
+| aria-label | `string` | - |
+| aria-labelledby | `string` | - |
+
+Extends `React.ComponentProps<typeof Select>`.
+
+## InputGroupHelperIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| invalidIcon | `ReactNode` | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## InputGroupField props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| label | `ReactNode` | - |
+| description | `ReactNode` | - |
+| error | `ReactNode` | - |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | `sm` |
+| disabled | `boolean` | - |
+| children | `ReactNode` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `input-group-demo`:
+
+```tsx
+import { RiSearch2Line } from "@create-ui/assets/icons"
+
+import {
+  InputGroup,
+  InputGroupButton,
+  InputGroupControl,
+  InputGroupKbd,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+
+export default function InputGroupDemo() {
+  return (
+    <InputGroup className="max-w-md">
+      <InputGroupSlot>
+        <RiSearch2Line />
+        <InputGroupControl placeholder="Search anything…" />
+        <InputGroupKbd>K</InputGroupKbd>
+      </InputGroupSlot>
+      <InputGroupButton>Search</InputGroupButton>
+    </InputGroup>
+  )
+}
+```
+
+From `input-group-with-select`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { Field, FieldLabel } from "@/components/ui/field"
+import {
+  InputGroup,
+  InputGroupControl,
+  InputGroupLeadingIcon,
+  InputGroupSelect,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+import { SelectItem } from "@/components/ui/select"
+
+const CURRENCY_SYMBOLS: Record<string, string> = {
+  usd: "$",
+  eur: "€",
+  gbp: "£",
+}
+
+export default function InputGroupWithSelect() {
+  const [currency, setCurrency] = React.useState("usd")
+
+  return (
+    <Field className="max-w-md">
+      <FieldLabel htmlFor="input-group-with-select-amount">Amount</FieldLabel>
+      <InputGroup>
+        <InputGroupLeadingIcon>
+          <span className="font-medium">{CURRENCY_SYMBOLS[currency]}</span>
+        </InputGroupLeadingIcon>
+        <InputGroupSlot>
+          <InputGroupControl
+            id="input-group-with-select-amount"
+            placeholder="0.00"
+          />
+        </InputGroupSlot>
+        <InputGroupSelect value={currency} onValueChange={setCurrency}>
+          <SelectItem value="usd">USD</SelectItem>
+          <SelectItem value="eur">EUR</SelectItem>
+          <SelectItem value="gbp">GBP</SelectItem>
+        </InputGroupSelect>
+      </InputGroup>
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-group` or MCP `get_item_examples_from_registries` with "input-group-demo" / "input-group-example".
+
+## When to use
+InputGroup is the shell for a single value that needs visible chrome: search bars with kbd hints and a submit button, URL fields with an https:// addon, amounts with a trailing currency select, passwords with a built-in show/hide toggle. For plain capture with no affordances use Input (or Textarea for multiline); for one-character-per-slot codes use InputOTP; for increment/decrement use InputStepper.
+## Gotchas
+- Never put a raw Input or Textarea inside the group; use InputGroupControl (single-line) or InputGroupTextarea (multiline). InputGroupControl strips its own height/padding (h-auto p-0) and relies on InputGroupSlot for size and state styling.
+- Two layers of placement: inline adornments (plain svg icons, InputGroupKbd, InputGroupHelperIcon) go INSIDE InputGroupSlot next to the control; bordered chrome (InputGroupLeadingIcon, InputGroupAddon, InputGroupSelect, InputGroupButton) goes as direct children of the group. The shell auto-draws 1px dividers between direct children.
+- size/invalid/disabled/loading cascade Field -> InputGroup -> every sub-part; set them once on Field. InputGroupSelect goes variant="compact" and InputGroupButton maps the group size to its own scale (xs->md, sm->lg, md->xl) automatically; do not re-set variant/size on them.
+- States do more than recolor: invalid auto-disables InputGroupButton; loading disables InputGroupButton and InputGroupSelect, appends a Spinner inside the slot, and makes InputGroupTextarea readOnly.
+- InputGroupControl type="password" auto-renders a show/hide eye toggle (with aria-pressed); it hides while loading and disables with the group. No extra wiring.
+- InputGroupKbd shows a command-key leading icon by default; pass leadingIcon={null} for plain single-key hints.

package/dist/skills/createui/reference/input-otp.md

@@ -0,0 +1,130 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-otp.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-otp.md -->
+
+# input-otp
+
+One-time passcode input with per-character slots; outline/filled variants and rounded/pill/square/underline shapes
+
+Install: `npx @create-ui/cli add input-otp`
+
+## Import
+
+```tsx
+import { InputOTP } from "@/components/ui/input-otp"
+```
+
+Also exported: `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`, `inputOTPSlotVariants`
+
+## InputOTP props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| shape | `rounded \| pill \| square \| underline` | `rounded` |
+| size | `lg \| md \| sm` (Resolution chain: explicit prop ?? wrapping Field's size ?? lg. Do not set it manually inside a Field.) | `lg` |
+| variant | `outline \| filled` | `outline` |
+| containerClassName | `string` (Merged onto the visible flex wrapper (default gap-component-lg). Disabled state auto-adds opacity-50 here.) | - |
+| invalid | `boolean` (Falls back to Field's invalid; flips every slot to data-state=error at once, overriding filled/typing/focused visuals (disabled still wins).) | `false` |
+| children | `ReactNode` | - |
+
+Extends `Omit< React.ComponentProps<typeof OTPInput>, "containerClassName" | "size" | "render" | "ref" >`.
+
+## Examples
+
+From `input-otp-demo`:
+
+```tsx
+"use client"
+
+import { REGEXP_ONLY_DIGITS } from "input-otp"
+
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from "@/components/ui/input-otp"
+
+export default function InputOTPDemo() {
+  return (
+    <InputOTP maxLength={6} pattern={REGEXP_ONLY_DIGITS}>
+      <InputOTPGroup>
+        <InputOTPSlot index={0} />
+        <InputOTPSlot index={1} />
+        <InputOTPSlot index={2} />
+        <InputOTPSeparator />
+        <InputOTPSlot index={3} />
+        <InputOTPSlot index={4} />
+        <InputOTPSlot index={5} />
+      </InputOTPGroup>
+    </InputOTP>
+  )
+}
+```
+
+From `input-otp-with-field`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { REGEXP_ONLY_DIGITS } from "input-otp"
+
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from "@/components/ui/field"
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from "@/components/ui/input-otp"
+
+export default function InputOTPWithField() {
+  const [value, setValue] = React.useState("")
+  const invalid = value.length > 0 && value.length < 6
+
+  return (
+    <Field size="md" invalid={invalid}>
+      <FieldLabel>Verification code</FieldLabel>
+      <FieldContent>
+        <InputOTP
+          maxLength={6}
+          value={value}
+          onChange={setValue}
+          pattern={REGEXP_ONLY_DIGITS}
+        >
+          <InputOTPGroup>
+            <InputOTPSlot index={0} />
+            <InputOTPSlot index={1} />
+            <InputOTPSlot index={2} />
+            <InputOTPSeparator />
+            <InputOTPSlot index={3} />
+            <InputOTPSlot index={4} />
+            <InputOTPSlot index={5} />
+          </InputOTPGroup>
+        </InputOTP>
+        <FieldDescription>
+          Enter the 6-digit code sent to your phone.
+        </FieldDescription>
+        <FieldError>Please enter all 6 digits.</FieldError>
+      </FieldContent>
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-otp` or MCP `get_item_examples_from_registries` with "input-otp-demo" / "input-otp-example".
+
+## When to use
+Fixed-length verification codes: 2FA, SMS/email confirmation, recovery codes. One hidden input drives per-character visual slots. Not for variable-length text (use Input), formatted values like card numbers, phone numbers, or dates (CreditCardInput, PhoneInput, DateInput), or bounded numeric values (InputStepper).
+
+## Gotchas
+- Children composition is mandatory; the upstream `render` prop is Omit-ted from the type. Render one `InputOTPSlot` per character with a zero-based `index` covering `maxLength`, wrapped in `InputOTPGroup` (a layout-only div; slots read state from the upstream OTPInputContext).
+- `shape`/`size`/`variant`/`disabled`/`invalid` are set only on the root `InputOTP` and reach slots via internal context. `InputOTPSlot` accepts only div props plus `index`; variant props on it do nothing.
+- Slots are NOT fused like shadcn's. Each slot is a standalone bordered box and `InputOTPGroup` just lays them out with `gap-component-lg`. Do not add shadcn-style `first:rounded-l` / shared-border / divide hacks.
+- Field cascade covers all three of `size`, `disabled`, `invalid` (prop ?? Field ctx ?? default). `<Field invalid>` alone puts the whole OTP in error state; pair it with `FieldError` for the message.
+- `InputOTPSeparator` defaults to the Remix `RiSubtractLine` minus icon and scales its text size from the root size context (default svg stays `size-6`). Pass children to replace it; never import a lucide icon for this.
+- The component sets no input `pattern` itself; examples always pass `pattern={REGEXP_ONLY_DIGITS}` imported from the `input-otp` package to restrict input to digits.

package/dist/skills/createui/reference/input-stepper.md

@@ -0,0 +1,120 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-stepper.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-stepper.md -->
+
+# input-stepper
+
+Numeric input with increment and decrement buttons; connected or separated variant, min/max/step clamping
+
+Install: `npx @create-ui/cli add input-stepper`
+
+## Import
+
+```tsx
+import { InputStepper } from "@/components/ui/input-stepper"
+```
+
+## InputStepper props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `connected \| separated` | - |
+| value | `number` (Clamped to [min, max] on every render in controlled mode; out-of-range state is never displayed) | - |
+| defaultValue | `number` | - |
+| onValueChange | `(value: number) => void` (Receives the clamped number, not an event; fires only when the clamped result differs from the current value) | - |
+| min | `number` | - |
+| max | `number` | - |
+| step | `number` (Drives +/- clicks AND native ArrowUp/ArrowDown stepping; both move by the same amount) | - |
+| size | `xs \| sm \| md` (Resolves explicit prop ?? parent Field size ?? md; the effective default is md, not sm) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| decrementLabel | `string` | - |
+| incrementLabel | `string` | - |
+
+Extends `React.ComponentProps<"input">`.
+
+## Examples
+
+From `input-stepper-demo`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { InputStepper } from "@/components/ui/input-stepper"
+
+export default function InputStepperDemo() {
+  const [value, setValue] = React.useState(1)
+
+  return (
+    <div className="w-[240px]">
+      <InputStepper
+        value={value}
+        onValueChange={setValue}
+        min={0}
+        max={10}
+        aria-label="Quantity"
+      />
+    </div>
+  )
+}
+```
+
+From `input-stepper-in-field`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
+import { InputStepper } from "@/components/ui/input-stepper"
+
+export default function InputStepperInField() {
+  const [quantity, setQuantity] = React.useState(1)
+
+  return (
+    <div className="flex w-[320px] flex-col gap-6">
+      <Field size="md">
+        <FieldLabel htmlFor="qty">Quantity</FieldLabel>
+        <InputStepper
+          id="qty"
+          value={quantity}
+          onValueChange={setQuantity}
+          min={1}
+          max={10}
+        />
+        <FieldDescription>
+          Inherits size from <code>{'<Field size="md" />'}</code>.
+        </FieldDescription>
+      </Field>
+
+      <Field size="sm" invalid>
+        <FieldLabel htmlFor="qty-invalid">Quantity (invalid)</FieldLabel>
+        <InputStepper id="qty-invalid" defaultValue={3} />
+        <FieldDescription>
+          Inherits <code>invalid</code> from Field.
+        </FieldDescription>
+      </Field>
+
+      <Field size="xs" disabled>
+        <FieldLabel htmlFor="qty-disabled">Quantity (disabled)</FieldLabel>
+        <InputStepper id="qty-disabled" defaultValue={3} variant="separated" />
+      </Field>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-stepper` or MCP `get_item_examples_from_registries` with "input-stepper-demo" / "input-stepper-example".
+
+## When to use
+A number-only input flanked by -/+ buttons for bounded counts: cart quantities, seats, tickets. Do NOT use it for free-form or unbounded numeric entry (use Input with type="number"), for picking from a fixed list (Select), or for boolean toggles (Switch/Checkbox).
+
+## Gotchas
+- Closed composite: only `InputStepper` is exported; the buttons, cell, and inner input are internal. Never rebuild it shadcn-style from `Input` + two `Button`s; restyle via `className` on the root or the `data-slot="input-stepper-*"` attributes.
+- The state API is `onValueChange(value: number)`; native `value`/`defaultValue`/`onChange` are Omit-ed from the prop type. `defaultValue` is clamped to `[min, max]` at mount and `value` on every render.
+- The -/+ buttons auto-disable at `min`/`max`, but only while a value is present; with an empty input both stay enabled.
+- `size`/`invalid`/`disabled` resolve as explicit prop ?? parent `Field` context ?? default, so inside a `Field` do not repeat them on the stepper (see input-stepper-in-field). The fallback `"sm"` visible in the source is unreachable; the real default size is `md`.
+- The -/+ buttons are `tabIndex={-1}` and call `preventDefault` on mousedown, so clicking them never moves focus and Tab reaches only the input. This is intentional; do not "fix" the tab order.
+- Clearing the input (uncontrolled) sets the value to `undefined` without firing `onValueChange`; in controlled mode the clear is ignored. From empty, the next +/- click seeds from `clamp(0, min, max)`, not from the last value.
+- Native browser spinners are hidden via CSS, but ArrowUp/ArrowDown still step the native `<input type="number">` by `step`.

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

@@ -0,0 +1,118 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input.md -->
+
+# input
+
+Single-line text input rendered in a focusable InputShell; size and invalid/disabled/loading state inherit from Field
+
+Install: `npx @create-ui/cli add input`
+
+## Import
+
+```tsx
+import { Input, InputProvider, InputShell } from "@/components/ui/input"
+```
+
+Also exported: `inputVariants`, `inputShellVariants`, `useInputContext`
+
+## Input props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution is prop ?? InputProvider context ?? Field context ?? sm; inside a Field omit it and let the Field's size cascade.) | `sm` |
+
+Extends `React.ComponentProps<"input">`.
+
+## InputProvider props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution is prop ?? InputProvider context ?? Field context ?? sm; inside a Field omit it and let the Field's size cascade.) | `md` |
+| invalid | `boolean` | `false` |
+| disabled | `boolean` | `false` |
+| loading | `boolean` | `false` |
+| children | `ReactNode` | - |
+
+## Examples
+
+From `input-demo`:
+
+```tsx
+import { Input } from "@/components/ui/input"
+
+export default function InputDemo() {
+  return (
+    <div className="w-100">
+      <Input type="email" placeholder="Email" />
+    </div>
+  )
+}
+```
+
+From `input-states`:
+
+```tsx
+import { Field, FieldLabel } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+
+export default function InputStates() {
+  return (
+    <div className="flex w-100 flex-col gap-10 py-4">
+      <Field>
+        <FieldLabel htmlFor="input-states-default">Default</FieldLabel>
+        <Input
+          id="input-states-default"
+          type="email"
+          placeholder="name@example.com"
+        />
+      </Field>
+      <Field invalid>
+        <FieldLabel htmlFor="input-states-invalid">Invalid</FieldLabel>
+        <Input
+          id="input-states-invalid"
+          type="email"
+          defaultValue="not-an-email"
+        />
+      </Field>
+      <Field disabled>
+        <FieldLabel htmlFor="input-states-disabled">Disabled</FieldLabel>
+        <Input
+          id="input-states-disabled"
+          type="email"
+          placeholder="name@example.com"
+        />
+      </Field>
+      <Field loading>
+        <FieldLabel htmlFor="input-states-loading">Loading</FieldLabel>
+        <Input
+          id="input-states-loading"
+          type="email"
+          placeholder="Checking availability…"
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input` or MCP `get_item_examples_from_registries` with "input-demo" / "input-example".
+
+## When to use
+Single-line text values: emails, names, search queries, URLs, file pickers. It is a one-element drop-in (`<Input />` wraps itself in a styled shell) that inherits size/invalid/disabled/loading from a surrounding `Field`. Do NOT use it for multi-line text (`Textarea`), option picking (`Select`), fields with icons/buttons/addons (`InputGroup` + `InputGroupControl`), OTP codes (`InputOTP`), step-controlled numbers (`InputStepper`), or dates/phones/cards (`DateInput` / `PhoneInput` / `CreditCardInput`).
+
+## Gotchas
+- Shell is auto-conditional: standalone `<Input />` wraps itself in `InputProvider` + `InputShell`; when any input context already exists it renders only the bare `<input>`. So in manual composition state props must go on `InputProvider`, not on `Input`, or the shell never sees them:
+
+```tsx
+<InputProvider size="md" invalid>
+  <InputShell>
+    <Input placeholder="Email" />
+  </InputShell>
+</InputProvider>
+```
+
+- Unlike shadcn, the border/focus/disabled visuals are on the shell `<div>`, not the input element. `className` on `Input` cannot change the border or radius; target `InputShell` (or `[data-slot="input-shell"]`) instead. Focus uses `outline-*`, never `ring-*`.
+- `loading` is not an `Input` prop; it arrives from `Field` (or `InputProvider`) context. It silently forces `readOnly` on the input and `pointer-events-none` + `aria-busy` on the shell.
+- For the error treatment prefer `<Field invalid>`. On a standalone `Input`, only a boolean `aria-invalid` is forwarded to the shell; the string form `aria-invalid="true"` sets the attribute on the inner input (red text via `aria-invalid:` CSS) but the shell keeps its normal border.
+- Clicking empty shell space focuses the input via mousedown delegation; clicks on nested interactive elements (input, button, a, [role='button'], etc.) are skipped. Mark custom interactive children with `data-input-control` so the shell does not steal their clicks.
+- Inside `InputGroup` use `InputGroupControl`, not raw `Input`: the control re-renders `Input` with `h-auto p-0` so the group shell owns spacing, and adds the password show/hide toggle for `type="password"`. A raw `Input` there renders bare but keeps its own size padding.
+- Hidden cleanups baked in: browser autofill background is suppressed and the native webkit clear (X) button for `type="search"` is hidden, so add your own clear affordance (e.g. an `InputGroup` button) if one is needed.

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

@@ -0,0 +1,121 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/label.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/label.md -->
+
+# label
+
+Form label with companion slots like LabelRequired, LabelOptional, LabelDescription and LabelCount; size follows Field
+
+Install: `npx @create-ui/cli add label`
+
+## Import
+
+```tsx
+import { Label, LabelBlock, LabelMain, LabelIcon, LabelRequired, LabelOptional, LabelDescription, LabelBadgeSlot, LabelInfoSlot, LabelCount } from "@/components/ui/label"
+```
+
+Also exported: `useLabelSize`
+
+## Label props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<typeof LabelPrimitive.Root>`.
+
+## LabelBlock props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+| asChild | `boolean` | `false` |
+
+Extends `React.ComponentProps<"div">`.
+
+## LabelIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelRequired props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelOptional props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelDescription props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"p">`.
+
+## LabelInfoSlot props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## LabelCount props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (Resolution: explicit prop ?? nearest LabelBlock/Label context ?? surrounding Field ?? sm. Set it once on Field or LabelBlock; never repeat on children) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## Examples
+
+From `label-demo`:
+
+```tsx
+import { Field } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import { Label } from "@/components/ui/label"
+
+export default function LabelDemo() {
+  return (
+    <Field className="w-full max-w-xs">
+      <Label htmlFor="label-demo">Full name</Label>
+      <Input id="label-demo" placeholder="Ada Lovelace" />
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view label` or MCP `get_item_examples_from_registries` with "label-demo" / "label-example".
+
+## When to use
+Caption for a form control (Input, Textarea, Select, Checkbox), with optional slots for an icon, required/optional marker, badge, info tooltip, description, and counter. For the full field stack with error wiring, compose `Field` with `FieldLabel` / `FieldDescription` / `FieldError` instead; for helper text rendered below the control use `FieldDescription`, not `LabelDescription` (which belongs in the label row).
+
+## Gotchas
+- Invalid/disabled looks are not props on Label. They are driven entirely by the wrapping `Field`'s `data-invalid` / `data-disabled` group attributes (`group-data-[...]/field`); a standalone Label cannot show those states.
+- `Label` and `LabelBlock` both re-provide the resolved size to nested slots via context, so `LabelIcon`, `LabelRequired`, `LabelCount`, etc. auto-match. Setting `size` on each slot is redundant and fights the cascade.
+- `LabelIcon` and `LabelRequired` are `aria-hidden` decoration: a `LabelRequired` asterisk does not make the field required, so still set `required` on the control. `LabelOptional` is NOT `aria-hidden`; its "(Optional)" text is announced.
+- Rich rows have a fixed composition: `LabelDescription` is a sibling of `Label` inside `LabelMain`, never a child of `Label`; `LabelCount` sits as `LabelBlock`'s trailing child, outside `LabelMain`.
+
+```tsx
+<LabelBlock>
+  <LabelMain>
+    <Label htmlFor="bio"><LabelIcon>...</LabelIcon>Bio<LabelRequired /></Label>
+    <LabelDescription>Shown on your profile.</LabelDescription>
+  </LabelMain>
+  <LabelCount>0/300</LabelCount>
+</LabelBlock>
+```
+- This is not shadcn's one-element Label: no `peer-disabled` styling, no CVA. State styling cascades from `Field`'s group attributes, and slots replace ad-hoc spans.