@cloudflare/kumo 1.19.0 → 2.0.1

package/ai/component-registry.md

@@ -2,6 +2,266 @@
 
 > Auto-generated component metadata for AI/agent consumption.
 
+---
+
+### Autocomplete
+
+Autocomplete — free-form text input with an optional filtered suggestion list.  Unlike Combobox, the input value is not restricted to items in the list. Use Combobox when the selected value must come from the list.  Compound component: `Autocomplete` (Root), `.InputGroup`, `.Content`, `.Item`, `.GroupLabel`, `.Group`, `.Separator`, `.List`, `.Collection`.  `InputGroup` renders the text input with Input component styling. Pass a `size` prop to `InputGroup` to match the Input component sizes.
+
+**Type:** component
+
+**Import:** `import { Autocomplete } from "@cloudflare/kumo";`
+
+**Category:** Other
+
+**Props:**
+
+- `items`: unknown[] (required)
+  Array of items to display in the dropdown
+- `value`: string | number | string[]
+  The controlled input value
+- `open`: boolean
+  Whether the popup is open (controlled)
+- `children`: ReactNode
+  Autocomplete content (input group, popup content)
+- `className`: string
+  Additional CSS classes
+- `label`: ReactNode
+  Label content (enables Field wrapper)
+- `required`: boolean
+  Whether the field is required
+- `labelTooltip`: ReactNode
+  Tooltip content to display next to the label
+- `description`: ReactNode
+  Helper text displayed below the field
+- `error`: string | object
+  Error message or validation error object
+
+**Colors (kumo tokens used):**
+
+`bg-kumo-control`, `bg-kumo-line`, `bg-kumo-overlay`, `border-kumo-line`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-strong`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Autocomplete.InputGroup
+
+InputGroup sub-component
+
+Props:
+- `className`: string
+- `size`: KumoAutocompleteSize
+- `placeholder`: string
+
+#### Autocomplete.Content
+
+Content sub-component
+
+Props:
+- `children`: ReactNode
+- `className`: string
+- `align`: AutocompleteBase.Positioner.Props["align"]
+- `alignOffset`: AutocompleteBase.Positioner.Props["alignOffset"]
+- `side`: AutocompleteBase.Positioner.Props["side"]
+- `sideOffset`: AutocompleteBase.Positioner.Props["sideOffset"]
+
+#### Autocomplete.Item
+
+Item sub-component
+
+#### Autocomplete.GroupLabel
+
+GroupLabel sub-component
+
+#### Autocomplete.Group
+
+Group sub-component
+
+#### Autocomplete.Separator
+
+Separator sub-component
+
+#### Autocomplete.List
+
+List sub-component
+
+#### Autocomplete.Empty
+
+Empty sub-component (wraps AutocompleteBase)
+
+#### Autocomplete.Collection
+
+Collection sub-component (wraps AutocompleteBase)
+
+
+**Examples:**
+
+```tsx
+<Autocomplete items={fruits}>
+      <Autocomplete.InputGroup placeholder="Search fruits…" />
+      <Autocomplete.Content>
+        <Autocomplete.List>
+          {(item: string) => (
+            <Autocomplete.Item key={item} value={item}>
+              {item}
+            </Autocomplete.Item>
+          )}
+        </Autocomplete.List>
+      </Autocomplete.Content>
+    </Autocomplete>
+```
+
+```tsx
+<div className="w-80">
+      <Autocomplete
+        items={countries}
+        label="Country"
+        description="Start typing to filter countries"
+        filter={(item: Country, query: string) =>
+          item.label.toLowerCase().includes(query.toLowerCase())
+        }
+      >
+        <Autocomplete.InputGroup placeholder="Search countries…" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: Country) => (
+              <Autocomplete.Item key={item.code} value={item}>
+                {item.label}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+    </div>
+```
+
+```tsx
+<div className="w-80">
+      <Autocomplete
+        items={countries}
+        label="Country"
+        error={{ message: "Please enter a valid country", match: true }}
+        filter={(item: Country, query: string) =>
+          item.label.toLowerCase().includes(query.toLowerCase())
+        }
+      >
+        <Autocomplete.InputGroup placeholder="Search countries…" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: Country) => (
+              <Autocomplete.Item key={item.code} value={item}>
+                {item.label}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+    </div>
+```
+
+```tsx
+<Autocomplete items={servers}>
+      <Autocomplete.InputGroup placeholder="Select region…" />
+      <Autocomplete.Content>
+        <Autocomplete.List>
+          {(group: ServerGroup) => (
+            <Autocomplete.Group key={group.value} items={group.items}>
+              <Autocomplete.GroupLabel>{group.value}</Autocomplete.GroupLabel>
+              <Autocomplete.Collection>
+                {(item: ServerLocation) => (
+                  <Autocomplete.Item key={item.value} value={item}>
+                    {item.label}
+                  </Autocomplete.Item>
+                )}
+              </Autocomplete.Collection>
+            </Autocomplete.Group>
+          )}
+        </Autocomplete.List>
+      </Autocomplete.Content>
+    </Autocomplete>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-4">
+      <Autocomplete items={fruits.slice(0, 10)}>
+        <Autocomplete.InputGroup size="xs" placeholder="xs" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: string) => (
+              <Autocomplete.Item key={item} value={item}>
+                {item}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+      <Autocomplete items={fruits.slice(0, 10)}>
+        <Autocomplete.InputGroup size="sm" placeholder="sm" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: string) => (
+              <Autocomplete.Item key={item} value={item}>
+                {item}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+      <Autocomplete items={fruits.slice(0, 10)}>
+        <Autocomplete.InputGroup size="base" placeholder="base (default)" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: string) => (
+              <Autocomplete.Item key={item} value={item}>
+                {item}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+      <Autocomplete items={fruits.slice(0, 10)}>
+        <Autocomplete.InputGroup size="lg" placeholder="lg" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: string) => (
+              <Autocomplete.Item key={item} value={item}>
+                {item}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+    </div>
+```
+
+```tsx
+<div className="flex flex-col gap-3 w-80">
+      <Autocomplete
+        items={fruits}
+        value={value}
+        onValueChange={(v) => setValue(v)}
+      >
+        <Autocomplete.InputGroup placeholder="Type a fruit…" />
+        <Autocomplete.Content>
+          <Autocomplete.List>
+            {(item: string) => (
+              <Autocomplete.Item key={item} value={item}>
+                {item}
+              </Autocomplete.Item>
+            )}
+          </Autocomplete.List>
+        </Autocomplete.Content>
+      </Autocomplete>
+      {value && (
+        <p className="text-sm text-kumo-subtle">
+          Value: <span className="text-kumo-default font-medium">{value}</span>
+        </p>
+      )}
+    </div>
+```
+
+
 ---
 
 ### Badge
@@ -353,10 +613,9 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
   **State Classes:**
   - `"primary"`:
     - `hover`: `hover:bg-kumo-brand-hover`
-    - `focus`: `focus:bg-kumo-brand-hover`
     - `disabled`: `disabled:bg-kumo-brand/50`
   - `"secondary"`:
-    - `not-disabled`: `not-disabled:hover:border-secondary! not-disabled:hover:bg-kumo-tint`
+    - `not-disabled`: `not-disabled:hover:bg-kumo-tint`
     - `disabled`: `disabled:bg-kumo-base/50 disabled:!text-kumo-default/70`
     - `data-state`: `data-[state=open]:bg-kumo-base`
   - `"ghost"`:
@@ -364,7 +623,7 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
   - `"destructive"`:
     - `hover`: `hover:bg-kumo-danger/70`
   - `"secondary-destructive"`:
-    - `not-disabled`: `not-disabled:hover:border-secondary! not-disabled:hover:bg-kumo-base`
+    - `not-disabled`: `not-disabled:hover:bg-kumo-base`
     - `disabled`: `disabled:bg-kumo-base/50 disabled:!text-kumo-danger/70`
     - `data-state`: `data-[state=open]:bg-kumo-base`
 - `children`: ReactNode
@@ -383,7 +642,7 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-brand-hover`, `bg-kumo-danger`, `bg-kumo-tint`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-brand-hover`, `bg-kumo-danger`, `bg-kumo-tint`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -479,7 +738,7 @@ Checkbox component
 
   **State Classes:**
   - `"default"`:
-    - `focus`: `[&:focus-within>span]:ring-kumo-hairline`
+    - `focus`: `[&:focus-within>span]:ring-kumo-focus`
     - `hover`: `[&:hover>span]:ring-kumo-hairline`
 - `label`: ReactNode
   Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
@@ -499,12 +758,10 @@ Checkbox component
   Whether the field is required
 - `className`: string
   Additional class name
-- `onValueChange`: (checked: boolean) => void
-  Callback when checkbox value changes
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-contrast`, `ring-kumo-contrast`, `ring-kumo-danger`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-contrast`, `ring-kumo-brand`, `ring-kumo-contrast`, `ring-kumo-danger`, `ring-kumo-focus`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -535,7 +792,7 @@ Item sub-component
 Group sub-component
 
 Props:
-- `legend`: string (required)
+- `legend`: string
 - `children`: ReactNode (required)
 - `error`: string
 - `description`: ReactNode
@@ -545,6 +802,14 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+#### Checkbox.Legend
+
+Legend sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
 
 **Examples:**
 
@@ -594,6 +859,17 @@ Props:
     </Checkbox.Group>
 ```
 
+```tsx
+<Checkbox.Group value={preferences} onValueChange={setPreferences}>
+      <Checkbox.Legend className="sr-only">
+        Notification preferences
+      </Checkbox.Legend>
+      <Checkbox.Item value="email" label="Email notifications" />
+      <Checkbox.Item value="sms" label="SMS notifications" />
+      <Checkbox.Item value="push" label="Push notifications" />
+    </Checkbox.Group>
+```
+
 ```tsx
 <Checkbox.Group
       legend="Required preferences"
@@ -638,7 +914,7 @@ Read-only text field with a one-click copy-to-clipboard button.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `border-kumo-hairline`, `outline-kumo-fill`, `text-kumo-default`
+`bg-kumo-base`, `border-kumo-line`, `outline-kumo-fill`, `ring-kumo-brand`, `ring-kumo-focus`, `text-kumo-default`
 
 **Styling:**
 
@@ -1146,12 +1422,12 @@ Code component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `border-kumo-fill`, `text-kumo-strong`
+`bg-kumo-base`, `border-kumo-fill`, `text-kumo-subtle`
 
 **Styling:**
 
 - **Dimensions:** `[object Object]`
-- **Base Tokens:** `text-kumo-strong`
+- **Base Tokens:** `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -1170,7 +1446,7 @@ Props:
 
 ### Collapsible
 
-Collapsible component for showing/hiding content.  Features: - Animated chevron indicator (rotates 180° when open) - Accessible with aria-expanded and aria-controls - Content panel with left border accent
+Collapsible — a composable disclosure component for showing/hiding content.  Built on Base UI's Collapsible with full composition support.  ## Basic Usage  ```tsx const [open, setOpen] = useState(false);  <Collapsible.Root open={open} onOpenChange={setOpen}> <Collapsible.Trigger render={<Button variant="ghost" />}> Show details </Collapsible.Trigger> <Collapsible.Panel className="mt-2"> <Text>Hidden content revealed when expanded.</Text> </Collapsible.Panel> </Collapsible.Root> ```  ## With Default Styling  Use `DefaultTrigger` and `DefaultPanel` for the classic Kumo style:  ```tsx <Collapsible.Root> <Collapsible.DefaultTrigger>Show details</Collapsible.DefaultTrigger> <Collapsible.DefaultPanel> <Text>Content with border-left accent</Text> </Collapsible.DefaultPanel> </Collapsible.Root> ```  ## Controlled Accordion Pattern  ```tsx const [activeIndex, setActiveIndex] = useState<number | null>(null);  {items.map((item, i) => ( <Collapsible.Root key={i} open={activeIndex === i} onOpenChange={(open) => setActiveIndex(open ? i : null)} > <Collapsible.DefaultTrigger>{item.title}</Collapsible.DefaultTrigger> <Collapsible.DefaultPanel>{item.content}</Collapsible.DefaultPanel> </Collapsible.Root> ))} ```
 
 **Type:** component
 
@@ -1180,13 +1456,8 @@ Collapsible component for showing/hiding content.  Features: - Animated chevron
 
 **Props:**
 
-- `children`: ReactNode
-- `label`: string (required)
-  Text label displayed in the trigger button
-- `open`: boolean
-  Whether the collapsible content is visible
 - `className`: string
-  Additional CSS classes for the content panel
+  Additional CSS classes
 - `onOpenChange`: (open: boolean) => void
   Callback when collapsed state changes
 
@@ -1194,35 +1465,115 @@ Collapsible component for showing/hiding content.  Features: - Animated chevron
 
 `border-kumo-fill`, `text-kumo-link`
 
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Collapsible.Root
+
+Root sub-component
+
+Props:
+- `className`: string
+
+#### Collapsible.Trigger
+
+Trigger sub-component
+
+Props:
+- `className`: string
+
+#### Collapsible.Panel
+
+Panel sub-component
+
+Props:
+- `className`: string
+
+#### Collapsible.DefaultTrigger
+
+DefaultTrigger sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
+#### Collapsible.DefaultPanel
+
+DefaultPanel sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
+
 **Examples:**
 
 ```tsx
 <div className="w-full">
-      <Collapsible label="What is Kumo?" open={isOpen} onOpenChange={setIsOpen}>
-        Kumo is Cloudflare's new design system.
-      </Collapsible>
+      <Collapsible.Root open={isOpen} onOpenChange={setIsOpen}>
+        <Collapsible.DefaultTrigger>What is Kumo?</Collapsible.DefaultTrigger>
+        <Collapsible.DefaultPanel>
+          <Text>Kumo is Cloudflare's new design system.</Text>
+        </Collapsible.DefaultPanel>
+      </Collapsible.Root>
     </div>
 ```
 
 ```tsx
 <div className="w-full space-y-2">
-      <Collapsible label="What is Kumo?" open={open1} onOpenChange={setOpen1}>
-        Kumo is Cloudflare's new design system.
-      </Collapsible>
-      <Collapsible
-        label="How do I use it?"
-        open={open2}
-        onOpenChange={setOpen2}
-      >
-        Install the components and import them into your project.
-      </Collapsible>
-      <Collapsible
-        label="Is it open source?"
-        open={open3}
-        onOpenChange={setOpen3}
-      >
-        Check the repository for license information.
-      </Collapsible>
+      <Collapsible.Root open={open1} onOpenChange={setOpen1}>
+        <Collapsible.DefaultTrigger>What is Kumo?</Collapsible.DefaultTrigger>
+        <Collapsible.DefaultPanel>
+          <Text>Kumo is Cloudflare's new design system.</Text>
+        </Collapsible.DefaultPanel>
+      </Collapsible.Root>
+      <Collapsible.Root open={open2} onOpenChange={setOpen2}>
+        <Collapsible.DefaultTrigger>How do I use it?</Collapsible.DefaultTrigger>
+        <Collapsible.DefaultPanel>
+          <Text>Install the components and import them into your project.</Text>
+        </Collapsible.DefaultPanel>
+      </Collapsible.Root>
+      <Collapsible.Root open={open3} onOpenChange={setOpen3}>
+        <Collapsible.DefaultTrigger>Is it open source?</Collapsible.DefaultTrigger>
+        <Collapsible.DefaultPanel>
+          <Text>Check the repository for license information.</Text>
+        </Collapsible.DefaultPanel>
+      </Collapsible.Root>
+    </div>
+```
+
+```tsx
+<div className="w-full">
+      <Collapsible.Root open={isOpen} onOpenChange={setIsOpen}>
+        <Collapsible.Trigger
+          render={<Button variant="secondary" size="sm" />}
+        >
+          {isOpen ? "Hide details" : "Show details"}
+        </Collapsible.Trigger>
+        <Collapsible.Panel className="mt-3 rounded-lg bg-kumo-tint p-4">
+          <Text>
+            This panel uses custom styling instead of the default border-left accent.
+          </Text>
+        </Collapsible.Panel>
+      </Collapsible.Root>
+    </div>
+```
+
+```tsx
+<div className="w-full space-y-2">
+      {items.map((item, i) => (
+        <Collapsible.Root
+          key={i}
+          open={activeIndex === i}
+          onOpenChange={(open) => setActiveIndex(open ? i : null)}
+        >
+          <Collapsible.DefaultTrigger>{item.title}</Collapsible.DefaultTrigger>
+          <Collapsible.DefaultPanel>
+            <Text>{item.content}</Text>
+          </Collapsible.DefaultPanel>
+        </Collapsible.Root>
+      ))}
     </div>
 ```
 
@@ -1277,7 +1628,7 @@ Combobox — autocomplete input with filterable dropdown list.  Compound compone
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-fill-hover`, `bg-kumo-overlay`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-fill-hover`, `bg-kumo-overlay`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -1524,6 +1875,36 @@ Usage:
     </div>
 ```
 
+```tsx
+<div className="w-80">
+      <Combobox value={value} onValueChange={setValue} items={items}>
+        <Combobox.TriggerInput placeholder="Select database" />
+        <Combobox.Content>
+          <Combobox.Empty />
+          <Combobox.List>
+            {(item: DatabaseItemWithDisabled) => (
+              <Combobox.Item
+                key={item.value}
+                value={item}
+                disabled={item.disabled}
+              >
+                <span>
+                  {item.label}
+                  {item.reason && (
+                    <Text variant="secondary" size="xs" as="span">
+                      {" — "}
+                      {item.reason}
+                    </Text>
+                  )}
+                </span>
+              </Combobox.Item>
+            )}
+          </Combobox.List>
+        </Combobox.Content>
+      </Combobox>
+    </div>
+```
+
 ```tsx
 <div className="w-80">
       <Combobox
@@ -1656,7 +2037,7 @@ CommandPalette — accessible command palette / spotlight search overlay.  Compo
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-overlay`, `bg-kumo-warning`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-overlay`, `bg-kumo-warning`, `ring-kumo-brand`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -1823,6 +2204,70 @@ CommandPalette — accessible command palette / spotlight search overlay.  Compo
     </div>
 ```
 
+```tsx
+<div className="flex flex-col items-start gap-4">
+      <Button onClick={() => setOpen(true)}>
+        Open Palette (No Autocomplete)
+      </Button>
+
+      <CommandPalette.Root
+        open={open}
+        onOpenChange={setOpen}
+        items={filteredGroups}
+        value={search}
+        onValueChange={setSearch}
+        itemToStringValue={(group) => group.label}
+        onSelect={(item) => {
+          console.log("Selected:", item.title);
+          setOpen(false);
+          setSearch("");
+        }}
+        getSelectableItems={getSelectableItems}
+      >
+        <CommandPalette.Input
+          placeholder="Search commands..."
+          autoComplete="off"
+          autoCorrect="off"
+          autoCapitalize="none"
+          spellCheck={false}
+          data-1p-ignore="true"
+          data-lpignore="true"
+        />
+        <CommandPalette.List>
+          <CommandPalette.Results>
+            {(group: CommandGroup) => (
+              <CommandPalette.Group key={group.id} items={group.items}>
+                <CommandPalette.GroupLabel>
+                  {group.label}
+                </CommandPalette.GroupLabel>
+                <CommandPalette.Items>
+                  {(item: CommandItem) => (
+                    <CommandPalette.Item
+                      key={item.id}
+                      value={item}
+                      onClick={() => {
+                        setOpen(false);
+                        setSearch("");
+                      }}
+                    >
+                      <span className="flex items-center gap-3">
+                        {item.icon && (
+                          <span className="text-kumo-subtle">{item.icon}</span>
+                        )}
+                        <span>{item.title}</span>
+                      </span>
+                    </CommandPalette.Item>
+                  )}
+                </CommandPalette.Items>
+              </CommandPalette.Group>
+            )}
+          </CommandPalette.Results>
+          <CommandPalette.Empty>No commands found</CommandPalette.Empty>
+        </CommandPalette.List>
+      </CommandPalette.Root>
+    </div>
+```
+
 ```tsx
 <div>
       <Button onClick={() => setOpen(true)}>Open with ResultItem</Button>
@@ -2013,7 +2458,7 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
                   className={`rounded-md px-3 py-1.5 text-left whitespace-nowrap ${
                     isActive
                       ? "bg-kumo-bg-inverse text-kumo-text-inverse"
-                      : "text-kumo-strong hover:bg-kumo-control"
+                      : "text-kumo-subtle hover:bg-kumo-control"
                   }`}
                 >
                   {preset.label}
@@ -2085,7 +2530,7 @@ DateRangePicker — dual-calendar date range selector.  Renders two side-by-side
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-fill`, `bg-kumo-interact`, `bg-kumo-overlay`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-fill`, `bg-kumo-interact`, `bg-kumo-overlay`, `ring-kumo-focus`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -2465,7 +2910,7 @@ DropdownMenu — accessible dropdown menu anchored to a trigger.  Compound compo
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-control`, `bg-kumo-danger`, `bg-kumo-hairline`, `bg-kumo-overlay`, `bg-kumo-tint`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`
+`bg-kumo-control`, `bg-kumo-danger`, `bg-kumo-hairline`, `bg-kumo-overlay`, `bg-kumo-tint`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`
 
 **Sub-Components:**
 
@@ -2569,7 +3014,7 @@ Placeholder shown when a list, table, or page has no content to display.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-control`, `bg-kumo-overlay`, `border-kumo-fill`, `border-kumo-interact`, `text-kumo-brand`, `text-kumo-default`, `text-kumo-inactive`, `text-kumo-strong`, `text-kumo-success`
+`bg-kumo-control`, `bg-kumo-overlay`, `border-kumo-fill`, `border-kumo-interact`, `text-kumo-brand`, `text-kumo-default`, `text-kumo-inactive`, `text-kumo-subtle`, `text-kumo-success`
 
 **Examples:**
 
@@ -3010,121 +3455,481 @@ Input component
   - `"default"`: Default input appearance
   - `"error"`: Error state for validation failures
 
-  **State Classes:**
-  - `"default"`:
-    - `focus`: `focus:ring-kumo-hairline`
-  - `"error"`:
-    - `focus`: `focus:ring-kumo-danger`
+  **State Classes:**
+  - `"default"`:
+    - `focus`: `focus:ring-kumo-focus/50 focus:ring-[1.5px]`
+  - `"error"`:
+    - `focus`: `focus:ring-kumo-danger/50 focus:ring-[1.5px]`
+
+**Colors (kumo tokens used):**
+
+`bg-kumo-control`, `ring-kumo-danger`, `ring-kumo-focus`, `ring-kumo-line`, `text-kumo-default`
+
+**Styling:**
+
+- **Dimensions:** `[object Object]`
+
+**Examples:**
+
+```tsx
+<Input
+      label="Email"
+      placeholder="you@example.com"
+      description="We'll never share your email"
+    />
+```
+
+```tsx
+<Input
+      label="Email"
+      placeholder="you@example.com"
+      value="invalid-email"
+      error="Please enter a valid email address"
+    />
+```
+
+```tsx
+<Input
+      label="Password"
+      type="password"
+      value="short"
+      error={{
+        message: "Password must be at least 8 characters",
+        match: "tooShort",
+      }}
+      minLength={8}
+    />
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+      <Input size="xs" label="Extra Small" placeholder="Extra small input" />
+      <Input size="sm" label="Small" placeholder="Small input" />
+      <Input label="Base" placeholder="Base input (default)" />
+      <Input size="lg" label="Large" placeholder="Large input" />
+    </div>
+```
+
+```tsx
+<Input label="Disabled field" placeholder="Cannot edit" disabled />
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+      <Input type="email" label="Email" placeholder="you@example.com" />
+      <Input type="password" label="Password" placeholder="••••••••" />
+      <Input type="number" label="Age" placeholder="18" />
+      <Input type="tel" label="Phone" placeholder="+1 (555) 000-0000" />
+    </div>
+```
+
+```tsx
+<Input
+      label="Phone Number"
+      required={false}
+      placeholder="+1 (555) 000-0000"
+    />
+```
+
+```tsx
+<Input
+      label="API Key"
+      labelTooltip="Find this in your dashboard under Settings > API Keys"
+      placeholder="sk_live_..."
+    />
+```
+
+```tsx
+<Input
+      label={
+        <span>
+          Email for <strong>billing</strong>
+        </span>
+      }
+      required
+      placeholder="billing@company.com"
+      type="email"
+    />
+```
+
+```tsx
+<Input
+      label="With onChange"
+      placeholder="Type something..."
+      description={value ? `Value: ${value}` : "Uses e.target.value"}
+      value={value}
+      onChange={(e) => setValue(e.target.value)}
+    />
+```
+
+```tsx
+<Input
+      label="With onValueChange"
+      placeholder="Type something..."
+      description={value ? `Value: ${value}` : "Receives the value directly"}
+      value={value}
+      onValueChange={(v) => setValue(v)}
+    />
+```
+
+
+---
+
+### InputGroup
+
+InputGroup component
+
+**Type:** component
+
+**Import:** `import { InputGroup } from "@cloudflare/kumo";`
+
+**Category:** Input
+
+**Props:**
+
+- `label`: ReactNode
+  The label content — can be a string or any React node.
+- `description`: ReactNode
+  Helper text displayed below the control (hidden when `error` is present).
+- `error`: object
+  Validation error with a message and a browser `ValidityState` match key.
+- `required`: boolean
+  When explicitly `false`, shows gray "(optional)" text after the label. When `true` or `undefined`, no indicator is shown.
+- `labelTooltip`: ReactNode
+  Tooltip content displayed next to the label via an info icon.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `size`: enum [default: base]
+  - `"xs"`: Extra small size.
+  - `"sm"`: Small size.
+  - `"base"`: Default size.
+  - `"lg"`: Large size.
+- `disabled`: boolean
+
+**Colors (kumo tokens used):**
+
+`border-kumo-line`, `ring-kumo-danger`, `ring-kumo-focus`, `ring-kumo-line`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### InputGroup.Input
+
+Input sub-component
+
+#### InputGroup.Button
+
+Button sub-component
+
+Props:
+- `tooltip`: ReactNode - When provided, wraps the button in a Tooltip. Automatically sets aria-label from a string value.
+- `tooltipSide`: "top" | "right" | "bottom" | "left" [default: "bottom"] - Preferred side for the tooltip popup.
+- `variant`: "primary" | "secondary" | "ghost" | "destructive" | "secondary-destructive" | "outline" [default: "ghost"] - Button visual style. Defaults to ghost.
+- `size`: "xs" | "sm" | "base" | "lg" [default: "sm"] - Button size.
+
+#### InputGroup.Addon
 
-**Colors (kumo tokens used):**
+Addon sub-component
 
-`bg-kumo-control`, `ring-kumo-danger`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-subtle`
+Props:
+- `align`: "start" | "end" [default: "start"] - Position relative to the input.
+- `className`: string - Additional CSS classes.
 
-**Styling:**
+#### InputGroup.Suffix
 
-- **Dimensions:** `[object Object]`
+Suffix sub-component
 
-**Examples:**
+Props:
+- `className`: string - Additional CSS classes.
 
-```tsx
-<Input
-      label="Email"
-      placeholder="you@example.com"
-      description="We'll never share your email"
-    />
-```
+#### InputGroup.Label
+
+Label sub-component
+
+#### InputGroup.Description
+
+Description sub-component
+
+
+**Examples:**
 
 ```tsx
-<Input
-      label="Email"
-      placeholder="you@example.com"
-      value="invalid-email"
-      error="Please enter a valid email address"
-    />
+<div className="w-full max-w-2xs">
+      <InputGroup>
+        <InputGroup.Input
+          maxLength={20}
+          onChange={handleChange}
+          value={value}
+        />
+        <InputGroup.Suffix>.workers.dev</InputGroup.Suffix>
+        {status !== "idle" && (
+          <InputGroup.Addon align="end">
+            {status === "loading" ? (
+              <Loader />
+            ) : (
+              <CheckCircleIcon weight="duotone" className="text-kumo-success" />
+            )}
+          </InputGroup.Addon>
+        )}
+      </InputGroup>
+    </div>
 ```
 
 ```tsx
-<Input
-      label="Password"
-      type="password"
-      value="short"
-      error={{
-        message: "Password must be at least 8 characters",
-        match: "tooShort",
-      }}
-      minLength={8}
-    />
+<InputGroup className="w-full max-w-3xs">
+      <InputGroup.Addon>
+        <LinkIcon />
+      </InputGroup.Addon>
+      <InputGroup.Input placeholder="Paste a link..." aria-label="Link" />
+    </InputGroup>
 ```
 
 ```tsx
 <div className="flex flex-col gap-4">
-      <Input size="xs" label="Extra Small" placeholder="Extra small input" />
-      <Input size="sm" label="Small" placeholder="Small input" />
-      <Input label="Base" placeholder="Base input (default)" />
-      <Input size="lg" label="Large" placeholder="Large input" />
+      <InputGroup className="w-full max-w-3xs">
+        <InputGroup.Addon>@</InputGroup.Addon>
+        <InputGroup.Input placeholder="username" aria-label="Username" />
+      </InputGroup>
+
+      <InputGroup className="w-full max-w-3xs">
+        <InputGroup.Input placeholder="email" aria-label="Email" />
+        <InputGroup.Addon align="end">@example.com</InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup className="w-full max-w-3xs">
+        <InputGroup.Addon>/api/</InputGroup.Addon>
+        <InputGroup.Input placeholder="endpoint" aria-label="API path" />
+        <InputGroup.Addon align="end">.json</InputGroup.Addon>
+      </InputGroup>
     </div>
 ```
 
 ```tsx
-<Input label="Disabled field" placeholder="Cannot edit" disabled />
+<div className="flex flex-col gap-4">
+      <InputGroup className="w-full max-w-3xs">
+        <InputGroup.Input
+          type={show ? "text" : "password"}
+          defaultValue="password"
+          aria-label="Password"
+        />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={show ? EyeSlashIcon : EyeIcon}
+            aria-label={show ? "Hide password" : "Show password"}
+            onClick={() => setShow(!show)}
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup className="w-full max-w-3xs">
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input
+          value={searchValue}
+          placeholder="Search"
+          aria-label="Search"
+          onChange={(e) => setSearchValue(e.target.value)}
+        />
+        {searchValue && (
+          <InputGroup.Addon align="end" className="pr-1">
+            <InputGroup.Button
+              aria-label="Clear search"
+              onClick={() => setSearchValue("")}
+            >
+              <XIcon />
+            </InputGroup.Button>
+          </InputGroup.Addon>
+        )}
+        <InputGroup.Button variant="secondary" onClick={() => {}}>
+          Search
+        </InputGroup.Button>
+      </InputGroup>
+    </div>
 ```
 
 ```tsx
-<div className="flex flex-col gap-4">
-      <Input type="email" label="Email" placeholder="you@example.com" />
-      <Input type="password" label="Password" placeholder="••••••••" />
-      <Input type="number" label="Age" placeholder="18" />
-      <Input type="tel" label="Phone" placeholder="+1 (555) 000-0000" />
-    </div>
+<InputGroup className="w-full max-w-2xs">
+      <InputGroup.Addon>
+        <MagnifyingGlassIcon />
+      </InputGroup.Addon>
+      <InputGroup.Input
+        placeholder="Search with query language..."
+        aria-label="Search"
+      />
+      <InputGroup.Addon align="end">
+        <InputGroup.Button
+          className="text-kumo-subtle"
+          icon={QuestionIcon}
+          tooltip="Query language help"
+          onClick={() => {}}
+        />
+      </InputGroup.Addon>
+    </InputGroup>
 ```
 
 ```tsx
-<Input
-      label="Phone Number"
-      required={false}
-      placeholder="+1 (555) 000-0000"
-    />
+<InputGroup className="w-full max-w-3xs">
+      <InputGroup.Addon>
+        <MagnifyingGlassIcon />
+      </InputGroup.Addon>
+      <InputGroup.Input placeholder="Search..." aria-label="Search" />
+      <InputGroup.Addon align="end">
+        <kbd className="bg-none! border-none!">⌘K</kbd>
+      </InputGroup.Addon>
+    </InputGroup>
 ```
 
 ```tsx
-<Input
-      label="API Key"
-      labelTooltip="Find this in your dashboard under Settings > API Keys"
-      placeholder="sk_live_..."
-    />
+<InputGroup className="w-full max-w-3xs">
+      <InputGroup.Input defaultValue="kumo" aria-label="kumo" />
+      <InputGroup.Addon align="end">
+        <Loader />
+      </InputGroup.Addon>
+    </InputGroup>
 ```
 
 ```tsx
-<Input
-      label={
-        <span>
-          Email for <strong>billing</strong>
-        </span>
-      }
-      required
-      placeholder="billing@company.com"
-      type="email"
-    />
+<div className="flex w-full max-w-2xs flex-col gap-4">
+      <InputGroup label="Subdomain">
+        <InputGroup.Input
+          aria-label="Subdomain"
+          defaultValue="kumo"
+          maxLength={20}
+        />
+        <InputGroup.Suffix>.workers.dev</InputGroup.Suffix>
+        <InputGroup.Addon align="end">
+          <CheckCircleIcon weight="duotone" className="text-kumo-success" />
+        </InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup
+        label="Subdomain"
+        error={{ message: "This subdomain is unavailable", match: true }}
+      >
+        <InputGroup.Input
+          aria-label="Subdomain"
+          defaultValue="kumo"
+          maxLength={20}
+        />
+        <InputGroup.Suffix>.workers.dev</InputGroup.Suffix>
+        <InputGroup.Addon align="end">
+          <XCircleIcon weight="duotone" className="text-kumo-danger" />
+        </InputGroup.Addon>
+      </InputGroup>
+    </div>
 ```
 
 ```tsx
-<Input
-      label="With onChange"
-      placeholder="Type something..."
-      description={value ? `Value: ${value}` : "Uses e.target.value"}
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    />
+<div className="flex w-full max-w-3xs flex-col gap-4">
+      <InputGroup size="xs" label="Extra Small">
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input placeholder="Extra small input" />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={QuestionIcon}
+            shape="square"
+            aria-label="Help"
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup size="sm" label="Small">
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input placeholder="Small input" />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={QuestionIcon}
+            shape="square"
+            aria-label="Help"
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup label="Base (default)">
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input placeholder="Base input" />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={QuestionIcon}
+            shape="square"
+            aria-label="Help"
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup size="lg" label="Large">
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input placeholder="Large input" />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={QuestionIcon}
+            shape="square"
+            aria-label="Help"
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+    </div>
 ```
 
 ```tsx
-<Input
-      label="With onValueChange"
-      placeholder="Type something..."
-      description={value ? `Value: ${value}` : "Receives the value directly"}
-      value={value}
-      onValueChange={(v) => setValue(v)}
-    />
+<div className="flex w-full max-w-3xs flex-col gap-4">
+      <InputGroup
+        label="Error State"
+        error={{ message: "Please enter a valid email address", match: true }}
+      >
+        <InputGroup.Input type="email" defaultValue="invalid-email" />
+        <InputGroup.Addon align="end">@example.com</InputGroup.Addon>
+      </InputGroup>
+
+      <InputGroup label="Disabled" disabled>
+        <InputGroup.Addon>
+          <MagnifyingGlassIcon />
+        </InputGroup.Addon>
+        <InputGroup.Input placeholder="Search..." />
+      </InputGroup>
+
+      <InputGroup label="Optional Field" required={false}>
+        <InputGroup.Addon>$</InputGroup.Addon>
+        <InputGroup.Input placeholder="0.00" />
+      </InputGroup>
+
+      <InputGroup
+        label="With Description"
+        description="Must be at least 8 characters"
+        labelTooltip="Your password is stored securely"
+      >
+        <InputGroup.Input
+          type={show ? "text" : "password"}
+          placeholder="Password"
+        />
+        <InputGroup.Addon align="end">
+          <InputGroup.Button
+            className="text-kumo-subtle"
+            icon={show ? EyeSlashIcon : EyeIcon}
+            aria-label={show ? "Hide password" : "Show password"}
+            onClick={() => setShow(!show)}
+          />
+        </InputGroup.Addon>
+      </InputGroup>
+    </div>
 ```
 
 
@@ -3157,7 +3962,7 @@ Label component for form fields.  Provides a standardized way to display labels
 
 **Colors (kumo tokens used):**
 
-`text-kumo-default`, `text-kumo-strong`
+`text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -3227,7 +4032,7 @@ LayerCard component
 **Props:**
 
 - `render`: ReactNode
-  Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
+  Allows you to replace the component's HTML element with a different tag, or compose it with another component.
 
 Accepts a `ReactElement` or a function that returns the element to render.
 - `children`: ReactNode
@@ -3238,7 +4043,7 @@ Accepts a `ReactElement` or a function that returns the element to render.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `ring-kumo-fill`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-strong`
+`bg-kumo-base`, `bg-kumo-elevated`, `ring-kumo-fill`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -3338,7 +4143,7 @@ Link component
 - `type`: string
 - `referrerPolicy`: enum
 - `render`: ReactNode
-  Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
+  Allows you to replace the component's HTML element with a different tag, or compose it with another component.
 
 Accepts a `ReactElement` or a function that returns the element to render.
 
@@ -3484,7 +4289,7 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-recessed`, `border-kumo-recessed`, `ring-kumo-line`
+`bg-kumo-base`, `bg-kumo-recessed`, `border-kumo-recessed`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-line`
 
 **Styling:**
 
@@ -3546,7 +4351,7 @@ Progress bar showing a measured value within a known range (e.g. quota usage).
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-fill`, `text-kumo-default`, `text-kumo-strong`
+`bg-kumo-fill`, `text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -3610,7 +4415,7 @@ For visible text like "Showing X of Y", use render props on sub-components:
 
 **Colors (kumo tokens used):**
 
-`border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-strong`
+`border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -4059,7 +4864,7 @@ Close sub-component
 
 ### Radio
 
-Radio — radio button group for single-select choices.  Compound component: `Radio.Group` (with built-in Fieldset) and `Radio.Item`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
+Radio — radio button group for single-select choices.  Compound component: `Radio.Group` (with built-in Fieldset), `Radio.Item`, and `Radio.Legend`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
 
 **Type:** component
 
@@ -4069,10 +4874,10 @@ Radio — radio button group for single-select choices.  Compound component: `Ra
 
 **Props:**
 
-- `legend`: string (required)
-  Legend text for the group (required for accessibility)
+- `legend`: string
+  Legend text for the group (required for accessibility). For more control over legend styling, omit this prop and use `<Radio.Legend>` as a child instead.
 - `children`: ReactNode
-  Child Radio.Item components
+  Child Radio.Item components (and optionally a Radio.Legend)
 - `orientation`: enum
   Layout direction of the radio items
 - `appearance`: enum [default: default]
@@ -4091,7 +4896,7 @@ Radio — radio button group for single-select choices.  Compound component: `Ra
 - `disabled`: boolean
   Whether all radios in the group are disabled
 - `controlPosition`: enum
-  Position of radio control relative to label: "start" (default) puts radio before label, "end" puts label before radio. Note: In card appearance, the control is always positioned at the end.
+  Position of radio control relative to label: "start" puts radio before label, "end" puts label before radio. Defaults to "start" for default appearance and "end" for card appearance.
 - `name`: string
   Form submission name for the radio group
 - `className`: string
@@ -4099,7 +4904,7 @@ Radio — radio button group for single-select choices.  Compound component: `Ra
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-tint`, `border-kumo-danger`, `border-kumo-hairline`, `border-kumo-interact`, `ring-kumo-danger`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-tint`, `border-kumo-danger`, `border-kumo-hairline`, `border-kumo-interact`, `ring-kumo-brand`, `ring-kumo-danger`, `ring-kumo-focus`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -4114,7 +4919,7 @@ Item sub-component
 Group sub-component
 
 Props:
-- `legend`: string (required)
+- `legend`: string
 - `children`: ReactNode (required)
 - `orientation`: "vertical" | "horizontal"
 - `appearance`: KumoRadioAppearance
@@ -4122,12 +4927,19 @@ Props:
 - `description`: ReactNode
 - `value`: string
 - `disabled`: boolean
-- `label`: "start" (default) puts radio before label (required)
-- `Note`: In card appearance (required)
+- `label`: "start" puts radio before label (required)
 - `controlPosition`: RadioControlPosition
 - `name`: string
 - `className`: string
 
+#### Radio.Legend
+
+Legend sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
 
 **Examples:**
 
@@ -4283,6 +5095,76 @@ Props:
     </Radio.Group>
 ```
 
+```tsx
+<Radio.Group defaultValue="all" value={value} onValueChange={setValue}>
+      <Radio.Legend className="sr-only">Paths</Radio.Legend>
+      <Radio.Item label="Allow all paths" value="all" />
+      <Radio.Item label="Restrict to specific paths" value="specific" />
+    </Radio.Group>
+```
+
+```tsx
+<Radio.Group value={value} onValueChange={setValue}>
+      <Radio.Legend className="text-sm font-normal text-kumo-subtle">
+        Notification preference
+      </Radio.Legend>
+      <Radio.Item label="Email" value="email" />
+      <Radio.Item label="SMS" value="sms" />
+      <Radio.Item label="Push notification" value="push" />
+    </Radio.Group>
+```
+
+```tsx
+<Radio.Group
+      legend="Choose a plan"
+      appearance="card"
+      controlPosition="start"
+      value={value}
+      onValueChange={setValue}
+    >
+      <Radio.Item
+        label="Free"
+        description="For personal or hobby projects that aren't business-critical."
+        value="free"
+      />
+      <Radio.Item
+        label="Pro"
+        description="For professional websites that aren't business-critical."
+        value="pro"
+      />
+    </Radio.Group>
+```
+
+```tsx
+<Radio.Group
+      legend="Choose a plan"
+      appearance="card"
+      value={value}
+      onValueChange={setValue}
+    >
+      <Radio.Item
+        label={
+          <span className="flex items-center gap-2">
+            Free
+            <Badge variant="neutral">$0</Badge>
+          </span>
+        }
+        description="For personal or hobby projects."
+        value="free"
+      />
+      <Radio.Item
+        label={
+          <span className="flex items-center gap-2">
+            Pro
+            <Badge variant="primary">Popular</Badge>
+          </span>
+        }
+        description="For professional websites."
+        value="pro"
+      />
+    </Radio.Group>
+```
+
 ```tsx
 <Radio.Group
       legend="Choose a plan"
@@ -4361,7 +5243,7 @@ Select component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-hairline`, `bg-kumo-tint`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-placeholder`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-hairline`, `bg-kumo-tint`, `border-kumo-line`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-placeholder`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -4746,7 +5628,7 @@ Password/secret input that masks its value by default and reveals on click. Incl
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-brand`, `bg-kumo-control`, `outline-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-brand`, `bg-kumo-control`, `outline-kumo-focus`, `ring-kumo-brand`, `ring-kumo-focus`, `text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -4863,7 +5745,7 @@ Sidebar — responsive navigation panel with expand/collapse support.  Compound
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-hairline`, `bg-kumo-overlay`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-hairline`, `bg-kumo-overlay`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-brand`, `ring-kumo-hairline`, `text-kumo-default`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -4893,66 +5775,129 @@ Props:
 
 Header sub-component
 
+Props:
+- `collapsible`: boolean
+- `defaultOpen`: boolean
+- `open`: boolean
+
 #### Sidebar.Content
 
 Content sub-component
 
+Props:
+- `collapsible`: boolean
+- `defaultOpen`: boolean
+- `open`: boolean
+
 #### Sidebar.Footer
 
 Footer sub-component
 
+Props:
+- `collapsible`: boolean
+- `defaultOpen`: boolean
+- `open`: boolean
+
 #### Sidebar.Group
 
 Group sub-component
 
+Props:
+- `collapsible`: boolean
+- `defaultOpen`: boolean
+- `open`: boolean
+
 #### Sidebar.GroupLabel
 
 GroupLabel sub-component
 
+Props:
+- `icon`: React.ComponentType<{ className?: string
+
 #### Sidebar.GroupContent
 
 GroupContent sub-component
 
+Props:
+- `icon`: React.ComponentType<{ className?: string
+
 #### Sidebar.Menu
 
 Menu sub-component
 
+Props:
+- `icon`: React.ComponentType<{ className?: string
+
 #### Sidebar.MenuItem
 
 MenuItem sub-component
 
+Props:
+- `icon`: React.ComponentType<{ className?: string
+
 #### Sidebar.MenuButton
 
 MenuButton sub-component
 
+Props:
+- `icon`: React.ComponentType<{ className?: string
+
 #### Sidebar.MenuAction
 
 MenuAction sub-component
 
+Props:
+- `active`: boolean
+- `href`: string
+
 #### Sidebar.MenuBadge
 
 MenuBadge sub-component
 
+Props:
+- `active`: boolean
+- `href`: string
+
 #### Sidebar.MenuSub
 
 MenuSub sub-component
 
+Props:
+- `active`: boolean
+- `href`: string
+
 #### Sidebar.MenuSubItem
 
 MenuSubItem sub-component
 
+Props:
+- `active`: boolean
+- `href`: string
+
 #### Sidebar.MenuSubButton
 
 MenuSubButton sub-component
 
+Props:
+- `active`: boolean
+- `href`: string
+
 #### Sidebar.Separator
 
 Separator sub-component
 
+Props:
+- `placeholder`: string
+- `shortcut`: string
+
 #### Sidebar.Input
 
 Input sub-component
 
+Props:
+- `placeholder`: string
+- `shortcut`: string
+
 #### Sidebar.Trigger
 
 Trigger sub-component
@@ -4969,6 +5914,9 @@ ResizeHandle sub-component
 
 MenuChevron sub-component
 
+Props:
+- `className`: string
+
 #### Sidebar.Collapsible
 
 Collapsible sub-component
@@ -5310,7 +6258,7 @@ Surface component
 
 - `as`: React.ElementType
 - `render`: ReactNode
-  Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
+  Allows you to replace the component's HTML element with a different tag, or compose it with another component.
 
 Accepts a `ReactElement` or a function that returns the element to render.
 - `children`: ReactNode
@@ -5363,7 +6311,7 @@ Switch component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-base`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -5378,7 +6326,7 @@ Item sub-component
 Group sub-component
 
 Props:
-- `legend`: string (required)
+- `legend`: string
 - `children`: ReactNode (required)
 - `error`: string
 - `description`: ReactNode
@@ -5386,6 +6334,14 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+#### Switch.Legend
+
+Legend sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
 
 **Examples:**
 
@@ -5457,6 +6413,23 @@ Props:
     />
 ```
 
+```tsx
+<Switch.Group legend="Notification settings">
+      <Switch.Item label="Email notifications" />
+      <Switch.Item label="SMS notifications" />
+      <Switch.Item label="Push notifications" />
+    </Switch.Group>
+```
+
+```tsx
+<Switch.Group>
+      <Switch.Legend className="sr-only">Notification settings</Switch.Legend>
+      <Switch.Item label="Email notifications" />
+      <Switch.Item label="SMS notifications" />
+      <Switch.Item label="Push notifications" />
+    </Switch.Group>
+```
+
 ```tsx
 <div className="flex flex-col gap-4">
       <Switch
@@ -5511,7 +6484,7 @@ Table — semantic HTML table with styled rows, cells, and selection support.  C
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-hairline`, `bg-kumo-tint`, `border-kumo-fill`, `text-kumo-default`, `text-kumo-strong`
+`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-hairline`, `bg-kumo-tint`, `border-kumo-fill`, `ring-kumo-brand`, `text-kumo-default`, `text-kumo-strong`
 
 **Sub-Components:**
 
@@ -5589,7 +6562,7 @@ ResizeHandle sub-component
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < rows.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -5602,7 +6575,7 @@ ResizeHandle sub-component
             <Table.Row key={row.id}>
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>{row.subject}</Table.Cell>
@@ -5648,7 +6621,7 @@ ResizeHandle sub-component
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < rows.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -5664,7 +6637,7 @@ ResizeHandle sub-component
             >
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>{row.subject}</Table.Cell>
@@ -5863,7 +6836,7 @@ ResizeHandle sub-component
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < emailData.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -5880,7 +6853,7 @@ ResizeHandle sub-component
             >
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>
@@ -5958,7 +6931,7 @@ TableOfContents — presentational compound component for section navigation.  P
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-brand`, `bg-kumo-line`, `bg-kumo-tint`, `text-kumo-default`, `text-kumo-subtle`
+`border-kumo-brand`, `border-kumo-hairline`, `border-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -5976,10 +6949,18 @@ List sub-component
 
 Item sub-component
 
+Props:
+- `active`: boolean
+
 #### TableOfContents.Group
 
 Group sub-component
 
+Props:
+- `label`: string (required)
+- `href`: string
+- `active`: boolean
+
 
 **Examples:**
 
@@ -6045,6 +7026,14 @@ Group sub-component
           <TableOfContents.Item active className="cursor-pointer">
             Overview
           </TableOfContents.Item>
+          <TableOfContents.Group label="Examples" href="#examples-demo">
+            <TableOfContents.Item className="cursor-pointer">
+              Basic example
+            </TableOfContents.Item>
+            <TableOfContents.Item className="cursor-pointer">
+              Advanced example
+            </TableOfContents.Item>
+          </TableOfContents.Group>
           <TableOfContents.Group label="Getting Started">
             <TableOfContents.Item className="cursor-pointer">
               Installation
@@ -6053,7 +7042,7 @@ Group sub-component
               Configuration
             </TableOfContents.Item>
           </TableOfContents.Group>
-          <TableOfContents.Group label="API">
+          <TableOfContents.Group label="API" href="#api-demo">
             <TableOfContents.Item className="cursor-pointer">
               Props
             </TableOfContents.Item>
@@ -6128,7 +7117,7 @@ Tab navigation component with segmented or underline style. Built on Base UI Tab
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-hairline`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -6265,8 +7254,11 @@ Text component
   Whether to use bold font weight (only applies to body variants).
 - `truncate`: boolean
   Whether to truncate overflowing text with an ellipsis. Adds `truncate min-w-0` classes.
-- `as`: React.ElementType
-  The HTML element type to render as (e.g. `"span"`, `"p"`, `"h1"`). Auto-selected based on variant if omitted.
+- `as`: enum
+  The HTML element to render. Accepts headings (`"h1"`–`"h6"`), block text (`"p"`, `"pre"`), inline text (`"span"`, `"code"`, `"em"`, `"strong"`, `"small"`, `"abbr"`, `"time"`), form-related (`"label"`, `"legend"`), list/definition (`"dt"`, `"dd"`, `"li"`), and `"figcaption"`.
+
+- **Required** for heading variants (`"heading1"`, `"heading2"`,   `"heading3"`) — pick the element that reflects this text's place in   the document outline, or `"span"` for decorative heading-styled text   that is not a section heading.
+- **Optional** for body variants (defaults to `"p"`) and monospace   variants (defaults to `"span"`).
 - `children`: ReactNode
   Text content.
 
@@ -6282,15 +7274,21 @@ Text component
 ```tsx
 <div className="grid w-full grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
       <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
-        <Text variant="heading1">Heading 1</Text>
+        <Text variant="heading1" as="h1">
+          Heading 1
+        </Text>
         <Text variant="mono-secondary">text-3xl (30px)</Text>
       </div>
       <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
-        <Text variant="heading2">Heading 2</Text>
+        <Text variant="heading2" as="h2">
+          Heading 2
+        </Text>
         <Text variant="mono-secondary">text-2xl (24px)</Text>
       </div>
       <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
-        <Text variant="heading3">Heading 3</Text>
+        <Text variant="heading3" as="h3">
+          Heading 3
+        </Text>
         <Text variant="mono-secondary">text-lg (16px)</Text>
       </div>
       <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
@@ -6379,7 +7377,7 @@ Toasty — toast notification provider and viewport.  Renders a `Toast.Provider`
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-control`, `bg-kumo-danger`, `bg-kumo-fill-hover`, `bg-kumo-info`, `bg-kumo-success`, `bg-kumo-warning`, `border-kumo-fill`, `ring-kumo-danger`, `ring-kumo-hairline`, `ring-kumo-info`, `ring-kumo-line`, `ring-kumo-success`, `ring-kumo-warning`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-info`, `text-kumo-strong`, `text-kumo-subtle`, `text-kumo-success`, `text-kumo-warning`
+`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-control`, `bg-kumo-danger`, `bg-kumo-fill-hover`, `bg-kumo-info`, `bg-kumo-success`, `bg-kumo-warning`, `border-kumo-fill`, `ring-kumo-danger`, `ring-kumo-hairline`, `ring-kumo-info`, `ring-kumo-line`, `ring-kumo-success`, `ring-kumo-warning`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-info`, `text-kumo-subtle`, `text-kumo-success`, `text-kumo-warning`
 
 **Styling:**
 
@@ -6516,11 +7514,11 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 ## Quick Reference
 
 **Components by Category:**
+- **Other:** Autocomplete, CloudflareLogo, DatePicker, Label, Link, SensitiveInput, Sidebar, Table, TableOfContents, DeleteResource
 - **Display:** Badge, Breadcrumbs, Code, Collapsible, Empty, LayerCard, Meter, Text
 - **Feedback:** Banner, Loader, Toasty
 - **Action:** Button, ClipboardText
-- **Input:** Checkbox, Combobox, DateRangePicker, Field, Input, Radio, Select, Switch
-- **Other:** CloudflareLogo, DatePicker, Label, Link, SensitiveInput, Sidebar, Table, TableOfContents, DeleteResource
+- **Input:** Checkbox, Combobox, DateRangePicker, Field, Input, InputGroup, Radio, Select, Switch
 - **Navigation:** CommandPalette, MenuBar, Pagination, Tabs
 - **Overlay:** Dialog, DropdownMenu, Popover, Tooltip
 - **Layout:** Grid, Surface, PageHeader, ResourceListPage