@cloudflare/kumo 1.15.0 → 1.17.0

package/ai/component-registry.md

@@ -16,13 +16,28 @@ Small status label for categorizing or highlighting content.
 
 **Props:**
 
-- `variant`: enum [default: primary]
-  - `"primary"`: Default high-emphasis badge for important labels
-  - `"secondary"`: Subtle badge for secondary information
-  - `"destructive"`: Error or danger state indicator
-  - `"success"`: Success or positive state indicator
+- `variant`: enum [default: neutral]
+  - `"red"`: Red badge
+  - `"red-subtle"`: Subtle red badge
+  - `"orange"`: Orange badge
+  - `"orange-subtle"`: Subtle orange badge
+  - `"yellow"`: Yellow badge
+  - `"yellow-subtle"`: Subtle yellow badge
+  - `"green"`: Green badge
+  - `"green-subtle"`: Subtle green badge
+  - `"teal"`: Teal badge
+  - `"teal-subtle"`: Subtle teal badge
+  - `"blue"`: Blue badge
+  - `"blue-subtle"`: Subtle blue badge
+  - `"neutral"`: Neutral badge
+  - `"neutral-subtle"`: Subtle neutral badge
+  - `"inverted"`: Inverted badge
   - `"outline"`: Bordered badge with transparent background
   - `"beta"`: Indicates beta or experimental features
+  - `"primary"`: Deprecated. Use inverted instead.
+  - `"secondary"`: Deprecated. Use neutral instead.
+  - `"destructive"`: Deprecated. Use red instead.
+  - `"success"`: Deprecated. Use green instead.
 - `className`: string
   Additional CSS classes merged via `cn()`.
 - `children`: ReactNode
@@ -30,29 +45,40 @@ Small status label for categorizing or highlighting content.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-contrast`, `bg-kumo-danger`, `bg-kumo-fill`, `bg-kumo-success`, `border-kumo-brand`, `border-kumo-fill`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-link`
+`bg-kumo-badge-blue`, `bg-kumo-badge-blue-subtle`, `bg-kumo-badge-green`, `bg-kumo-badge-green-subtle`, `bg-kumo-badge-inverted`, `bg-kumo-badge-neutral`, `bg-kumo-badge-orange`, `bg-kumo-badge-orange-subtle`, `bg-kumo-badge-red`, `bg-kumo-badge-red-subtle`, `bg-kumo-badge-teal`, `bg-kumo-badge-teal-subtle`, `bg-kumo-badge-yellow`, `bg-kumo-badge-yellow-subtle`, `bg-kumo-fill`, `border-kumo-brand`, `border-kumo-fill`, `text-kumo-badge-blue-subtle`, `text-kumo-badge-green-subtle`, `text-kumo-badge-inverted`, `text-kumo-badge-neutral-subtle`, `text-kumo-badge-orange-subtle`, `text-kumo-badge-red-subtle`, `text-kumo-badge-teal-subtle`, `text-kumo-badge-yellow-subtle`, `text-kumo-default`, `text-kumo-link`
 
 **Examples:**
 
 ```tsx
 <div className="flex flex-wrap items-center gap-2">
-      <Badge variant="primary">Primary</Badge>
-      <Badge variant="secondary">Secondary</Badge>
-      <Badge variant="destructive">Destructive</Badge>
-      <Badge variant="success">Success</Badge>
+      <Badge variant="red">Red</Badge>
+      <Badge variant="orange">Orange</Badge>
+      <Badge variant="yellow">Yellow</Badge>
+      <Badge variant="green">Green</Badge>
+      <Badge variant="teal">Teal</Badge>
+      <Badge variant="blue">Blue</Badge>
+      <Badge variant="neutral">Neutral</Badge>
+      <Badge variant="inverted">Inverted</Badge>
       <Badge variant="outline">Outline</Badge>
       <Badge variant="beta">Beta</Badge>
+      <Badge variant="red-subtle">Red subtle</Badge>
+      <Badge variant="orange-subtle">Orange subtle</Badge>
+      <Badge variant="yellow-subtle">Yellow subtle</Badge>
+      <Badge variant="green-subtle">Green subtle</Badge>
+      <Badge variant="teal-subtle">Teal subtle</Badge>
+      <Badge variant="blue-subtle">Blue subtle</Badge>
+      <Badge variant="neutral-subtle">Neutral subtle</Badge>
     </div>
 ```
 
 ```tsx
-<Badge variant="primary">Primary</Badge>
+<Badge variant="red">Red</Badge>
 ```
 
 ```tsx
 <p className="flex items-center gap-2">
       Workers
-      <Badge variant="beta">Beta</Badge>
+      <Badge variant="blue">New</Badge>
     </p>
 ```
 
@@ -77,6 +103,8 @@ Full-width message bar for informational, warning, or error notices. Supports st
   Primary heading text for the banner. Use for i18n string injection.
 - `description`: ReactNode
   Secondary description text displayed below the title. Use for i18n string injection.
+- `action`: ReactNode
+  Action slot rendered at the trailing end of the banner (e.g. a CTA button or link). Only used in structured mode (with `title` or `description`).
 - `text`: string
 - `children`: ReactNode
 - `variant`: enum [default: default]
@@ -93,7 +121,7 @@ Full-width message bar for informational, warning, or error notices. Supports st
 **Examples:**
 
 ```tsx
-<div className="space-y-3">
+<div className="w-full space-y-3">
       <Banner
         icon={<Info weight="fill" />}
         title="Update available"
@@ -150,6 +178,48 @@ Full-width message bar for informational, warning, or error notices. Supports st
     />
 ```
 
+```tsx
+<div className="w-full space-y-3">
+      <Banner
+        icon={<Info weight="fill" />}
+        title="Update available"
+        description="A new version is ready to install."
+        action={<Button size="sm">Update now</Button>}
+      />
+      <Banner
+        icon={<Info weight="fill" />}
+        title="Update available"
+        description="A new version is ready to install."
+        action={
+          <Button
+            size="sm"
+            variant="ghost"
+            shape="square"
+            icon={X}
+            aria-label="Dismiss"
+          />
+        }
+      />
+    </div>
+```
+
+```tsx
+<Banner
+      icon={<Warning weight="fill" />}
+      variant="alert"
+      title="Session expiring"
+      description="Your session will expire in 5 minutes."
+      action={
+        <>
+          <Button size="sm" variant="secondary">
+            Dismiss
+          </Button>
+          <Button size="sm">Extend session</Button>
+        </>
+      }
+    />
+```
+
 ```tsx
 <Banner icon={<Info />}>This is a simple banner using children.</Banner>
 ```
@@ -308,9 +378,9 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
   Icon from `@phosphor-icons/react` or a React element. Rendered before children.
 - `loading`: boolean
   Shows a loading spinner and disables interaction.
+- `title`: string
 - `id`: string
 - `lang`: string
-- `title`: string
 - `disabled`: boolean
 - `name`: string
 - `type`: enum
@@ -378,6 +448,21 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
     </div>
 ```
 
+```tsx
+<div className="flex flex-wrap items-center gap-3">
+      <Button variant="secondary" title="Create a new Worker">
+        Create Worker
+      </Button>
+      <Button
+        variant="secondary"
+        shape="square"
+        icon={PlusIcon}
+        aria-label="Add item"
+        title="Add item"
+      />
+    </div>
+```
+
 
 ---
 
@@ -424,7 +509,7 @@ Checkbox component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-contrast`, `border-kumo-line`, `ring-kumo-contrast`, `ring-kumo-danger`, `ring-kumo-line`, `ring-kumo-ring`, `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-line`, `ring-kumo-ring`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-inverse`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -547,6 +632,8 @@ Read-only text field with a one-click copy-to-clipboard button.
   - `"lg"`: Large clipboard text for prominent display
 - `text`: string (required)
   The text to display and copy to clipboard.
+- `textToCopy`: string
+  If provided, this text will be copied to clipboard instead of the `text` prop.
 - `className`: string
   Additional CSS classes merged via `cn()`.
 - `tooltip`: object
@@ -610,6 +697,13 @@ Read-only text field with a one-click copy-to-clipboard button.
 <ClipboardText text="0c239dd2" />
 ```
 
+```tsx
+<ClipboardText
+      text="sk_live_***********"
+      textToCopy="sk_live_51H8_abc123"
+    />
+```
+
 ```tsx
 <ClipboardText
       text="npx kumo add button"
@@ -1077,27 +1171,6 @@ Props:
 - `lang`: CodeLang
 
 
-**Examples:**
-
-```tsx
-<CodeBlock
-      lang="tsx"
-      code={`const greeting = "Hello, World!";
-console.log(greeting);`}
-    />
-```
-
-```tsx
-<Code
-      lang="bash"
-      code="export API_KEY={{apiKey}}"
-      values={{
-        apiKey: { value: "sk_live_123", highlight: true },
-      }}
-    />
-```
-
-
 ---
 
 ### Collapsible
@@ -1225,6 +1298,7 @@ Props:
 - `alignOffset`: ComboboxBase.Positioner.Props["alignOffset"]
 - `side`: ComboboxBase.Positioner.Props["side"]
 - `sideOffset`: ComboboxBase.Positioner.Props["sideOffset"]
+- `container`: PortalContainer
 
 #### Combobox.TriggerValue
 
@@ -1419,6 +1493,42 @@ Usage:
     </div>
 ```
 
+```tsx
+<div className="flex flex-wrap gap-4 items-start">
+      <Combobox value="Apple" items={fruits} disabled>
+        <Combobox.TriggerInput
+          className="w-[200px]"
+          placeholder="Select fruit"
+        />
+        <Combobox.Content>
+          <Combobox.Empty />
+          <Combobox.List>
+            {(item: string) => (
+              <Combobox.Item key={item} value={item}>
+                {item}
+              </Combobox.Item>
+            )}
+          </Combobox.List>
+        </Combobox.Content>
+      </Combobox>
+
+      <Combobox value={languages[0]} items={languages} disabled>
+        <Combobox.TriggerValue className="w-[200px]" />
+        <Combobox.Content>
+          <Combobox.Input placeholder="Search" />
+          <Combobox.Empty />
+          <Combobox.List>
+            {(item: Language) => (
+              <Combobox.Item key={item.value} value={item}>
+                {item.emoji} {item.label}
+              </Combobox.Item>
+            )}
+          </Combobox.List>
+        </Combobox.Content>
+      </Combobox>
+    </div>
+```
+
 ```tsx
 <div className="w-80">
       <Combobox
@@ -1546,6 +1656,8 @@ CommandPalette — accessible command palette / spotlight search overlay.  Compo
   Whether the dialog is open
 - `children`: ReactNode
   Child content - typically one or more Panel components
+- `container`: PortalContainer
+  Container element for the portal. Use this to render the command palette inside a Shadow DOM or custom container. Overrides `KumoPortalProvider` context.
 
 **Colors (kumo tokens used):**
 
@@ -2027,6 +2139,8 @@ Dialog component
   Additional CSS classes merged via `cn()`.
 - `children`: ReactNode
   Dialog content (typically Title, Description, Close, and action buttons).
+- `container`: PortalContainer
+  Container element for the portal. Use this to render the dialog inside a Shadow DOM or custom container. Overrides `KumoPortalProvider` context.
 - `size`: enum [default: base]
   - `"base"`: Default dialog width
   - `"sm"`: Small dialog for simple confirmations
@@ -2035,7 +2149,7 @@ Dialog component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `text-kumo-default`
+`bg-kumo-base`, `bg-kumo-recessed`, `text-kumo-default`
 
 **Styling:**
 
@@ -3100,7 +3214,7 @@ LayerCard component
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-elevated`, `bg-kumo-recessed`, `ring-kumo-fill`, `ring-kumo-line`, `text-kumo-strong`
+`bg-kumo-base`, `bg-kumo-elevated`, `ring-kumo-fill`, `ring-kumo-line`, `text-kumo-strong`
 
 **Styling:**
 
@@ -3316,6 +3430,10 @@ Animated circular spinner for indicating loading states.
 <Loader size={24} />
 ```
 
+```tsx
+<Loader className="text-kumo-subtle" />
+```
+
 
 ---
 
@@ -3342,7 +3460,7 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-base`, `bg-kumo-fill`, `border-kumo-fill`
+`bg-kumo-base`, `bg-kumo-recessed`, `border-kumo-fill`, `border-kumo-recessed`
 
 **Styling:**
 
@@ -3351,20 +3469,20 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.
 
 ```tsx
 <MenuBar
-      isActive="bold"
+      isActive={active}
       optionIds
       options={[
         {
           icon: <TextBolderIcon />,
           id: "bold",
           tooltip: "Bold",
-          onClick: () => {},
+          onClick: () => setActive(active === "bold" ? undefined : "bold"),
         },
         {
           icon: <TextItalicIcon />,
           id: "italic",
           tooltip: "Italic",
-          onClick: () => {},
+          onClick: () => setActive(active === "italic" ? undefined : "italic"),
         },
       ]}
     />
@@ -3424,7 +3542,7 @@ Progress bar showing a measured value within a known range (e.g. quota usage).
 <Meter
       label="Upload progress"
       value={80}
-      indicatorClassName="from-green-500 via-green-500 to-green-500"
+      indicatorClassName="from-kumo-success via-kumo-success to-kumo-success"
     />
 ```
 
@@ -3839,7 +3957,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-interact`, `border-kumo-line`, `border-kumo-ring`, `ring-kumo-danger`, `ring-kumo-line`, `ring-kumo-ring`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-contrast`, `bg-kumo-tint`, `border-kumo-danger`, `border-kumo-interact`, `border-kumo-ring`, `ring-kumo-danger`, `ring-kumo-line`, `ring-kumo-ring`, `text-kumo-danger`, `text-kumo-default`, `text-kumo-subtle`
 
 **Sub-Components:**
 
@@ -4268,7 +4386,7 @@ Option sub-component
         <span className="flex items-center gap-2">
           <span>Issue Types</span>
           {selected.length > 0 && (
-            <Badge variant="secondary">{selected.length}</Badge>
+            <Badge variant="neutral">{selected.length}</Badge>
           )}
         </span>
       )}
@@ -4433,11 +4551,486 @@ Password/secret input that masks its value by default and reveals on click. Incl
 ```
 
 
+---
+
+### Sidebar
+
+Sidebar — responsive navigation panel with expand/collapse support.  Compound component: `Sidebar` (root `<aside>`), `.Provider`, `.Header`, `.Content`, `.Footer`, `.Group`, `.GroupLabel`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction`, `.MenuBadge`, `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`, `.Separator`, `.Input`, `.Trigger`, `.Rail`, `.MenuChevron`, `.Collapsible`, `.CollapsibleTrigger`, `.CollapsibleContent`.  Built on `@base-ui/react/collapsible` + `@base-ui/react/dialog`.
+
+**Type:** component
+
+**Import:** `import { Sidebar } from "@cloudflare/kumo";`
+
+**Category:** Other
+
+**Props:**
+
+- `defaultOpen`: boolean
+  Initial open state when uncontrolled.
+- `open`: boolean
+  Controlled open state.
+- `variant`: enum [default: sidebar]
+  - `"sidebar"`: Standard sidebar with border separator
+  - `"floating"`: Floating sidebar with shadow and rounded corners
+  - `"inset"`: Inset sidebar within the content area
+- `side`: enum [default: left]
+  - `"left"`: Left-aligned sidebar
+  - `"right"`: Right-aligned sidebar
+- `collapsible`: enum [default: icon]
+  - `"icon"`: Collapses to show icons only
+  - `"offcanvas"`: Slides off screen when collapsed
+  - `"none"`: Cannot be collapsed
+- `resizable`: boolean
+  Enable drag-to-resize on the sidebar edge.
+- `defaultWidth`: number
+  Initial width in pixels when resizable.
+- `minWidth`: number
+  Minimum width in pixels when resizing.
+- `maxWidth`: number
+  Maximum width in pixels when resizing.
+- `children`: ReactNode
+  Content — typically `<Sidebar>` + main content.
+- `className`: string
+  Additional CSS classes for the wrapper div.
+
+**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-line`, `ring-kumo-ring`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+
+**Styling:**
+
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Sidebar.Provider
+
+Provider sub-component
+
+Props:
+- `defaultOpen`: boolean
+- `open`: boolean
+- `variant`: SidebarVariant
+- `side`: SidebarSide
+- `collapsible`: "icon" | "offcanvas" | "none"
+- `resizable`: boolean
+- `defaultWidth`: number
+- `minWidth`: number
+- `maxWidth`: number
+- `children`: ReactNode (required)
+- `className`: string
+
+#### Sidebar.Header
+
+Header sub-component
+
+#### Sidebar.Content
+
+Content sub-component
+
+#### Sidebar.Footer
+
+Footer sub-component
+
+#### Sidebar.Group
+
+Group sub-component
+
+#### Sidebar.GroupLabel
+
+GroupLabel sub-component
+
+#### Sidebar.GroupContent
+
+GroupContent sub-component
+
+#### Sidebar.Menu
+
+Menu sub-component
+
+#### Sidebar.MenuItem
+
+MenuItem sub-component
+
+#### Sidebar.MenuButton
+
+MenuButton sub-component
+
+#### Sidebar.MenuAction
+
+MenuAction sub-component
+
+#### Sidebar.MenuBadge
+
+MenuBadge sub-component
+
+#### Sidebar.MenuSub
+
+MenuSub sub-component
+
+#### Sidebar.MenuSubItem
+
+MenuSubItem sub-component
+
+#### Sidebar.MenuSubButton
+
+MenuSubButton sub-component
+
+#### Sidebar.Separator
+
+Separator sub-component
+
+#### Sidebar.Input
+
+Input sub-component
+
+#### Sidebar.Trigger
+
+Trigger sub-component
+
+#### Sidebar.Rail
+
+Rail sub-component
+
+#### Sidebar.ResizeHandle
+
+ResizeHandle sub-component
+
+#### Sidebar.MenuChevron
+
+MenuChevron sub-component
+
+#### Sidebar.Collapsible
+
+Collapsible sub-component
+
+#### Sidebar.CollapsibleTrigger
+
+CollapsibleTrigger sub-component
+
+#### Sidebar.CollapsibleContent
+
+CollapsibleContent sub-component
+
+
+**Examples:**
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+        <Sidebar>
+          <Sidebar.Content>
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={HouseIcon} active>
+                  Home
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={ChartBarIcon}>
+                  Analytics
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={GlobeIcon}>
+                  Domains
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Build</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuItem>
+                  <Sidebar.Collapsible defaultOpen>
+                    <Sidebar.CollapsibleTrigger
+                      render={
+                        <Sidebar.MenuButton icon={CodeIcon}>
+                          Compute
+                          <Sidebar.MenuChevron />
+                        </Sidebar.MenuButton>
+                      }
+                    />
+                    <Sidebar.CollapsibleContent>
+                      <Sidebar.MenuSub>
+                        <Sidebar.MenuSubButton>
+                          Workers & Pages
+                        </Sidebar.MenuSubButton>
+                        <Sidebar.MenuSubButton>
+                          Durable Objects
+                        </Sidebar.MenuSubButton>
+                      </Sidebar.MenuSub>
+                    </Sidebar.CollapsibleContent>
+                  </Sidebar.Collapsible>
+                </Sidebar.MenuItem>
+                <Sidebar.MenuButton icon={DatabaseIcon}>
+                  Storage
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+          </Sidebar.Content>
+        </Sidebar>
+        <DemoMain />
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+        <Sidebar>
+          <Sidebar.Content>
+            {/* GroupContent is required for collapsible groups (provides grid-rows animation) */}
+            <Sidebar.Group collapsible defaultOpen>
+              <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+              <Sidebar.GroupContent>
+                <Sidebar.Menu>
+                  <Sidebar.MenuButton icon={HouseIcon} active>
+                    Home
+                  </Sidebar.MenuButton>
+                  <Sidebar.MenuButton icon={ChartBarIcon}>
+                    Analytics
+                  </Sidebar.MenuButton>
+                  <Sidebar.MenuButton icon={GlobeIcon}>
+                    Domains
+                  </Sidebar.MenuButton>
+                </Sidebar.Menu>
+              </Sidebar.GroupContent>
+            </Sidebar.Group>
+
+            <Sidebar.Group collapsible defaultOpen>
+              <Sidebar.GroupLabel>Build</Sidebar.GroupLabel>
+              <Sidebar.GroupContent>
+                <Sidebar.Menu>
+                  <Sidebar.MenuButton icon={CodeIcon}>
+                    Compute
+                  </Sidebar.MenuButton>
+                  <Sidebar.MenuButton icon={DatabaseIcon}>
+                    Storage
+                  </Sidebar.MenuButton>
+                </Sidebar.Menu>
+              </Sidebar.GroupContent>
+            </Sidebar.Group>
+
+            <Sidebar.Group collapsible defaultOpen={false}>
+              <Sidebar.GroupLabel>Protect & Connect</Sidebar.GroupLabel>
+              <Sidebar.GroupContent>
+                <Sidebar.Menu>
+                  <Sidebar.MenuButton icon={ShieldCheckIcon}>
+                    Security
+                  </Sidebar.MenuButton>
+                  <Sidebar.MenuButton icon={LockIcon}>
+                    Zero Trust
+                  </Sidebar.MenuButton>
+                </Sidebar.Menu>
+              </Sidebar.GroupContent>
+            </Sidebar.Group>
+          </Sidebar.Content>
+        </Sidebar>
+        <DemoMain />
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+        <Sidebar>
+          <Sidebar.Header>
+            <BrandLogo />
+          </Sidebar.Header>
+          <Sidebar.Content>
+            <Sidebar.Group>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={HouseIcon} tooltip="Home" active>
+                  Home
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={ChartBarIcon} tooltip="Analytics">
+                  Analytics
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={CodeIcon} tooltip="Compute">
+                  Compute
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={DatabaseIcon} tooltip="Storage">
+                  Storage
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+          </Sidebar.Content>
+          <Sidebar.Footer>
+            <Sidebar.Trigger />
+          </Sidebar.Footer>
+        </Sidebar>
+        <DemoMain>
+          <ToggleButton />
+          <p className="text-sm">
+            Click the button or the sidebar trigger to toggle
+          </p>
+        </DemoMain>
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+        <Sidebar>
+          <Sidebar.Header>
+            <AccountSwitcher />
+          </Sidebar.Header>
+
+          <Sidebar.Content>
+            <div className="px-1 pb-2">
+              <Sidebar.Input placeholder="Quick search..." shortcut="⌘K" />
+            </div>
+
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={HouseIcon} active>
+                  Home
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={ChartBarIcon}>
+                  Analytics & Logs
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={GlobeIcon}>
+                  Domains
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+
+            <Sidebar.Separator />
+
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Build</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuItem>
+                  <Sidebar.Collapsible defaultOpen>
+                    <Sidebar.CollapsibleTrigger
+                      render={
+                        <Sidebar.MenuButton icon={CodeIcon}>
+                          Compute
+                          <Sidebar.MenuChevron />
+                        </Sidebar.MenuButton>
+                      }
+                    />
+                    <Sidebar.CollapsibleContent>
+                      <Sidebar.MenuSub>
+                        <Sidebar.MenuSubButton>
+                          Workers & Pages
+                        </Sidebar.MenuSubButton>
+                        <Sidebar.MenuSubButton>
+                          Durable Objects
+                        </Sidebar.MenuSubButton>
+                        <Sidebar.MenuSubButton>
+                          Containers
+                          <Sidebar.MenuBadge>Beta</Sidebar.MenuBadge>
+                        </Sidebar.MenuSubButton>
+                      </Sidebar.MenuSub>
+                    </Sidebar.CollapsibleContent>
+                  </Sidebar.Collapsible>
+                </Sidebar.MenuItem>
+                <Sidebar.MenuButton icon={DatabaseIcon}>
+                  Storage
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Protect & Connect</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={ShieldCheckIcon}>
+                  Security
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={LockIcon}>
+                  Zero Trust
+                  <Sidebar.MenuBadge>Beta</Sidebar.MenuBadge>
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+          </Sidebar.Content>
+
+          <Sidebar.Footer>
+            <Sidebar.MenuButton icon={GearIcon}>
+              Manage account
+            </Sidebar.MenuButton>
+          </Sidebar.Footer>
+        </Sidebar>
+        <DemoMain />
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider
+        defaultOpen
+        resizable
+        defaultWidth={240}
+        minWidth={180}
+        maxWidth={400}
+        className="min-h-0! h-full"
+      >
+        <Sidebar>
+          <Sidebar.Header>
+            <BrandLogo />
+          </Sidebar.Header>
+          <Sidebar.Content>
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={HouseIcon} active>
+                  Home
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={ChartBarIcon}>
+                  Analytics
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={DatabaseIcon}>
+                  Storage
+                </Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+          </Sidebar.Content>
+          <Sidebar.Footer>
+            <Sidebar.Trigger />
+          </Sidebar.Footer>
+          <Sidebar.ResizeHandle />
+        </Sidebar>
+        <DemoMain>
+          <p className="text-sm">Drag the sidebar edge to resize</p>
+        </DemoMain>
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+      <Sidebar.Provider defaultOpen side="right" className="min-h-0! h-full">
+        <DemoMain />
+        <Sidebar>
+          <Sidebar.Content>
+            <Sidebar.Group>
+              <Sidebar.GroupLabel>Details</Sidebar.GroupLabel>
+              <Sidebar.Menu>
+                <Sidebar.MenuButton icon={GearIcon} active>
+                  Properties
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={ChartBarIcon}>
+                  Metrics
+                </Sidebar.MenuButton>
+                <Sidebar.MenuButton icon={BellIcon}>Alerts</Sidebar.MenuButton>
+              </Sidebar.Menu>
+            </Sidebar.Group>
+          </Sidebar.Content>
+        </Sidebar>
+      </Sidebar.Provider>
+    </DemoContainer>
+```
+
+
 ---
 
 ### Surface
 
-Surface component
+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> ```
 
 **Type:** component
 
@@ -4448,11 +5041,15 @@ Surface component
 **Props:**
 
 - `as`: React.ElementType
-  The HTML element type to render as (e.g. `"div"`, `"section"`, `"article"`).
-- `className`: string
-  Additional CSS classes merged via `cn()`.
+- `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
-  Content rendered inside the surface.
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
 
 **Colors (kumo tokens used):**
 
@@ -4475,13 +5072,13 @@ Surface component
 
 ```tsx
 <div className="flex flex-col gap-4">
-      <Surface as="section" className="rounded-lg p-4">
+      <Surface render={<section />} className="rounded-lg p-4">
         <Text bold>As section element</Text>
       </Surface>
-      <Surface as="article" className="rounded-lg p-4">
+      <Surface render={<article />} className="rounded-lg p-4">
         <Text bold>As article element</Text>
       </Surface>
-      <Surface as="aside" className="rounded-lg p-4">
+      <Surface render={<aside />} className="rounded-lg p-4">
         <Text bold>As aside element</Text>
       </Surface>
     </div>
@@ -4608,14 +5205,25 @@ Props:
 ```
 
 ```tsx
-<div className="flex flex-col gap-4">
+<div className="grid grid-cols-2 gap-x-8 gap-y-4">
       <Switch
-        label="Default variant"
+        label="Default off"
+        checked={false}
+        onCheckedChange={() => {}}
+      />
+      <Switch
+        label="Default on"
         checked={true}
         onCheckedChange={() => {}}
       />
       <Switch
-        label="Neutral variant"
+        label="Neutral off"
+        variant="neutral"
+        checked={false}
+        onCheckedChange={() => {}}
+      />
+      <Switch
+        label="Neutral on"
         variant="neutral"
         checked={true}
         onCheckedChange={() => {}}
@@ -4623,6 +5231,29 @@ Props:
     </div>
 ```
 
+```tsx
+<div className="flex flex-col gap-4">
+      <Switch
+        label="Small"
+        size="sm"
+        checked={true}
+        onCheckedChange={() => {}}
+      />
+      <Switch
+        label="Base (default)"
+        size="base"
+        checked={true}
+        onCheckedChange={() => {}}
+      />
+      <Switch
+        label="Large"
+        size="lg"
+        checked={true}
+        onCheckedChange={() => {}}
+      />
+    </div>
+```
+
 
 ---
 
@@ -4644,6 +5275,9 @@ Table — semantic HTML table with styled rows, cells, and selection support.  C
 - `variant`: enum [default: default]
   - `"default"`: Default row variant
   - `"selected"`: Selected row variant
+- `sticky`: enum
+  - `"left"`: Pin column to the left edge of the scroll container
+  - `"right"`: Pin column to the right edge of the scroll container
 - `className`: string
   Additional CSS classes
 - `children`: ReactNode
@@ -4855,6 +5489,78 @@ ResizeHandle sub-component
     </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>
+            </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.Primary>
+    </LayerCard>
+```
+
 ```tsx
 <LayerCard>
       <LayerCard.Primary className="w-full overflow-x-auto p-0">
@@ -4985,7 +5691,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-surface`, `bg-kumo-tint`, `border-kumo-ring`, `ring-kumo-ring`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
+`bg-kumo-base`, `bg-kumo-brand`, `bg-kumo-recessed`, `bg-kumo-tint`, `border-kumo-ring`, `ring-kumo-line`, `ring-kumo-ring`, `text-kumo-default`, `text-kumo-strong`, `text-kumo-subtle`
 
 **Styling:**
 
@@ -5120,6 +5826,8 @@ Text component
   - `"lg"`: Large text
 - `bold`: boolean
   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.
 - `children`: ReactNode
@@ -5197,6 +5905,15 @@ Text component
     </div>
 ```
 
+```tsx
+<div className="w-64 rounded-lg border border-kumo-line 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.
+      </Text>
+    </div>
+```
+
 
 ---
 
@@ -5225,7 +5942,7 @@ Toasty — toast notification provider and viewport.  Renders a `Toast.Provider`
 
 **Colors (kumo tokens used):**
 
-`bg-kumo-contrast`, `bg-kumo-control`, `bg-kumo-danger-tint`, `bg-kumo-fill-hover`, `bg-kumo-info-tint`, `bg-kumo-success-tint`, `bg-kumo-warning-tint`, `border-kumo-danger`, `border-kumo-fill`, `border-kumo-info`, `border-kumo-success`, `border-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-tint`, `bg-kumo-fill-hover`, `bg-kumo-info-tint`, `bg-kumo-success-tint`, `bg-kumo-warning-tint`, `border-kumo-fill`, `ring-kumo-danger`, `ring-kumo-info`, `ring-kumo-ring`, `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:**
 
@@ -5330,7 +6047,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, Table, DeleteResource
+- **Other:** CloudflareLogo, DatePicker, Label, Link, SensitiveInput, Sidebar, Table, DeleteResource
 - **Navigation:** CommandPalette, MenuBar, Pagination, Tabs
 - **Overlay:** Dialog, DropdownMenu, Popover, Tooltip
 - **Layout:** Grid, Surface, PageHeader, ResourceListPage