@cloudflare/kumo 1.18.0 → 2.0.0

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`, `ring-kumo-line`, `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`, `ring-kumo-line`, `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-line`, `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:**
 
@@ -980,7 +1256,7 @@ Cloudflare logo component.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `ring-kumo-line`, `text-kumo-default`
+`bg-kumo-base`, `ring-kumo-hairline`, `text-kumo-default`
 
 **Examples:**
 
@@ -1108,7 +1384,7 @@ Cloudflare logo component.
 ```
 
 ```tsx
-<footer className="flex w-full items-center justify-between rounded-lg border border-kumo-line bg-kumo-elevated px-6 py-4">
+<footer className="flex w-full items-center justify-between rounded-lg border border-kumo-hairline bg-kumo-elevated px-6 py-4">
       <span className="text-sm text-kumo-subtle">
         &copy; 2026 Your Company. All rights reserved.
       </span>
@@ -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-line`, `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-strong`, `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-line`, `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-strong`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -1714,13 +2095,13 @@ CommandPalette — accessible command palette / spotlight search overlay.  Compo
         </CommandPalette.List>
         <CommandPalette.Footer>
           <span className="flex items-center gap-2">
-            <kbd className="rounded border border-kumo-line bg-kumo-base px-1.5 py-0.5 text-[10px]">
+            <kbd className="rounded border border-kumo-hairline bg-kumo-base px-1.5 py-0.5 text-[10px]">
               ↑↓
             </kbd>
             <span>Navigate</span>
           </span>
           <span className="flex items-center gap-2">
-            <kbd className="rounded border border-kumo-line bg-kumo-base px-1.5 py-0.5 text-[10px]">
+            <kbd className="rounded border border-kumo-hairline bg-kumo-base px-1.5 py-0.5 text-[10px]">
               ↵
             </kbd>
             <span>Select</span>
@@ -1824,52 +2205,116 @@ CommandPalette — accessible command palette / spotlight search overlay.  Compo
 ```
 
 ```tsx
-<div>
-      <Button onClick={() => setOpen(true)}>Open with ResultItem</Button>
+<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={searchResults}
+        items={filteredGroups}
         value={search}
         onValueChange={setSearch}
-        itemToStringValue={(item) => item.title}
-        getSelectableItems={(items) => items}
+        itemToStringValue={(group) => group.label}
+        onSelect={(item) => {
+          console.log("Selected:", item.title);
+          setOpen(false);
+          setSearch("");
+        }}
+        getSelectableItems={getSelectableItems}
       >
-        <CommandPalette.Input placeholder="Search documentation..." />
+        <CommandPalette.Input
+          placeholder="Search commands..."
+          autoComplete="off"
+          autoCorrect="off"
+          autoCapitalize="none"
+          spellCheck={false}
+          data-1p-ignore="true"
+          data-lpignore="true"
+        />
         <CommandPalette.List>
           <CommandPalette.Results>
-            {(item: SearchResult) => (
-              <CommandPalette.ResultItem
-                key={item.id}
-                value={item}
-                title={item.title}
-                breadcrumbs={item.breadcrumbs}
-                icon={item.icon}
-                onClick={() => {
-                  console.log("Navigate to:", item.title);
-                  setOpen(false);
-                }}
-              />
-            )}
-          </CommandPalette.Results>
-          <CommandPalette.Empty>No pages found</CommandPalette.Empty>
-        </CommandPalette.List>
-        <CommandPalette.Footer>
-          <span className="flex items-center gap-2">
-            <kbd className="rounded border border-kumo-line bg-kumo-base px-1.5 py-0.5 text-[10px]">
-              ↑↓
-            </kbd>
-            <span>Navigate</span>
-          </span>
-          <span className="flex items-center gap-2">
-            <kbd className="rounded border border-kumo-line bg-kumo-base px-1.5 py-0.5 text-[10px]">
-              ⌘↵
-            </kbd>
-            <span>Open in new tab</span>
-          </span>
-        </CommandPalette.Footer>
-      </CommandPalette.Root>
+            {(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>
+
+      <CommandPalette.Root
+        open={open}
+        onOpenChange={setOpen}
+        items={searchResults}
+        value={search}
+        onValueChange={setSearch}
+        itemToStringValue={(item) => item.title}
+        getSelectableItems={(items) => items}
+      >
+        <CommandPalette.Input placeholder="Search documentation..." />
+        <CommandPalette.List>
+          <CommandPalette.Results>
+            {(item: SearchResult) => (
+              <CommandPalette.ResultItem
+                key={item.id}
+                value={item}
+                title={item.title}
+                breadcrumbs={item.breadcrumbs}
+                icon={item.icon}
+                onClick={() => {
+                  console.log("Navigate to:", item.title);
+                  setOpen(false);
+                }}
+              />
+            )}
+          </CommandPalette.Results>
+          <CommandPalette.Empty>No pages found</CommandPalette.Empty>
+        </CommandPalette.List>
+        <CommandPalette.Footer>
+          <span className="flex items-center gap-2">
+            <kbd className="rounded border border-kumo-hairline bg-kumo-base px-1.5 py-0.5 text-[10px]">
+              ↑↓
+            </kbd>
+            <span>Navigate</span>
+          </span>
+          <span className="flex items-center gap-2">
+            <kbd className="rounded border border-kumo-hairline bg-kumo-base px-1.5 py-0.5 text-[10px]">
+              ⌘↵
+            </kbd>
+            <span>Open in new tab</span>
+          </span>
+        </CommandPalette.Footer>
+      </CommandPalette.Root>
     </div>
 ```
 
@@ -1901,11 +2346,15 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
 
 ```tsx
 <div className="flex flex-col gap-4">
-      <DatePicker mode="single" selected={date} onChange={d => {
-        if (d) {
-          setDate(d);
-        }
-      }} />
+      <DatePicker
+        mode="single"
+        selected={date}
+        onChange={(d) => {
+          if (d) {
+            setDate(d);
+          }
+        }}
+      />
       <p className="text-sm text-kumo-subtle">
         Selected: {date ? date.toLocaleDateString() : "None"}
       </p>
@@ -1960,10 +2409,10 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button variant="outline" icon={CalendarDotsIcon}>
-          {date ? date.toLocaleDateString() : "Pick a date"}
-        </Button>
+      <Popover.Trigger
+        render={<Button variant="outline" icon={CalendarDotsIcon} />}
+      >
+        {date ? date.toLocaleDateString() : "Pick a date"}
       </Popover.Trigger>
       <Popover.Content className="p-3">
         <DatePicker mode="single" selected={date} onChange={setDate} />
@@ -1973,10 +2422,10 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button variant="outline" icon={CalendarDotsIcon}>
-          {formatRange()}
-        </Button>
+      <Popover.Trigger
+        render={<Button variant="outline" icon={CalendarDotsIcon} />}
+      >
+        {formatRange()}
       </Popover.Trigger>
       <Popover.Content className="p-3">
         <DatePicker
@@ -1991,14 +2440,14 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button variant="outline" icon={CalendarDotsIcon}>
-          {formatRange()}
-        </Button>
+      <Popover.Trigger
+        render={<Button variant="outline" icon={CalendarDotsIcon} />}
+      >
+        {formatRange()}
       </Popover.Trigger>
       <Popover.Content className="p-0">
         <div className="flex">
-          <div className="flex flex-col gap-1 border-r border-kumo-line p-2 text-sm">
+          <div className="flex flex-col gap-1 border-r border-kumo-hairline p-2 text-sm">
             {presets.map((preset) => {
               const isActive = isPresetActive(preset);
               return (
@@ -2006,10 +2455,11 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
                   key={preset.label}
                   type="button"
                   onClick={() => handlePresetClick(preset)}
-                  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"
-                    }`}
+                  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"
+                  }`}
                 >
                   {preset.label}
                 </button>
@@ -2080,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-strong`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -2144,7 +2594,7 @@ Dialog component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-recessed`, `text-kumo-default`
+`bg-kumo-base`, `bg-kumo-recessed`, `ring-kumo-line`, `text-kumo-default`
 
 **Styling:**
 
@@ -2460,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-line`, `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:**
 
@@ -2726,7 +3176,7 @@ Responsive CSS grid layout container with preset column configurations.
 
 **Colors (kumo tokens used):**
 
-`border-kumo-line`
+`border-kumo-hairline`
 
 **Examples:**
 
@@ -3007,13 +3457,13 @@ Input component
 
   **State Classes:**
   - `"default"`:
-    - `focus`: `focus:ring-kumo-hairline`
+    - `focus`: `focus:ring-kumo-focus/50 focus:ring-[1.5px]`
   - `"error"`:
-    - `focus`: `focus:ring-kumo-danger`
+    - `focus`: `focus:ring-kumo-danger/50 focus:ring-[1.5px]`
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-control`, `ring-kumo-danger`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-control`, `ring-kumo-danger`, `ring-kumo-focus`, `ring-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -3102,6 +3552,386 @@ Input component
     />
 ```
 
+```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
+
+Addon sub-component
+
+Props:
+- `align`: "start" | "end" [default: "start"] - Position relative to the input.
+- `className`: string - Additional CSS classes.
+
+#### InputGroup.Suffix
+
+Suffix sub-component
+
+Props:
+- `className`: string - Additional CSS classes.
+
+#### InputGroup.Label
+
+Label sub-component
+
+#### InputGroup.Description
+
+Description sub-component
+
+
+**Examples:**
+
+```tsx
+<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
+<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">
+      <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
+<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
+<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
+<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
+<InputGroup className="w-full max-w-3xs">
+      <InputGroup.Input defaultValue="kumo" aria-label="kumo" />
+      <InputGroup.Addon align="end">
+        <Loader />
+      </InputGroup.Addon>
+    </InputGroup>
+```
+
+```tsx
+<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
+<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
+<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>
+```
+
 
 ---
 
@@ -3201,13 +4031,19 @@ LayerCard component
 
 **Props:**
 
+- `render`: ReactNode
+  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
 - `className`: string
-  Additional CSS classes merged via `cn()`.
+- `id`: string
+- `lang`: string
+- `title`: string
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `ring-kumo-fill`, `ring-kumo-line`, `text-kumo-strong`
+`bg-kumo-base`, `bg-kumo-elevated`, `ring-kumo-fill`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-strong`
 
 **Styling:**
 
@@ -3307,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.
 
@@ -3453,7 +4289,7 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-recessed`, `border-kumo-fill`, `border-kumo-recessed`
+`bg-kumo-base`, `bg-kumo-recessed`, `border-kumo-recessed`, `ring-kumo-brand`, `ring-kumo-focus`, `ring-kumo-line`
 
 **Styling:**
 
@@ -3564,6 +4400,12 @@ Pagination component
   Total number of items across all pages.
 - `className`: string
   Additional CSS classes for the container
+- `labels`: PaginationLabels
+  Labels for internationalization of aria-labels. All labels have English defaults.
+
+For visible text like "Showing X of Y", use render props on sub-components:
+- `Pagination.Info` children for the info text
+- `Pagination.PageSize` label prop for the "Per page:" text
 - `children`: ReactNode
   Compound component children for custom layouts. Use Pagination.Info, Pagination.PageSize, Pagination.Controls, and Pagination.Separator.
 - `controls`: enum [default: full]
@@ -3573,7 +4415,7 @@ Pagination component
 
 **Colors (kumo tokens used):**
 
-`border-kumo-line`, `ring-kumo-line`, `text-kumo-strong`
+`border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-strong`
 
 **Styling:**
 
@@ -3600,6 +4442,7 @@ PageSize sub-component
 Props:
 - `value`: number (required)
 - `options`: number[]
+- `page`: " (required)
 - `label`: ReactNode
 - `className`: string
 
@@ -3731,6 +4574,34 @@ Props:
     </Pagination>
 ```
 
+```tsx
+<Pagination
+      page={page}
+      setPage={setPage}
+      perPage={10}
+      totalCount={100}
+      labels={{
+        firstPage: "Première page",
+        previousPage: "Page précédente",
+        nextPage: "Page suivante",
+        lastPage: "Dernière page",
+        pageNumber: "Numéro de page",
+        pageSize: "Taille de page",
+      }}
+    >
+      <Pagination.Info>
+        {({ pageShowingRange, totalCount }) => (
+          <>
+            Affichage de{" "}
+            <span className="tabular-nums">{pageShowingRange}</span> sur{" "}
+            <span className="tabular-nums">{totalCount}</span>
+          </>
+        )}
+      </Pagination.Info>
+      <Pagination.Controls />
+    </Pagination>
+```
+
 
 ---
 
@@ -3785,9 +4656,11 @@ Close sub-component
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button shape="square" icon={BellIcon} aria-label="Notifications" />
-      </Popover.Trigger>
+      <Popover.Trigger
+        render={
+          <Button shape="square" icon={BellIcon} aria-label="Notifications" />
+        }
+      />
       <Popover.Content>
         <Popover.Title>Notifications</Popover.Title>
         <Popover.Description>
@@ -3799,9 +4672,7 @@ Close sub-component
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button>Open Popover</Button>
-      </Popover.Trigger>
+      <Popover.Trigger render={<Button />}>Open Popover</Popover.Trigger>
       <Popover.Content>
         <Popover.Title>Popover Title</Popover.Title>
         <Popover.Description>
@@ -3813,19 +4684,15 @@ Close sub-component
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button>Open Settings</Button>
-      </Popover.Trigger>
+      <Popover.Trigger render={<Button />}>Open Settings</Popover.Trigger>
       <Popover.Content>
         <Popover.Title>Settings</Popover.Title>
         <Popover.Description>
           Configure your preferences below.
         </Popover.Description>
         <div className="mt-3">
-          <Popover.Close asChild>
-            <Button variant="secondary" size="sm">
-              Close
-            </Button>
+          <Popover.Close render={<Button variant="secondary" size="sm" />}>
+            Close
           </Popover.Close>
         </div>
       </Popover.Content>
@@ -3835,8 +4702,8 @@ Close sub-component
 ```tsx
 <div className="flex flex-wrap gap-4">
       <Popover>
-        <Popover.Trigger asChild>
-          <Button variant="secondary">Bottom</Button>
+        <Popover.Trigger render={<Button variant="secondary" />}>
+          Bottom
         </Popover.Trigger>
         <Popover.Content side="bottom">
           <Popover.Title>Bottom</Popover.Title>
@@ -3847,8 +4714,8 @@ Close sub-component
       </Popover>
 
       <Popover>
-        <Popover.Trigger asChild>
-          <Button variant="secondary">Top</Button>
+        <Popover.Trigger render={<Button variant="secondary" />}>
+          Top
         </Popover.Trigger>
         <Popover.Content side="top">
           <Popover.Title>Top</Popover.Title>
@@ -3857,8 +4724,8 @@ Close sub-component
       </Popover>
 
       <Popover>
-        <Popover.Trigger asChild>
-          <Button variant="secondary">Left</Button>
+        <Popover.Trigger render={<Button variant="secondary" />}>
+          Left
         </Popover.Trigger>
         <Popover.Content side="left">
           <Popover.Title>Left</Popover.Title>
@@ -3867,8 +4734,8 @@ Close sub-component
       </Popover>
 
       <Popover>
-        <Popover.Trigger asChild>
-          <Button variant="secondary">Right</Button>
+        <Popover.Trigger render={<Button variant="secondary" />}>
+          Right
         </Popover.Trigger>
         <Popover.Content side="right">
           <Popover.Title>Right</Popover.Title>
@@ -3880,9 +4747,7 @@ Close sub-component
 
 ```tsx
 <Popover>
-      <Popover.Trigger asChild>
-        <Button>User Profile</Button>
-      </Popover.Trigger>
+      <Popover.Trigger render={<Button />}>User Profile</Popover.Trigger>
       <Popover.Content className="w-64">
         <div className="flex items-center gap-3">
           <div className="size-10 rounded-full bg-kumo-recessed" />
@@ -3891,14 +4756,14 @@ Close sub-component
             <p className="text-sm text-kumo-subtle">jane@example.com</p>
           </div>
         </div>
-        <div className="mt-3 flex gap-2 border-t border-kumo-line pt-3">
+        <div className="mt-3 flex gap-2 border-t border-kumo-hairline pt-3">
           <Button variant="secondary" size="sm" className="flex-1">
             Profile
           </Button>
-          <Popover.Close asChild>
-            <Button variant="ghost" size="sm" className="flex-1">
-              Sign Out
-            </Button>
+          <Popover.Close
+            render={<Button variant="ghost" size="sm" className="flex-1" />}
+          >
+            Sign Out
           </Popover.Close>
         </div>
       </Popover.Content>
@@ -3907,8 +4772,12 @@ Close sub-component
 
 ```tsx
 <Popover>
-      <Popover.Trigger openOnHover delay={200} asChild>
-        <Button variant="secondary">Hover Me</Button>
+      <Popover.Trigger
+        openOnHover
+        delay={200}
+        render={<Button variant="secondary" />}
+      >
+        Hover Me
       </Popover.Trigger>
       <Popover.Content>
         <Popover.Title>Hover Triggered</Popover.Title>
@@ -3917,22 +4786,85 @@ Close sub-component
           interactive content like buttons and links.
         </Popover.Description>
         <div className="mt-3">
-          <Popover.Close asChild>
-            <Button variant="secondary" size="sm">
-              Got it
-            </Button>
+          <Popover.Close render={<Button variant="secondary" size="sm" />}>
+            Got it
           </Popover.Close>
         </div>
       </Popover.Content>
     </Popover>
 ```
 
-
----
-
+```tsx
+<div className="w-full">
+      <div className="overflow-hidden rounded-lg border border-kumo-hairline">
+        <table className="w-full text-sm">
+          <thead className="bg-kumo-elevated">
+            <tr>
+              <th className="px-4 py-2 text-left font-medium">Name</th>
+              <th className="px-4 py-2 text-left font-medium">Status</th>
+              <th className="w-12 px-4 py-2"></th>
+            </tr>
+          </thead>
+          <tbody className="divide-y divide-kumo-hairline">
+            {rows.map((row) => (
+              <tr
+                key={row.id}
+                ref={(el) => {
+                  if (el) rowRefs.current.set(row.id, el);
+                }}
+                className={
+                  selectedRow === row.id ? "bg-kumo-recessed" : "bg-kumo-base"
+                }
+              >
+                <td className="px-4 py-2 font-mono">{row.name}</td>
+                <td className="px-4 py-2 text-kumo-subtle">{row.status}</td>
+                <td className="px-4 py-2">
+                  <Button
+                    size="xs"
+                    variant="ghost"
+                    shape="square"
+                    icon={DotsThree}
+                    aria-label={`Actions for ${row.name}`}
+                    onClick={() => handleEdit(row.id)}
+                  />
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      <Popover
+        open={!!selectedRow}
+        onOpenChange={(open) => !open && setSelectedRow(null)}
+      >
+        <Popover.Content
+          side="left"
+          anchor={
+            anchorRect ? { getBoundingClientRect: () => anchorRect } : undefined
+          }
+        >
+          <Popover.Title>
+            Edit {rows.find((r) => r.id === selectedRow)?.name}
+          </Popover.Title>
+          <Popover.Description>
+            The popover anchors to the selected row, not the icon button.
+          </Popover.Description>
+          <div className="mt-3">
+            <Popover.Close render={<Button size="sm" variant="secondary" />}>
+              Close
+            </Popover.Close>
+          </div>
+        </Popover.Content>
+      </Popover>
+    </div>
+```
+
+
+---
+
 ### 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
 
@@ -3942,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]
@@ -3964,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
@@ -3972,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`, `ring-kumo-line`, `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:**
 
@@ -3987,7 +4919,7 @@ Item sub-component
 Group sub-component
 
 Props:
-- `legend`: string (required)
+- `legend`: string
 - `children`: ReactNode (required)
 - `orientation`: "vertical" | "horizontal"
 - `appearance`: KumoRadioAppearance
@@ -3995,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:**
 
@@ -4156,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"
@@ -4204,6 +5213,8 @@ Select component
 
 - `className`: string
   Additional CSS classes merged via `cn()`.
+- `size`: enum [default: base]
+  Size of the select trigger. Matches Input component sizes.
 - `label`: ReactNode
   Label content for the select. When provided, enables the Field wrapper with a visible label above the select. For accessibility without a visible label, use `aria-label` instead.
 - `hideLabel`: boolean
@@ -4232,7 +5243,7 @@ Select component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-line`, `bg-kumo-tint`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `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:**
 
@@ -4270,6 +5281,51 @@ Separator sub-component
     />
 ```
 
+```tsx
+<div className="grid gap-4">
+      <div className="flex items-center gap-3">
+        <span className="w-10 text-sm text-kumo-subtle">xs</span>
+        <Select
+          aria-label="Select size xs"
+          size="xs"
+          className="w-[200px]"
+          placeholder="Choose..."
+          items={{ a: "Option A", b: "Option B" }}
+        />
+      </div>
+      <div className="flex items-center gap-3">
+        <span className="w-10 text-sm text-kumo-subtle">sm</span>
+        <Select
+          aria-label="Select size sm"
+          size="sm"
+          className="w-[200px]"
+          placeholder="Choose..."
+          items={{ a: "Option A", b: "Option B" }}
+        />
+      </div>
+      <div className="flex items-center gap-3">
+        <span className="w-10 text-sm text-kumo-subtle">base</span>
+        <Select
+          aria-label="Select size base"
+          size="base"
+          className="w-[200px]"
+          placeholder="Choose..."
+          items={{ a: "Option A", b: "Option B" }}
+        />
+      </div>
+      <div className="flex items-center gap-3">
+        <span className="w-10 text-sm text-kumo-subtle">lg</span>
+        <Select
+          aria-label="Select size lg"
+          size="lg"
+          className="w-[200px]"
+          placeholder="Choose..."
+          items={{ a: "Option A", b: "Option B" }}
+        />
+      </div>
+    </div>
+```
+
 ```tsx
 <Select
       label="Issue Type"
@@ -4432,13 +5488,12 @@ Separator sub-component
 <Select
       label="Author"
       description="Select the primary author for this document"
+      placeholder="Select an author"
       className="w-[200px]"
       onValueChange={(v) => setValue(v as (typeof authors)[0] | null)}
       value={value}
       isItemEqualToValue={(item, value) => item?.id === value?.id}
-      renderValue={(author) => {
-        return author?.name ?? "Select an author";
-      }}
+      renderValue={(author) => author.name}
     >
       {authors.map((author) => (
         <Select.Option key={author.id} value={author}>
@@ -4457,16 +5512,18 @@ Separator sub-component
       placeholder="Choose a region..."
       className="w-[250px]"
       value={value}
-      onValueChange={(v) => setValue(v as string | null)}
+      onValueChange={(v) => setValue(v as Region | null)}
+      isItemEqualToValue={(item, val) => item.value === val.value}
     >
-      <Select.Option value="us-east">US East</Select.Option>
-      <Select.Option value="us-west">US West</Select.Option>
-      <Select.Option value="eu-west" disabled>
-        EU West
-      </Select.Option>
-      <Select.Option value="ap-south" disabled>
-        AP South
-      </Select.Option>
+      {regions.map((region) => (
+        <Select.Option
+          key={region.value}
+          value={region}
+          disabled={region.disabled}
+        >
+          {region.label}
+        </Select.Option>
+      ))}
     </Select>
 ```
 
@@ -4476,47 +5533,25 @@ Separator sub-component
       placeholder="Pick a food..."
       className="w-[220px]"
       value={value}
-      onValueChange={(v) => setValue(v as string | null)}
+      onValueChange={(v) => setValue(v as Food | null)}
+      isItemEqualToValue={(item, val) => item.value === val.value}
     >
       <Select.Group>
         <Select.GroupLabel>Fruits</Select.GroupLabel>
-        <Select.Option value="apple">Apple</Select.Option>
-        <Select.Option value="banana">Banana</Select.Option>
-        <Select.Option value="cherry">Cherry</Select.Option>
+        {foods.fruits.map((food) => (
+          <Select.Option key={food.value} value={food}>
+            {food.label}
+          </Select.Option>
+        ))}
       </Select.Group>
       <Select.Separator />
       <Select.Group>
         <Select.GroupLabel>Vegetables</Select.GroupLabel>
-        <Select.Option value="carrot">Carrot</Select.Option>
-        <Select.Option value="broccoli">Broccoli</Select.Option>
-        <Select.Option value="spinach">Spinach</Select.Option>
-      </Select.Group>
-    </Select>
-```
-
-```tsx
-<Select
-      label="Server Region"
-      placeholder="Select a region..."
-      className="w-[260px]"
-      value={value}
-      onValueChange={(v) => setValue(v as string | null)}
-    >
-      <Select.Group>
-        <Select.GroupLabel>Available</Select.GroupLabel>
-        <Select.Option value="us-east-1">US East (N. Virginia)</Select.Option>
-        <Select.Option value="us-west-2">US West (Oregon)</Select.Option>
-        <Select.Option value="eu-west-1">EU West (Ireland)</Select.Option>
-      </Select.Group>
-      <Select.Separator />
-      <Select.Group>
-        <Select.GroupLabel>Unavailable</Select.GroupLabel>
-        <Select.Option value="ap-south-1" disabled>
-          AP South (Mumbai)
-        </Select.Option>
-        <Select.Option value="sa-east-1" disabled>
-          SA East (São Paulo)
-        </Select.Option>
+        {foods.vegetables.map((food) => (
+          <Select.Option key={food.value} value={food}>
+            {food.label}
+          </Select.Option>
+        ))}
       </Select.Group>
     </Select>
 ```
@@ -4528,10 +5563,11 @@ Separator sub-component
       placeholder="Choose an option..."
       className="w-[220px]"
       value={value}
-      onValueChange={(v) => setValue(v as string | null)}
+      onValueChange={(v) => setValue(v as LongListItem | null)}
+      isItemEqualToValue={(item, val) => item.value === val.value}
     >
       {longListItems.map((item) => (
-        <Select.Option key={item.value} value={item.value}>
+        <Select.Option key={item.value} value={item}>
           {item.label}
         </Select.Option>
       ))}
@@ -4592,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:**
 
@@ -4709,7 +5745,7 @@ Sidebar — responsive navigation panel with expand/collapse support.  Compound
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-line`, `bg-kumo-overlay`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-line`, `ring-kumo-hairline`, `ring-kumo-line`, `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-strong`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -4739,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
@@ -4815,6 +5914,9 @@ ResizeHandle sub-component
 
 MenuChevron sub-component
 
+Props:
+- `className`: string
+
 #### Sidebar.Collapsible
 
 Collapsible sub-component
@@ -5144,7 +6246,7 @@ CollapsibleContent sub-component
 
 ### Surface
 
-Polymorphic container with consistent background, shadow, and border styling.  Use the `render` prop to change the underlying element: ```tsx <Surface render={<section />} className="rounded-lg p-4">Card content</Surface> ```
+Surface component
 
 **Type:** component
 
@@ -5156,7 +6258,7 @@ Polymorphic container with consistent background, shadow, and border styling.  U
 
 - `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
@@ -5165,49 +6267,6 @@ Accepts a `ReactElement` or a function that returns the element to render.
 - `lang`: string
 - `title`: string
 
-**Colors (kumo tokens used):**
-
-`bg-kumo-base`, `ring-kumo-line`
-
-**Examples:**
-
-```tsx
-<Surface className="rounded-lg p-6">
-      <Text size="lg" bold>
-        Surface Component
-      </Text>
-      <div className="mt-2">
-        <Text variant="secondary">
-          A container with consistent elevation and border styling.
-        </Text>
-      </div>
-    </Surface>
-```
-
-```tsx
-<div className="flex flex-col gap-4">
-      <Surface render={<section />} className="rounded-lg p-4">
-        <Text bold>As section element</Text>
-      </Surface>
-      <Surface render={<article />} className="rounded-lg p-4">
-        <Text bold>As article element</Text>
-      </Surface>
-      <Surface render={<aside />} className="rounded-lg p-4">
-        <Text bold>As aside element</Text>
-      </Surface>
-    </div>
-```
-
-```tsx
-<Surface className="rounded-lg p-6">
-      <Text bold>Outer Surface</Text>
-      <Surface className="mt-4 rounded-md bg-kumo-elevated p-4">
-        <Text variant="secondary">Nested Surface</Text>
-      </Surface>
-    </Surface>
-```
-
-
 ---
 
 ### Switch
@@ -5252,7 +6311,7 @@ Switch component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `border-kumo-line`, `ring-kumo-line`, `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:**
 
@@ -5267,7 +6326,7 @@ Item sub-component
 Group sub-component
 
 Props:
-- `legend`: string (required)
+- `legend`: string
 - `children`: ReactNode (required)
 - `error`: string
 - `description`: ReactNode
@@ -5275,6 +6334,14 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+#### Switch.Legend
+
+Legend sub-component
+
+Props:
+- `children`: ReactNode (required)
+- `className`: string
+
 
 **Examples:**
 
@@ -5346,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
@@ -5400,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:**
 
@@ -5446,326 +6530,553 @@ ResizeHandle sub-component
 **Examples:**
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="p-0">
-        <Table>
-          <Table.Header>
-            <Table.Row>
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
+<LayerCard className="p-0">
+      <Table>
+        <Table.Header>
+          <Table.Row>
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.slice(0, 3).map((row) => (
+            <Table.Row key={row.id}>
+              <Table.Cell>{row.subject}</Table.Cell>
+              <Table.Cell>{row.from}</Table.Cell>
+              <Table.Cell>{row.date}</Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {emailData.slice(0, 3).map((row) => (
-              <Table.Row key={row.id}>
-                <Table.Cell>{row.subject}</Table.Cell>
-                <Table.Cell>{row.from}</Table.Cell>
-                <Table.Cell>{row.date}</Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="p-0">
-        <Table>
-          <Table.Header>
-            <Table.Row>
-              <Table.CheckHead
-                checked={selectedIds.size === rows.length}
-                indeterminate={
-                  selectedIds.size > 0 && selectedIds.size < rows.length
-                }
-                onValueChange={toggleAll}
-                aria-label="Select all rows"
+<LayerCard className="p-0">
+      <Table>
+        <Table.Header>
+          <Table.Row>
+            <Table.CheckHead
+              checked={selectedIds.size === rows.length}
+              indeterminate={
+                selectedIds.size > 0 && selectedIds.size < rows.length
+              }
+              onCheckedChange={toggleAll}
+              aria-label="Select all rows"
+            />
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {rows.map((row) => (
+            <Table.Row key={row.id}>
+              <Table.CheckCell
+                checked={selectedIds.has(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
+                aria-label={`Select ${row.subject}`}
               />
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
+              <Table.Cell>{row.subject}</Table.Cell>
+              <Table.Cell>{row.from}</Table.Cell>
+              <Table.Cell>{row.date}</Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {rows.map((row) => (
-              <Table.Row key={row.id}>
-                <Table.CheckCell
-                  checked={selectedIds.has(row.id)}
-                  onValueChange={() => toggleRow(row.id)}
-                  aria-label={`Select ${row.subject}`}
-                />
-                <Table.Cell>{row.subject}</Table.Cell>
-                <Table.Cell>{row.from}</Table.Cell>
-                <Table.Cell>{row.date}</Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="p-0">
-        <Table>
-          <Table.Header variant="compact">
-            <Table.Row>
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
+<LayerCard className="p-0">
+      <Table>
+        <Table.Header variant="compact">
+          <Table.Row>
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.slice(0, 3).map((row) => (
+            <Table.Row key={row.id}>
+              <Table.Cell>{row.subject}</Table.Cell>
+              <Table.Cell>{row.from}</Table.Cell>
+              <Table.Cell>{row.date}</Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {emailData.slice(0, 3).map((row) => (
-              <Table.Row key={row.id}>
-                <Table.Cell>{row.subject}</Table.Cell>
-                <Table.Cell>{row.from}</Table.Cell>
-                <Table.Cell>{row.date}</Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="p-0">
-        <Table>
-          <Table.Header>
-            <Table.Row>
-              <Table.CheckHead
-                checked={selectedIds.size === rows.length}
-                indeterminate={
-                  selectedIds.size > 0 && selectedIds.size < rows.length
-                }
-                onValueChange={toggleAll}
-                aria-label="Select all rows"
+<LayerCard className="p-0">
+      <Table>
+        <Table.Header>
+          <Table.Row>
+            <Table.CheckHead
+              checked={selectedIds.size === rows.length}
+              indeterminate={
+                selectedIds.size > 0 && selectedIds.size < rows.length
+              }
+              onCheckedChange={toggleAll}
+              aria-label="Select all rows"
+            />
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {rows.map((row) => (
+            <Table.Row
+              key={row.id}
+              variant={selectedIds.has(row.id) ? "selected" : "default"}
+            >
+              <Table.CheckCell
+                checked={selectedIds.has(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
+                aria-label={`Select ${row.subject}`}
               />
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
+              <Table.Cell>{row.subject}</Table.Cell>
+              <Table.Cell>{row.from}</Table.Cell>
+              <Table.Cell>{row.date}</Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {rows.map((row) => (
-              <Table.Row
-                key={row.id}
-                variant={selectedIds.has(row.id) ? "selected" : "default"}
-              >
-                <Table.CheckCell
-                  checked={selectedIds.has(row.id)}
-                  onValueChange={() => toggleRow(row.id)}
-                  aria-label={`Select ${row.subject}`}
-                />
-                <Table.Cell>{row.subject}</Table.Cell>
-                <Table.Cell>{row.from}</Table.Cell>
-                <Table.Cell>{row.date}</Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="p-0">
-        <Table layout="fixed">
-          <colgroup>
-            <col />
-            <col className="w-[150px]" />
-            <col className="w-[150px]" />
-          </colgroup>
-          <Table.Header>
-            <Table.Row>
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
+<LayerCard className="p-0">
+      <Table layout="fixed">
+        <colgroup>
+          <col />
+          <col className="w-[150px]" />
+          <col className="w-[150px]" />
+        </colgroup>
+        <Table.Header>
+          <Table.Row>
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.map((row) => (
+            <Table.Row key={row.id}>
+              <Table.Cell>{row.subject}</Table.Cell>
+              <Table.Cell>{row.from}</Table.Cell>
+              <Table.Cell>{row.date}</Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {emailData.map((row) => (
-              <Table.Row key={row.id}>
-                <Table.Cell>{row.subject}</Table.Cell>
-                <Table.Cell>{row.from}</Table.Cell>
-                <Table.Cell>{row.date}</Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="w-full max-w-md overflow-x-auto p-0">
-        <Table>
-          <Table.Header>
-            <Table.Row>
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
-              <Table.Head>Tags</Table.Head>
-              <Table.Head sticky="right">
-                <span className="sr-only">Actions</span>
-              </Table.Head>
+<LayerCard className="w-full max-w-md overflow-x-auto p-0">
+      <Table>
+        <Table.Header variant="compact">
+          <Table.Row>
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+            <Table.Head>Tags</Table.Head>
+            <Table.Head sticky="right">
+              <span className="sr-only">Actions</span>
+            </Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.map((row) => (
+            <Table.Row key={row.id}>
+              <Table.Cell className="whitespace-nowrap">
+                {row.subject}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.from}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.date}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.tags ? (
+                  <div className="inline-flex gap-1">
+                    {row.tags.map((tag) => (
+                      <Badge key={tag}>{tag}</Badge>
+                    ))}
+                  </div>
+                ) : (
+                  "—"
+                )}
+              </Table.Cell>
+              <Table.Cell sticky="right" className="text-right">
+                <DropdownMenu>
+                  <DropdownMenu.Trigger
+                    render={
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        shape="square"
+                        aria-label="More options"
+                      >
+                        <DotsThree weight="bold" size={16} />
+                      </Button>
+                    }
+                  />
+                  <DropdownMenu.Content>
+                    <DropdownMenu.Item icon={Eye}>View</DropdownMenu.Item>
+                    <DropdownMenu.Item icon={PencilSimple}>
+                      Edit
+                    </DropdownMenu.Item>
+                    <DropdownMenu.Separator />
+                    <DropdownMenu.Item icon={Trash} variant="danger">
+                      Delete
+                    </DropdownMenu.Item>
+                  </DropdownMenu.Content>
+                </DropdownMenu>
+              </Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table>
+    </LayerCard>
+```
+
+```tsx
+<LayerCard className="w-full max-w-md overflow-x-auto p-0">
+      <Table>
+        <Table.Header>
+          <Table.Row>
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+            <Table.Head>Tags</Table.Head>
+            <Table.Head sticky="right">
+              <span className="sr-only">Actions</span>
+            </Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.map((row) => (
+            <Table.Row key={row.id}>
+              <Table.Cell className="whitespace-nowrap">
+                {row.subject}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.from}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.date}
+              </Table.Cell>
+              <Table.Cell className="whitespace-nowrap">
+                {row.tags ? (
+                  <div className="inline-flex gap-1">
+                    {row.tags.map((tag) => (
+                      <Badge key={tag}>{tag}</Badge>
+                    ))}
+                  </div>
+                ) : (
+                  "—"
+                )}
+              </Table.Cell>
+              <Table.Cell sticky="right" className="text-right">
+                <DropdownMenu>
+                  <DropdownMenu.Trigger
+                    render={
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        shape="square"
+                        aria-label="More options"
+                      >
+                        <DotsThree weight="bold" size={16} />
+                      </Button>
+                    }
+                  />
+                  <DropdownMenu.Content>
+                    <DropdownMenu.Item icon={Eye}>View</DropdownMenu.Item>
+                    <DropdownMenu.Item icon={PencilSimple}>
+                      Edit
+                    </DropdownMenu.Item>
+                    <DropdownMenu.Separator />
+                    <DropdownMenu.Item icon={Trash} variant="danger">
+                      Delete
+                    </DropdownMenu.Item>
+                  </DropdownMenu.Content>
+                </DropdownMenu>
+              </Table.Cell>
             </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {emailData.map((row) => (
-              <Table.Row key={row.id}>
-                <Table.Cell className="whitespace-nowrap">
-                  {row.subject}
-                </Table.Cell>
-                <Table.Cell className="whitespace-nowrap">
-                  {row.from}
-                </Table.Cell>
-                <Table.Cell className="whitespace-nowrap">
-                  {row.date}
-                </Table.Cell>
-                <Table.Cell className="whitespace-nowrap">
-                  {row.tags ? (
-                    <div className="inline-flex gap-1">
+          ))}
+        </Table.Body>
+      </Table>
+    </LayerCard>
+```
+
+```tsx
+<LayerCard className="w-full overflow-x-auto p-0">
+      <Table layout="fixed">
+        <colgroup>
+          <col />{" "}
+          {/* Checkbox column - width handled by Table.CheckHead/CheckCell */}
+          <col />
+          <col style={{ width: "150px" }} />
+          <col style={{ width: "120px" }} />
+          <col style={{ width: "50px" }} />
+        </colgroup>
+        <Table.Header>
+          <Table.Row>
+            <Table.CheckHead
+              checked={selectedIds.size === emailData.length}
+              indeterminate={
+                selectedIds.size > 0 && selectedIds.size < emailData.length
+              }
+              onCheckedChange={toggleAll}
+              aria-label="Select all rows"
+            />
+            <Table.Head>Subject</Table.Head>
+            <Table.Head>From</Table.Head>
+            <Table.Head>Date</Table.Head>
+            <Table.Head></Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {emailData.map((row) => (
+            <Table.Row
+              key={row.id}
+              variant={selectedIds.has(row.id) ? "selected" : "default"}
+            >
+              <Table.CheckCell
+                checked={selectedIds.has(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
+                aria-label={`Select ${row.subject}`}
+              />
+              <Table.Cell>
+                <div className="flex items-center gap-2">
+                  <EnvelopeSimple size={16} />
+                  <span className="truncate">{row.subject}</span>
+                  {row.tags && (
+                    <div className="ml-2 inline-flex gap-1">
                       {row.tags.map((tag) => (
                         <Badge key={tag}>{tag}</Badge>
                       ))}
                     </div>
-                  ) : (
-                    "—"
                   )}
-                </Table.Cell>
-                <Table.Cell sticky="right" className="text-right">
-                  <DropdownMenu>
-                    <DropdownMenu.Trigger
-                      render={
-                        <Button
-                          variant="ghost"
-                          size="sm"
-                          shape="square"
-                          aria-label="More options"
-                        >
-                          <DotsThree weight="bold" size={16} />
-                        </Button>
-                      }
-                    />
-                    <DropdownMenu.Content>
-                      <DropdownMenu.Item icon={Eye}>View</DropdownMenu.Item>
-                      <DropdownMenu.Item icon={PencilSimple}>
-                        Edit
-                      </DropdownMenu.Item>
-                      <DropdownMenu.Separator />
-                      <DropdownMenu.Item icon={Trash} variant="danger">
-                        Delete
-                      </DropdownMenu.Item>
-                    </DropdownMenu.Content>
-                  </DropdownMenu>
-                </Table.Cell>
-              </Table.Row>
-            ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
+                </div>
+              </Table.Cell>
+              <Table.Cell>
+                <span className="truncate">{row.from}</span>
+              </Table.Cell>
+              <Table.Cell>
+                <span className="truncate">{row.date}</span>
+              </Table.Cell>
+              <Table.Cell className="text-right">
+                <DropdownMenu>
+                  <DropdownMenu.Trigger
+                    render={
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        shape="square"
+                        aria-label="More options"
+                      >
+                        <DotsThree weight="bold" size={16} />
+                      </Button>
+                    }
+                  />
+                  <DropdownMenu.Content>
+                    <DropdownMenu.Item icon={Eye}>View</DropdownMenu.Item>
+                    <DropdownMenu.Item icon={PencilSimple}>
+                      Edit
+                    </DropdownMenu.Item>
+                    <DropdownMenu.Separator />
+                    <DropdownMenu.Item icon={Trash} variant="danger">
+                      Delete
+                    </DropdownMenu.Item>
+                  </DropdownMenu.Content>
+                </DropdownMenu>
+              </Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table>
     </LayerCard>
 ```
 
+
+---
+
+### TableOfContents
+
+TableOfContents — presentational compound component for section navigation.  Purely visual; all interaction logic (scroll tracking, active state management) is left to the consumer.
+
+**Type:** component
+
+**Import:** `import { TableOfContents } from "@cloudflare/kumo";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (kumo tokens used):**
+
+`border-kumo-brand`, `border-kumo-hairline`, `border-kumo-line`, `text-kumo-default`, `text-kumo-subtle`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### TableOfContents.Title
+
+Title sub-component
+
+#### TableOfContents.List
+
+List sub-component
+
+#### TableOfContents.Item
+
+Item sub-component
+
+Props:
+- `active`: boolean
+
+#### TableOfContents.Group
+
+Group sub-component
+
+Props:
+- `label`: string (required)
+- `href`: string
+- `active`: boolean
+
+
+**Examples:**
+
 ```tsx
-<LayerCard>
-      <LayerCard.Primary className="w-full overflow-x-auto p-0">
-        <Table layout="fixed">
-          <colgroup>
-            <col />{" "}
-            {/* Checkbox column - width handled by Table.CheckHead/CheckCell */}
-            <col />
-            <col style={{ width: "150px" }} />
-            <col style={{ width: "120px" }} />
-            <col style={{ width: "50px" }} />
-          </colgroup>
-          <Table.Header>
-            <Table.Row>
-              <Table.CheckHead
-                checked={selectedIds.size === emailData.length}
-                indeterminate={
-                  selectedIds.size > 0 && selectedIds.size < emailData.length
-                }
-                onValueChange={toggleAll}
-                aria-label="Select all rows"
-              />
-              <Table.Head>Subject</Table.Head>
-              <Table.Head>From</Table.Head>
-              <Table.Head>Date</Table.Head>
-              <Table.Head></Table.Head>
-            </Table.Row>
-          </Table.Header>
-          <Table.Body>
-            {emailData.map((row) => (
-              <Table.Row
-                key={row.id}
-                variant={selectedIds.has(row.id) ? "selected" : "default"}
+<DemoWrapper>
+      <TableOfContents>
+        <TableOfContents.Title>On this page</TableOfContents.Title>
+        <TableOfContents.List>
+          {headings.map((heading) => (
+            <TableOfContents.Item
+              key={heading.text}
+              active={heading.text === "Usage"}
+              className="cursor-pointer"
+            >
+              {heading.text}
+            </TableOfContents.Item>
+          ))}
+        </TableOfContents.List>
+      </TableOfContents>
+    </DemoWrapper>
+```
+
+```tsx
+<DemoWrapper>
+      <TableOfContents>
+        <TableOfContents.Title>On this page</TableOfContents.Title>
+        <TableOfContents.List>
+          {headings.map((heading) => (
+            <TableOfContents.Item
+              key={heading.text}
+              active={heading.text === active}
+              onClick={() => setActive(heading.text)}
+              className="cursor-pointer"
+            >
+              {heading.text}
+            </TableOfContents.Item>
+          ))}
+        </TableOfContents.List>
+      </TableOfContents>
+    </DemoWrapper>
+```
+
+```tsx
+<DemoWrapper>
+      <TableOfContents>
+        <TableOfContents.Title>On this page</TableOfContents.Title>
+        <TableOfContents.List>
+          {headings.map((heading) => (
+            <TableOfContents.Item key={heading.text} className="cursor-pointer">
+              {heading.text}
+            </TableOfContents.Item>
+          ))}
+        </TableOfContents.List>
+      </TableOfContents>
+    </DemoWrapper>
+```
+
+```tsx
+<DemoWrapper>
+      <TableOfContents>
+        <TableOfContents.Title>On this page</TableOfContents.Title>
+        <TableOfContents.List>
+          <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
+            </TableOfContents.Item>
+            <TableOfContents.Item className="cursor-pointer">
+              Configuration
+            </TableOfContents.Item>
+          </TableOfContents.Group>
+          <TableOfContents.Group label="API" href="#api-demo">
+            <TableOfContents.Item className="cursor-pointer">
+              Props
+            </TableOfContents.Item>
+            <TableOfContents.Item className="cursor-pointer">
+              Events
+            </TableOfContents.Item>
+          </TableOfContents.Group>
+        </TableOfContents.List>
+      </TableOfContents>
+    </DemoWrapper>
+```
+
+```tsx
+<DemoWrapper>
+      <div className="space-y-3">
+        <TableOfContents>
+          <TableOfContents.List>
+            {["Introduction", "Installation", "Usage"].map((text) => (
+              <TableOfContents.Item
+                key={text}
+                render={<button type="button" />}
+                onClick={() => setClicked(text)}
+                active={text === "Introduction"}
               >
-                <Table.CheckCell
-                  checked={selectedIds.has(row.id)}
-                  onValueChange={() => toggleRow(row.id)}
-                  aria-label={`Select ${row.subject}`}
-                />
-                <Table.Cell>
-                  <div className="flex items-center gap-2">
-                    <EnvelopeSimple size={16} />
-                    <span className="truncate">{row.subject}</span>
-                    {row.tags && (
-                      <div className="ml-2 inline-flex gap-1">
-                        {row.tags.map((tag) => (
-                          <Badge key={tag}>{tag}</Badge>
-                        ))}
-                      </div>
-                    )}
-                  </div>
-                </Table.Cell>
-                <Table.Cell>
-                  <span className="truncate">{row.from}</span>
-                </Table.Cell>
-                <Table.Cell>
-                  <span className="truncate">{row.date}</span>
-                </Table.Cell>
-                <Table.Cell className="text-right">
-                  <DropdownMenu>
-                    <DropdownMenu.Trigger
-                      render={
-                        <Button
-                          variant="ghost"
-                          size="sm"
-                          shape="square"
-                          aria-label="More options"
-                        >
-                          <DotsThree weight="bold" size={16} />
-                        </Button>
-                      }
-                    />
-                    <DropdownMenu.Content>
-                      <DropdownMenu.Item icon={Eye}>View</DropdownMenu.Item>
-                      <DropdownMenu.Item icon={PencilSimple}>
-                        Edit
-                      </DropdownMenu.Item>
-                      <DropdownMenu.Separator />
-                      <DropdownMenu.Item icon={Trash} variant="danger">
-                        Delete
-                      </DropdownMenu.Item>
-                    </DropdownMenu.Content>
-                  </DropdownMenu>
-                </Table.Cell>
-              </Table.Row>
+                {text}
+              </TableOfContents.Item>
             ))}
-          </Table.Body>
-        </Table>
-      </LayerCard.Primary>
-    </LayerCard>
+          </TableOfContents.List>
+        </TableOfContents>
+        {clicked && (
+          <p className="text-xs text-kumo-subtle">Clicked: {clicked}</p>
+        )}
+      </div>
+    </DemoWrapper>
 ```
 
 
@@ -5806,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-strong`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -5943,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.
 
@@ -5959,69 +7273,75 @@ 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-line bg-kumo-base p-4">
-        <Text variant="heading1">Heading 1</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-3xl (30px)</p>
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
+        <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-line bg-kumo-base p-4">
-        <Text variant="heading2">Heading 2</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-2xl (24px)</p>
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
+        <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-line bg-kumo-base p-4">
-        <Text variant="heading3">Heading 3</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-lg (16px)</p>
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
+        <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-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text>Body</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text bold>Body bold</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text size="lg">Body lg</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-lg (16px)</p>
+        <Text variant="mono-secondary">text-lg (16px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text size="sm">Body sm</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-sm (13px)</p>
+        <Text variant="mono-secondary">text-sm (13px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text size="xs">Body xs</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-xs (12px)</p>
+        <Text variant="mono-secondary">text-xs (12px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="secondary">Body secondary</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="mono">Monospace</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-sm (13px)</p>
+        <Text variant="mono-secondary">text-sm (13px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="mono" size="lg">
           Monospace lg
         </Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="mono-secondary">Monospace secondary</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-sm (13px)</p>
+        <Text variant="mono-secondary">text-sm (13px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="success">Success</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
-      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-line bg-kumo-base p-4">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="error">Error</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-base (14px)</p>
+        <Text variant="mono-secondary">text-base (14px)</Text>
       </div>
     </div>
 ```
 
 ```tsx
-<div className="w-64 rounded-lg border border-kumo-line bg-kumo-base p-4">
+<div className="w-64 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
       <Text truncate>
         This is a long piece of text that will be truncated with an ellipsis
         when it overflows its container.
@@ -6057,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-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-strong`, `text-kumo-subtle`, `text-kumo-success`, `text-kumo-warning`
 
 **Styling:**
 
@@ -6096,25 +7416,32 @@ Accessible popup that shows additional information on hover/focus. Wrap your app
 
 ```tsx
 <TooltipProvider>
-      <Tooltip content="Add new item" asChild>
-        <Button shape="square" icon={PlusIcon} aria-label="Add new item" />
-      </Tooltip>
+      <Tooltip
+        content="Add new item"
+        render={
+          <Button shape="square" icon={PlusIcon} aria-label="Add new item" />
+        }
+      />
     </TooltipProvider>
 ```
 
 ```tsx
 <TooltipProvider>
       <div className="flex gap-2">
-        <Tooltip content="Add" asChild>
-          <Button shape="square" icon={PlusIcon} aria-label="Add" />
-        </Tooltip>
-        <Tooltip content="Change language" asChild>
-          <Button
-            shape="square"
-            icon={TranslateIcon}
-            aria-label="Change language"
-          />
-        </Tooltip>
+        <Tooltip
+          content="Add"
+          render={<Button shape="square" icon={PlusIcon} aria-label="Add" />}
+        />
+        <Tooltip
+          content="Change language"
+          render={
+            <Button
+              shape="square"
+              icon={TranslateIcon}
+              aria-label="Change language"
+            />
+          }
+        />
       </div>
     </TooltipProvider>
 ```
@@ -6134,23 +7461,27 @@ Accessible popup that shows additional information on hover/focus. Wrap your app
 ```tsx
 <TooltipProvider>
       <div className="flex gap-4">
-        <Tooltip content="Opens after 1 second" delay={1000} asChild>
-          <Button variant="secondary">1s open delay</Button>
+        <Tooltip
+          content="Opens after 1 second"
+          delay={1000}
+          render={<Button variant="secondary" />}
+        >
+          1s open delay
         </Tooltip>
         <Tooltip
           content="Stays open 500ms after leaving"
           closeDelay={500}
-          asChild
+          render={<Button variant="secondary" />}
         >
-          <Button variant="secondary">500ms close delay</Button>
+          500ms close delay
         </Tooltip>
         <Tooltip
           content="Instant open, stays 1s"
           delay={0}
           closeDelay={1000}
-          asChild
+          render={<Button variant="secondary" />}
         >
-          <Button variant="secondary">Instant + 1s close</Button>
+          Instant + 1s close
         </Tooltip>
       </div>
     </TooltipProvider>
@@ -6183,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, 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