@duro-app/ui 0.51.0 → 1.0.0

package/src/components/SideNav/SideNav.meta.ts

@@ -2,33 +2,36 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Vertical side navigation. Use collapsible `Group`s (chevron accordion) or static `Section`s (always-open headers) — or a mix. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required.',
+    'Vertical side navigation. `Section` is a labelled block that is always open — the default for primary navigation. `Group` is the same block behind a chevron (a disclosure) — reach for it only for a rare/advanced region, an unbounded data-driven list, or a rail long enough that flat stops reading as an overview; mixing the two in one rail is the healthy shape. `Item`s take an optional `icon` and show an active left-marker. Supports controlled and uncontrolled active item. Compound component — Root is required.',
   whenToUse: [
-    'App-level sidebar navigation',
-    'Settings navigation with grouped sections',
-    'Flat menu with labelled, always-open regions — use Section instead of Group',
+    'App-level sidebar navigation — flat `Section`s, every destination visible',
+    'Settings navigation with labelled regions',
+    '`Group` for a rare or advanced region tucked below the flat sections',
+    '`Group` when the entries are data-driven and unbounded (one per namespace, project, team)',
   ],
   whenNotToUse: [
+    'Collapsing the everyday destinations — a nav advertises where you can go; hiding the common ones behind a chevron costs a click each and removes them from scanning. Use `Section`.',
+    'Arbitrary-depth data browsing (file tree, resource drill-down) — that needs role="tree" with roving tabindex and typeahead, not a deeper SideNav',
     'In-page content switching — use Tabs',
     'Top-level horizontal nav — use Inline with LinkButton',
   ],
   anatomy: {
     required: ['Root', 'Item'],
-    optional: ['Group', 'Section'],
+    optional: ['Section', 'Group'],
   },
   relatedTo: [
     {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
     {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
   ],
   example: `<SideNav.Root defaultValue="identities">
-  {/* Static, always-open sections with icons (flat menu) */}
+  {/* Default: always-open sections. Nothing is a click away from being seen. */}
   <SideNav.Section label="People & access">
-    <SideNav.Item value="identities" icon={<Icon name="users" size={18} />}>Identities</SideNav.Item>
-    <SideNav.Item value="grants" icon={<Icon name="key" size={18} />}>Grants</SideNav.Item>
+    <SideNav.Item value="identities" icon={<Icon name="users" size="md" />}>Identities</SideNav.Item>
+    <SideNav.Item value="grants" icon={<Icon name="key" size="md" />}>Grants</SideNav.Item>
   </SideNav.Section>
-  {/* Or collapsible groups (accordion) */}
+  {/* Disclosure, earned: rarely visited, so it starts collapsed. */}
   <SideNav.Group label="Advanced" defaultExpanded={false}>
-    <SideNav.Item value="plugins" icon={<Icon name="plug" size={18} />}>Plugins</SideNav.Item>
+    <SideNav.Item value="plugins" icon={<Icon name="plug" size="md" />}>Plugins</SideNav.Item>
   </SideNav.Group>
 </SideNav.Root>`,
 }

package/src/components/SideNav/SideNav.stories.tsx

@@ -14,18 +14,21 @@ const meta: Meta<typeof SideNav.Root> = {
 export default meta
 type Story = StoryObj<typeof SideNav.Root>
 
+// The default shape for primary navigation: labelled `Section`s, all open, no
+// chevrons. Every destination is visible and one click away — a nav's job is to
+// advertise where you can go, and a collapsed group does the opposite.
 export const Default: Story = {
   render: (args) => (
     <SideNav.Root {...args} defaultValue="dashboard">
-      <SideNav.Group label="Overview" defaultExpanded>
+      <SideNav.Section label="Overview">
         <SideNav.Item value="dashboard">Dashboard</SideNav.Item>
         <SideNav.Item value="analytics">Analytics</SideNav.Item>
-      </SideNav.Group>
-      <SideNav.Group label="Settings">
+      </SideNav.Section>
+      <SideNav.Section label="Settings">
         <SideNav.Item value="profile">Profile</SideNav.Item>
         <SideNav.Item value="security">Security</SideNav.Item>
         <SideNav.Item value="notifications">Notifications</SideNav.Item>
-      </SideNav.Group>
+      </SideNav.Section>
     </SideNav.Root>
   ),
   play: async ({canvas}) => {
@@ -34,6 +37,62 @@ export const Default: Story = {
 
     const activeItem = canvas.getByRole('button', {name: 'Dashboard'})
     await expect(activeItem).toHaveAttribute('aria-current', 'page')
+
+    // Nothing is hidden: no section is a disclosure, every item is reachable.
+    await expect(canvas.queryByRole('button', {name: 'Settings'})).toBeNull()
+    await expect(canvas.getByRole('button', {name: 'Notifications'})).toBeInTheDocument()
+
+    // Each section names its own group so a screen reader hears "Settings,
+    // group" rather than one undifferentiated run of buttons.
+    const groups = canvas.getAllByRole('group')
+    await expect(groups).toHaveLength(2)
+    await expect(groups[0]).toHaveAccessibleName('Overview')
+    await expect(groups[1]).toHaveAccessibleName('Settings')
+  },
+}
+
+// The healthy mix: flat sections carry the journey, and ONE collapsed Group
+// holds the region you visit rarely. Disclosure is for the seldom-used — never
+// for the everyday.
+export const SectionsWithOneDisclosedGroup: Story = {
+  render: (args) => (
+    <SideNav.Root {...args} defaultValue="identities">
+      <SideNav.Section label="People & access">
+        <SideNav.Item value="identities" icon={<Icon name="users" size="md" />}>
+          Identities
+        </SideNav.Item>
+        <SideNav.Item value="grants" icon={<Icon name="key" size="md" />}>
+          Grants
+        </SideNav.Item>
+      </SideNav.Section>
+      <SideNav.Section label="Audit">
+        <SideNav.Item value="audit" icon={<Icon name="file-text" size="md" />}>
+          Audit log
+        </SideNav.Item>
+      </SideNav.Section>
+      <SideNav.Group label="Advanced">
+        <SideNav.Item value="plugins" icon={<Icon name="plug" size="md" />}>
+          Plugins
+        </SideNav.Item>
+      </SideNav.Group>
+    </SideNav.Root>
+  ),
+  play: async ({canvas, userEvent}) => {
+    // Everyday destinations: visible without interaction.
+    await expect(canvas.getByRole('button', {name: 'Identities'})).toBeInTheDocument()
+    await expect(canvas.getByRole('button', {name: 'Audit log'})).toBeInTheDocument()
+
+    // The rare one is disclosed, and says so.
+    const advanced = canvas.getByRole('button', {name: 'Advanced'})
+    await expect(advanced).toHaveAttribute('aria-expanded', 'false')
+    await expect(advanced).not.toHaveAttribute('aria-controls')
+    await expect(canvas.queryByRole('button', {name: 'Plugins'})).toBeNull()
+
+    await userEvent.click(advanced)
+    await expect(advanced).toHaveAttribute('aria-expanded', 'true')
+    const panelId = advanced.getAttribute('aria-controls')
+    await expect(panelId).toBeTruthy()
+    await expect(canvas.getByRole('button', {name: 'Plugins'})).toBeInTheDocument()
   },
 }
 
@@ -106,18 +165,18 @@ export const FlatWithIcons: Story = {
   render: (args) => (
     <SideNav.Root {...args} defaultValue="grants">
       <SideNav.Section label="People & access">
-        <SideNav.Item value="identities" icon={<Icon name="users" size={18} />}>
+        <SideNav.Item value="identities" icon={<Icon name="users" size="md" />}>
           Identities
         </SideNav.Item>
-        <SideNav.Item value="grants" icon={<Icon name="key" size={18} />}>
+        <SideNav.Item value="grants" icon={<Icon name="key" size="md" />}>
           Grants
         </SideNav.Item>
       </SideNav.Section>
       <SideNav.Section label="Requests & invites">
-        <SideNav.Item value="invitations" icon={<Icon name="mail" size={18} />}>
+        <SideNav.Item value="invitations" icon={<Icon name="mail" size="md" />}>
           Invitations
         </SideNav.Item>
-        <SideNav.Item value="invites" icon={<Icon name="user-plus" size={18} />}>
+        <SideNav.Item value="invites" icon={<Icon name="user-plus" size="md" />}>
           User Invites
         </SideNav.Item>
       </SideNav.Section>

package/src/components/SideNav/SideNav.tsx

@@ -1,9 +1,35 @@
-import {type ReactNode, useState, useCallback, useRef, useEffect} from 'react'
+import {type ReactNode, useState, useCallback, useRef, useEffect, useId} from 'react'
 import {html} from 'react-strict-dom'
 import {styles} from './styles.css'
 import {useControllableValue} from '../../hooks/useControllableValue'
 import {SideNavContext, useSideNav} from './SideNavContext'
 
+/**
+ * SideNav has two ways to chunk a rail, and they are NOT interchangeable.
+ *
+ * `Section` — a labelled block that is always open. This is the DEFAULT for
+ * primary navigation. A nav's job is to advertise where you can go; an
+ * always-open list keeps the whole information architecture scannable and puts
+ * every destination one click away. The uppercase label does the chunking work
+ * on its own — you get the grouping benefit without hiding anything.
+ *
+ * `Group` — the same block behind a chevron (a disclosure). Collapsing costs
+ * every destination inside it an extra click and hides it from scanning, so it
+ * has to buy something back. It does when the region is:
+ *   • rare or advanced ("Advanced", "Danger zone", "Legacy") — disclose the
+ *     seldom-used, never the everyday;
+ *   • unbounded / data-driven (one entry per namespace, project, team) — you
+ *     cannot author-flatten a list whose length you don't control;
+ *   • one of many in a rail long enough (>~30 leaves) that a flat list stops
+ *     reading as an overview.
+ * The healthy shape is a mix: flat Sections for the journey, one collapsed
+ * Group at the bottom.
+ *
+ * Neither is a tree. Arbitrary-depth *data* browsing (a file tree, a
+ * namespace → resource drill-down) needs `role="tree"` with roving tabindex,
+ * typeahead and aria-level — a different component, not a deeper SideNav.
+ */
+
 // --- Root ---
 
 interface RootProps {
@@ -93,6 +119,8 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
   const {expandedGroups, toggleGroup, expandGroup, activeValue} = useSideNav()
   const isExpanded = expandedGroups.has(key)
   const groupRef = useRef<HTMLDivElement>(null)
+  const triggerId = useId()
+  const panelId = useId()
 
   // Auto-expand if this group contains the active item. Uses expandGroup (not
   // toggleGroup) so it never races the defaultExpanded effect into a closed
@@ -125,9 +153,11 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
     <html.div ref={groupRef} style={styles.group}>
       <html.button
         type="button"
+        id={triggerId}
         onClick={() => toggleGroup(key)}
         style={[styles.groupTrigger, hasActiveChild && styles.groupTriggerActive]}
         aria-expanded={isExpanded}
+        aria-controls={isExpanded ? panelId : undefined}
       >
         <html.span style={[styles.chevron, isExpanded && styles.chevronOpen]}>
           <svg
@@ -145,7 +175,11 @@ function Group({children, label, groupKey, defaultExpanded}: GroupProps) {
         </html.span>
         {label}
       </html.button>
-      {isExpanded && children}
+      {isExpanded ? (
+        <html.div id={panelId} role="group" aria-labelledby={triggerId} style={styles.items}>
+          {children}
+        </html.div>
+      ) : null}
     </html.div>
   )
 }
@@ -159,15 +193,24 @@ interface SectionProps {
 
 /**
  * A static, non-collapsible grouping: an always-visible uppercase header with
- * its items below. Unlike `Group` there is no chevron, toggle, or hidden state
- * — use it when every section should stay open at a glance (a flat menu with
- * labelled regions rather than an accordion).
+ * its items below. Unlike `Group` there is no chevron, toggle, or hidden state.
+ *
+ * Reach for this first — see the note at the top of this file for when a
+ * collapsible `Group` is the better call. The label is exposed as the group's
+ * accessible name, so a screen reader announces "Networking, group" on the way
+ * into its items instead of dropping the user into an undifferentiated run of
+ * thirty buttons.
  */
 function Section({children, label}: SectionProps) {
+  const labelId = useId()
   return (
     <html.div style={styles.section}>
-      <html.div style={styles.sectionLabel}>{label}</html.div>
-      {children}
+      <html.div id={labelId} style={styles.sectionLabel}>
+        {label}
+      </html.div>
+      <html.div role="group" aria-labelledby={labelId} style={styles.items}>
+        {children}
+      </html.div>
     </html.div>
   )
 }

package/src/components/SideNav/styles.css.ts

@@ -51,6 +51,13 @@ export const styles = css.create({
   chevronOpen: {
     transform: 'rotate(90deg)',
   },
+  // The `role="group"` wrapper around a Section's / an expanded Group's items.
+  // Purely structural: it exists to carry the accessible name, so it must not
+  // change how the items stack.
+  items: {
+    display: 'flex',
+    flexDirection: 'column',
+  },
   // Static (non-collapsible) section — see SideNav.Section.
   section: {
     display: 'flex',

package/src/components/Stack/Stack.stories.tsx

@@ -3,6 +3,7 @@ import {css, html} from 'react-strict-dom'
 import {Stack} from './Stack'
 import {colors} from '@duro-app/tokens/tokens/colors.css'
 import {spacing} from '@duro-app/tokens/tokens/spacing.css'
+import {SPACING_KEYS} from '@duro-app/tokens/keys'
 
 const meta: Meta<typeof Stack> = {
   title: 'Layout/Stack',
@@ -10,7 +11,7 @@ const meta: Meta<typeof Stack> = {
   argTypes: {
     gap: {
       control: 'select',
-      options: ['xs', 'sm', 'ms', 'md', 'lg', 'xl', 'xxl', 'xxxl'],
+      options: [...SPACING_KEYS],
     },
     align: {
       control: 'select',
@@ -87,7 +88,7 @@ export const CenterAligned: Story = {
 
 export const AllGaps: Story = {
   render: () => {
-    const gaps = ['xs', 'sm', 'ms', 'md', 'lg', 'xl', 'xxl', 'xxxl'] as const
+    const gaps = SPACING_KEYS
     return (
       <Stack gap="xl">
         {gaps.map((g) => (

package/src/components/Stack/Stack.tsx

@@ -1,8 +1,9 @@
 import type {ReactNode} from 'react'
 import {html} from 'react-strict-dom'
+import type {SpacingToken} from '@duro-app/tokens/keys'
 import {styles} from './styles.css'
 
-export type SpacingKey = 'xs' | 'sm' | 'ms' | 'md' | 'lg' | 'xl' | 'xxl' | 'xxxl'
+export type SpacingKey = SpacingToken
 
 interface StackProps {
   gap?: SpacingKey
@@ -19,7 +20,7 @@ const gapMap = {
   xl: styles.gapXl,
   xxl: styles.gapXxl,
   xxxl: styles.gapXxxl,
-} as const
+} as const satisfies Record<SpacingToken, unknown>
 
 const alignMap = {
   start: styles.alignStart,

package/src/components/StatusIcon/StatusIcon.stories.tsx

@@ -43,7 +43,7 @@ export const CheckDone: Story = {
 }
 
 export const CustomSize: Story = {
-  args: {name: 'check-circle', variant: 'success', size: 24},
+  args: {name: 'check-circle', variant: 'success', size: 'lg'},
 }
 
 const gridStyles = css.create({

package/src/components/StatusIcon/StatusIcon.tsx

@@ -1,6 +1,6 @@
 import {html} from 'react-strict-dom'
 import {Icon} from '../Icon'
-import type {IconName} from '../Icon'
+import type {IconName, IconSize} from '../Icon'
 import {styles} from './styles.css'
 
 export type StatusIconName = Extract<
@@ -11,11 +11,11 @@ export type StatusIconVariant = 'error' | 'success' | 'warning' | 'info' | 'mute
 
 interface StatusIconProps {
   name: StatusIconName
-  size?: number
+  size?: IconSize
   variant?: StatusIconVariant
 }
 
-export function StatusIcon({name, size = 48, variant = 'muted'}: StatusIconProps) {
+export function StatusIcon({name, size = 'xxl', variant = 'muted'}: StatusIconProps) {
   return (
     <html.div style={[styles.root, styles[variant]]}>
       <Icon name={name} size={size} />

package/src/components/Table/Table.stories.tsx

@@ -920,39 +920,36 @@ export const Responsive: Story = {
     ]
     return (
       <html.div style={responsiveStyles.resizable}>
-        <Table.Container>
-          <Table.SortChip options={sortable} value={sort} onChange={setSort} />
-          <Table.Root>
-            <Table.Header>
-              <Table.Row>
-                <Table.HeaderCell label="Principal">Principal</Table.HeaderCell>
-                <Table.HeaderCell label="Role">Role</Table.HeaderCell>
-                <Table.HeaderCell label="Resource">Resource</Table.HeaderCell>
-                <Table.HeaderCell label="Expires">Expires</Table.HeaderCell>
-                <Table.HeaderCell label="Granted by">Granted by</Table.HeaderCell>
-                <Table.HeaderCell label="Actions" isActions>
-                  Actions
-                </Table.HeaderCell>
+        <Table.Root
+          sortChip={<Table.SortChip options={sortable} value={sort} onChange={setSort} />}
+        >
+          <Table.Header>
+            <Table.Row>
+              <Table.HeaderCell label="Principal">Principal</Table.HeaderCell>
+              <Table.HeaderCell label="Role">Role</Table.HeaderCell>
+              <Table.HeaderCell label="Resource">Resource</Table.HeaderCell>
+              <Table.HeaderCell label="Expires">Expires</Table.HeaderCell>
+              <Table.HeaderCell label="Granted by">Granted by</Table.HeaderCell>
+              <Table.HeaderCell label="Actions">Actions</Table.HeaderCell>
+            </Table.Row>
+          </Table.Header>
+          <Table.Body>
+            {grants.map((g) => (
+              <Table.Row key={g.principal}>
+                <Table.Cell>{g.principal}</Table.Cell>
+                <Table.Cell>{g.role}</Table.Cell>
+                <Table.Cell>{g.resource}</Table.Cell>
+                <Table.Cell>{g.expires}</Table.Cell>
+                <Table.Cell>{g.granted_by}</Table.Cell>
+                <Table.Cell isActions>
+                  <Button size="small" variant="secondary">
+                    Revoke
+                  </Button>
+                </Table.Cell>
               </Table.Row>
-            </Table.Header>
-            <Table.Body>
-              {grants.map((g) => (
-                <Table.Row key={g.principal}>
-                  <Table.Cell>{g.principal}</Table.Cell>
-                  <Table.Cell>{g.role}</Table.Cell>
-                  <Table.Cell>{g.resource}</Table.Cell>
-                  <Table.Cell>{g.expires}</Table.Cell>
-                  <Table.Cell>{g.granted_by}</Table.Cell>
-                  <Table.Cell isActions>
-                    <Button size="small" variant="secondary">
-                      Revoke
-                    </Button>
-                  </Table.Cell>
-                </Table.Row>
-              ))}
-            </Table.Body>
-          </Table.Root>
-        </Table.Container>
+            ))}
+          </Table.Body>
+        </Table.Root>
       </html.div>
     )
   },

package/src/components/Table/Table.tsx

@@ -445,7 +445,6 @@ export function HeaderCell({
   width: _width,
   compactWidth: _compactWidth,
   label: _label,
-  isActions,
   'aria-label': ariaLabel,
 }: {
   children?: ReactNode
@@ -465,20 +464,8 @@ export function HeaderCell({
    *  text content is used as the label automatically. Required when children
    *  contain JSX (icon + text, sort indicator, etc.). */
   label?: string
-  /**
-   * @deprecated Has no effect on HeaderCell. Pass `isActions` on the
-   * matching `Table.Cell` instead — that's where the stack-mode footer
-   * layout actually applies.
-   */
-  isActions?: boolean
   'aria-label'?: string
 }) {
-  if (isActions === true) {
-    devWarnOnce(
-      'headerCell-isActions',
-      'HeaderCell `isActions` prop has no effect and is deprecated. Pass `isActions` on the matching Table.Cell instead.',
-    )
-  }
   const {size, variant} = useTable()
   const {index, total} = useContext(CellIndexContext)
   const isLast = variant === 'bordered' && index === total - 1

package/src/components/Tabs/TabsContext.ts

@@ -1,6 +1,7 @@
 import {createContext, useContext} from 'react'
+import type {Orientation} from '../../shared/types'
 
-export type Orientation = 'horizontal' | 'vertical'
+export type {Orientation}
 
 export interface TabsContextValue {
   activeValue: string | null

package/src/components/Toast/ToastProvider.tsx

@@ -123,7 +123,7 @@ function ToastItem({entry, onDismiss}: {entry: ToastEntry; onDismiss: (id: strin
       style={[styles.toast, styles[variant]]}
     >
       <html.div style={[styles.iconWrap, variantIconStyle[variant]]}>
-        <Icon name={variantIcon[variant]} size={18} />
+        <Icon name={variantIcon[variant]} size="md" />
       </html.div>
       <html.div style={styles.content}>
         <html.div style={styles.message}>{message}</html.div>
@@ -146,7 +146,7 @@ function ToastItem({entry, onDismiss}: {entry: ToastEntry; onDismiss: (id: strin
         style={styles.closeBtn}
         onClick={() => onDismiss(id)}
       >
-        <Icon name="x-circle" size={16} />
+        <Icon name="x-circle" size="sm" />
       </html.button>
     </html.div>
   )

package/src/components/Toggle/Toggle.meta.ts

@@ -19,7 +19,7 @@ export const meta: ComponentMeta = {
   ],
   example: `// Standalone
 <Toggle pressed={isBold} onPressedChange={setIsBold} aria-label="Bold">
-  <Icon name="key" size={16} />
+  <Icon name="key" size="sm" />
 </Toggle>
 
 // In a group

package/src/components/ToggleGroup/ToggleGroupContext.ts

@@ -1,7 +1,8 @@
 import {createContext, useContext} from 'react'
 import type {ToggleSize} from '../Toggle/Toggle'
+import type {Orientation} from '../../shared/types'
 
-export type Orientation = 'horizontal' | 'vertical'
+export type {Orientation}
 
 export interface ToggleGroupContextValue {
   value: string[]

package/src/components/VirtualTable/VirtualTable.tsx

@@ -11,7 +11,7 @@ import {
   type Row,
 } from '@tanstack/react-table'
 import {useVirtualizer} from '@tanstack/react-virtual'
-import {breakpointsPx} from '@duro-app/tokens/tokens/breakpoints.css'
+import {breakpointsPx, type Breakpoint} from '@duro-app/tokens/tokens/breakpoints.css'
 import {styles} from './styles.css'
 
 // Measure + commit before paint on the client; no-op-safe on the server.
@@ -67,7 +67,7 @@ interface VirtualTableProps<TData> {
    * line. Cards disable windowing (variable heights), so keep phone lists
    * reasonably short. Set `responsive={false}` to disable entirely.
    */
-  stackBelow?: number
+  stackBelow?: Breakpoint | number
   /** Opt out of the card-up-on-narrow behavior. Default true. */
   responsive?: boolean
   emptyLabel?: ReactNode
@@ -98,7 +98,7 @@ export function VirtualTable<TData>({
   estimateRowHeight = 44,
   maxHeight = '70vh',
   virtualizeThreshold = 150,
-  stackBelow = breakpointsPx.sm,
+  stackBelow = 'sm',
   responsive = true,
   emptyLabel,
 }: VirtualTableProps<TData>) {
@@ -125,6 +125,7 @@ export function VirtualTable<TData>({
   // so `virtualize` is forced off while stacked.
   const wrapRef = useRef<HTMLDivElement>(null)
   const [stacked, setStacked] = useState(false)
+  const stackBelowPx = typeof stackBelow === 'number' ? stackBelow : breakpointsPx[stackBelow]
   useIsoLayoutEffect(() => {
     if (!responsive) {
       setStacked(false)
@@ -133,7 +134,7 @@ export function VirtualTable<TData>({
     const el = wrapRef.current
     if (!el || typeof ResizeObserver === 'undefined') return
     const apply = (width: number) => {
-      if (width > 0) setStacked(width < stackBelow)
+      if (width > 0) setStacked(width < stackBelowPx)
     }
     apply(el.getBoundingClientRect().width)
     const ro = new ResizeObserver((entries) => {
@@ -144,7 +145,7 @@ export function VirtualTable<TData>({
     })
     ro.observe(el)
     return () => ro.disconnect()
-  }, [responsive, stackBelow])
+  }, [responsive, stackBelowPx])
 
   const virtualize = rows.length > virtualizeThreshold && !stacked
 

package/src/hooks/useContainerQuery.ts

@@ -1,10 +1,15 @@
 import {useRef, useState, useEffect} from 'react'
+import {breakpointsPx, type Breakpoint} from '@duro-app/tokens/tokens/breakpoints.css'
 
 export type ContainerSize = 'compact' | 'default' | 'spacious'
 
 interface UseContainerQueryOptions {
-  compactBelow?: number
-  spaciousAbove?: number
+  compactBelow?: Breakpoint | number
+  spaciousAbove?: Breakpoint | number
+}
+
+function toPx(value: Breakpoint | number): number {
+  return typeof value === 'number' ? value : breakpointsPx[value]
 }
 
 export function useContainerQuery<T extends HTMLElement = HTMLElement>(
@@ -13,7 +18,9 @@ export function useContainerQuery<T extends HTMLElement = HTMLElement>(
   ref: React.RefObject<T | null>
   size: ContainerSize
 } {
-  const {compactBelow = 480, spaciousAbove = 768} = options
+  const {compactBelow: compactOpt = 'xs', spaciousAbove: spaciousOpt = 'md'} = options
+  const compactBelow = toPx(compactOpt)
+  const spaciousAbove = toPx(spaciousOpt)
   const ref = useRef<T | null>(null)
   const [size, setSize] = useState<ContainerSize>('default')
 

package/src/shared/types.ts

@@ -0,0 +1,3 @@
+// Cross-component prop types that don't belong to any single component.
+
+export type Orientation = 'horizontal' | 'vertical'