@cloudflare/kumo 1.18.0 → 1.19.0

package/ai/component-registry.md

@@ -383,7 +383,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-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -504,7 +504,7 @@ Checkbox component
 
 **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-contrast`, `ring-kumo-danger`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -638,7 +638,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-hairline`, `outline-kumo-fill`, `text-kumo-default`
 
 **Styling:**
 
@@ -980,7 +980,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 +1108,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>
@@ -1277,7 +1277,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:**
 
@@ -1656,7 +1656,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-hairline`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
 
 **Examples:**
 
@@ -1714,13 +1714,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>
@@ -1857,13 +1857,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>Open in new tab</span>
@@ -1901,11 +1901,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 +1964,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 +1977,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 +1995,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 +2010,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>
@@ -2144,7 +2149,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 +2465,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-line`, `text-kumo-danger`, `text-kumo-default`
 
 **Sub-Components:**
 
@@ -2726,7 +2731,7 @@ Responsive CSS grid layout container with preset column configurations.
 
 **Colors (kumo tokens used):**
 
-`border-kumo-line`
+`border-kumo-hairline`
 
 **Examples:**
 
@@ -3013,7 +3018,7 @@ Input component
 
 **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-hairline`, `text-kumo-default`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -3102,6 +3107,26 @@ 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)}
+    />
+```
+
 
 ---
 
@@ -3201,13 +3226,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:**
 
@@ -3453,7 +3484,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-elevated`, `bg-kumo-recessed`, `border-kumo-recessed`, `ring-kumo-line`
 
 **Styling:**
 
@@ -3564,6 +3595,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 +3610,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 +3637,7 @@ PageSize sub-component
 Props:
 - `value`: number (required)
 - `options`: number[]
+- `page`: " (required)
 - `label`: ReactNode
 - `className`: string
 
@@ -3731,6 +3769,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 +3851,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 +3867,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 +3879,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 +3897,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 +3909,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 +3919,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 +3929,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 +3942,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 +3951,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 +3967,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,16 +3981,79 @@ 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>
+```
+
 
 ---
 
@@ -3972,7 +4099,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-danger`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -4204,6 +4331,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 +4361,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-hairline`, `bg-kumo-tint`, `ring-kumo-hairline`, `ring-kumo-line`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-placeholder`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -4270,6 +4399,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 +4606,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 +4630,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 +4651,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 +4681,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>
       ))}
@@ -4709,7 +4863,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-hairline`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -5144,7 +5298,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
 
@@ -5165,49 +5319,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 +5363,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`, `border-kumo-hairline`, `ring-kumo-hairline`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -5446,326 +5557,537 @@ 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
+              }
+              onValueChange={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)}
+                onValueChange={() => 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
+              }
+              onValueChange={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)}
+                onValueChange={() => 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
+              }
+              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"}
+            >
+              <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>
-                  ) : (
-                    "—"
                   )}
-                </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):**
+
+`bg-kumo-brand`, `bg-kumo-line`, `bg-kumo-tint`, `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
+
+#### TableOfContents.Group
+
+Group sub-component
+
+
+**Examples:**
+
+```tsx
+<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
-<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} 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="Getting Started">
+            <TableOfContents.Item className="cursor-pointer">
+              Installation
+            </TableOfContents.Item>
+            <TableOfContents.Item className="cursor-pointer">
+              Configuration
+            </TableOfContents.Item>
+          </TableOfContents.Group>
+          <TableOfContents.Group label="API">
+            <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>
 ```
 
 
@@ -5959,69 +6281,69 @@ 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">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="heading1">Heading 1</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-3xl (30px)</p>
+        <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">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="heading2">Heading 2</Text>
-        <p className="font-mono text-xs text-kumo-subtle">text-2xl (24px)</p>
+        <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">
+      <div className="flex flex-col justify-end gap-1 rounded-lg border border-kumo-hairline bg-kumo-base p-4">
         <Text variant="heading3">Heading 3</Text>
-        <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>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 +6379,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 +6418,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 +6463,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>
@@ -6187,7 +6520,7 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 - **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
+- **Other:** CloudflareLogo, DatePicker, Label, Link, SensitiveInput, Sidebar, Table, TableOfContents, DeleteResource
 - **Navigation:** CommandPalette, MenuBar, Pagination, Tabs
 - **Overlay:** Dialog, DropdownMenu, Popover, Tooltip
 - **Layout:** Grid, Surface, PageHeader, ResourceListPage