@duro-app/ui 0.20.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/ui",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,7 @@
     }
   },
   "dependencies": {
-    "@duro-app/tokens": "^0.20.0"
+    "@duro-app/tokens": "^0.21.0"
   },
   "devDependencies": {
     "@babel/preset-typescript": "^7.28.0",

package/src/components/ActionBar/ActionBar.meta.ts

@@ -0,0 +1,20 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Floating toolbar that appears at the bottom of the viewport when items are selected. Shows selection count and bulk actions. Animates in/out. Use with Table checkboxes for bulk operations.',
+  whenToUse: [
+    'Bulk actions on table selections (delete, revoke, export)',
+    'Multi-select workflows where actions apply to all selected items',
+  ],
+  whenNotToUse: [
+    'Single-item actions — use inline buttons or a Menu',
+    'Persistent toolbars — use Inline with buttons',
+  ],
+  relatedTo: [
+    {component: 'Table', relationship: 'Common pattern: Table checkboxes + ActionBar for bulk ops'},
+  ],
+  example: `<ActionBar selectedItemCount={selected.size} onClearSelection={() => setSelected(new Set())}>
+  <Button variant="danger" size="small" onClick={handleDelete}>Delete</Button>
+</ActionBar>`,
+}

package/src/components/Alert/Alert.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Inline status message with icon. Compact, single-line feedback for form validation results, API responses, or status updates. For block-level prominent messages, use Callout instead.',
+  whenToUse: [
+    'Form submission feedback (success, error)',
+    'API response status messages',
+    'Inline warnings or info notices',
+  ],
+  whenNotToUse: [
+    'Block-level prominent messages — use Callout',
+    'Toast notifications — use a toast system',
+    'Form field errors — use Field.Error',
+  ],
+  relatedTo: [
+    {component: 'Callout', relationship: 'Callout for larger block-level messages; Alert for compact inline'},
+  ],
+  example: `<Stack gap="sm">
+  <Alert variant="success">Settings saved successfully.</Alert>
+  <Alert variant="error">Failed to connect. Please retry.</Alert>
+  <Alert variant="warning">Your session expires in 5 minutes.</Alert>
+  <Alert variant="info">New version available.</Alert>
+</Stack>`,
+}

package/src/components/Badge/Badge.meta.ts

@@ -0,0 +1,20 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Small label or tag for status indicators, counts, or categories. Renders inline. Use for metadata annotations next to text or in table cells.',
+  whenToUse: [
+    'Status indicators (active, expired, pending)',
+    'Category tags or labels',
+    'Count indicators next to items',
+  ],
+  whenNotToUse: [
+    'Interactive toggleable tags — use Toggle or ToggleGroup',
+    'Long descriptive messages — use Alert or Callout',
+  ],
+  example: `<Inline gap="xs">
+  <Badge variant="success">Active</Badge>
+  <Badge variant="error">Expired</Badge>
+  <Badge variant="default">Draft</Badge>
+</Inline>`,
+}

package/src/components/Callout/Callout.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Block-level informational message with icon and colored background. More prominent than Alert. Use for important notices, onboarding tips, or contextual guidance that should stand out.',
+  whenToUse: [
+    'Important notices that need visual prominence',
+    'Onboarding tips or contextual guidance',
+    'Warning messages before destructive actions',
+  ],
+  whenNotToUse: [
+    'Compact inline feedback — use Alert',
+    'Form field errors — use Field.Error',
+    'Toast notifications — use a toast system',
+  ],
+  relatedTo: [
+    {component: 'Alert', relationship: 'Alert for compact inline; Callout for block-level prominent'},
+  ],
+  example: `<Callout variant="warning">
+  Your subscription expires in 3 days. Renew now to avoid service interruption.
+</Callout>`,
+}

package/src/components/Card/Card.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Container with visual styling (elevation, border, or fill). Groups related content with consistent spacing and background. For structural containers with Header/Body/Footer slots, use Panel instead.',
+  whenToUse: [
+    'Grouping related content visually (settings sections, dashboard widgets)',
+    'Clickable content cards with hover state (interactive variant)',
+    'Content containers with elevation or borders',
+  ],
+  whenNotToUse: [
+    'Structural containers with Header/Body/Footer — use Panel',
+    'Page-level layout — use PageShell',
+    'Simple spacing — use Stack or Inline',
+  ],
+  relatedTo: [
+    {component: 'Panel', relationship: 'Panel for structural Header/Body/Footer; Card for visual container'},
+  ],
+  example: `<Card variant="elevated" size="md">
+  <Stack gap="md">
+    <Heading level={3}>Account</Heading>
+    <Text>Manage your account settings.</Text>
+  </Stack>
+</Card>`,
+}

package/src/components/Dialog/Dialog.stories.tsx

@@ -177,9 +177,7 @@ function FormDialogDemo() {
           <Dialog.Title>Edit profile</Dialog.Title>
           <Dialog.Close />
         </Dialog.Header>
-        <Dialog.Description>
-          Update your display name and email address.
-        </Dialog.Description>
+        <Dialog.Description>Update your display name and email address.</Dialog.Description>
         <Dialog.Body>
           <Stack gap="md">
             <Field.Root>
@@ -270,8 +268,8 @@ export const NonDismissable: Story = {
         <Dialog.Body>
           <Stack gap="md">
             <Text>
-              You must accept the terms of service to continue. This dialog cannot be
-              dismissed by clicking outside or pressing Escape.
+              You must accept the terms of service to continue. This dialog cannot be dismissed by
+              clicking outside or pressing Escape.
             </Text>
             <Text variant="bodySm" color="muted">
               Try clicking the backdrop or pressing Escape — the dialog stays open.
@@ -309,8 +307,8 @@ function BackdropDismissDemo() {
           </Dialog.Header>
           <Dialog.Body>
             <Text>
-              Click the dark backdrop behind this dialog to dismiss it.
-              You can also press Escape or use the close button.
+              Click the dark backdrop behind this dialog to dismiss it. You can also press Escape or
+              use the close button.
             </Text>
           </Dialog.Body>
         </Dialog.Portal>

package/src/components/Dialog/Dialog.tsx

@@ -278,11 +278,7 @@ function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
   }
 
   return (
-    <html.button
-      onClick={requestClose}
-      aria-label={ariaLabel}
-      style={styles.closeButton}
-    >
+    <html.button onClick={requestClose} aria-label={ariaLabel} style={styles.closeButton}>
       <svg width={16} height={16} viewBox="0 0 16 16" fill="none">
         <path
           d="M4 4l8 8M12 4l-8 8"

package/src/components/Drawer/Drawer.stories.tsx

@@ -31,8 +31,8 @@ export const Default: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Text>
-            This drawer slides in from the right edge. It's useful for showing details,
-            settings panels, or supplementary content without leaving the current page.
+            This drawer slides in from the right edge. It's useful for showing details, settings
+            panels, or supplementary content without leaving the current page.
           </Text>
         </Drawer.Body>
         <Drawer.Footer>
@@ -93,9 +93,15 @@ export const BottomAnchor: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Stack gap="sm">
-            <Button variant="secondary" fullWidth>Share</Button>
-            <Button variant="secondary" fullWidth>Duplicate</Button>
-            <Button variant="danger" fullWidth>Delete</Button>
+            <Button variant="secondary" fullWidth>
+              Share
+            </Button>
+            <Button variant="secondary" fullWidth>
+              Duplicate
+            </Button>
+            <Button variant="danger" fullWidth>
+              Delete
+            </Button>
           </Stack>
         </Drawer.Body>
       </Drawer.Portal>
@@ -125,7 +131,10 @@ function SizesDemo() {
               <Drawer.Close />
             </Drawer.Header>
             <Drawer.Body>
-              <Text>This drawer uses the {s} size preset ({s === 'sm' ? '360' : s === 'md' ? '480' : '640'}px max-width).</Text>
+              <Text>
+                This drawer uses the {s} size preset (
+                {s === 'sm' ? '360' : s === 'md' ? '480' : '640'}px max-width).
+              </Text>
             </Drawer.Body>
             <Drawer.Footer>
               <Drawer.Close>
@@ -164,9 +173,7 @@ function FormDrawerDemo() {
           <Drawer.Title>Edit profile</Drawer.Title>
           <Drawer.Close />
         </Drawer.Header>
-        <Drawer.Description>
-          Update your account information below.
-        </Drawer.Description>
+        <Drawer.Description>Update your account information below.</Drawer.Description>
         <Drawer.Body>
           <Stack gap="md">
             <Field.Root>
@@ -269,8 +276,8 @@ export const NonDismissable: Story = {
         <Drawer.Body>
           <Stack gap="md">
             <Text>
-              This drawer cannot be dismissed by clicking the backdrop or pressing Escape.
-              You must use the explicit close action below.
+              This drawer cannot be dismissed by clicking the backdrop or pressing Escape. You must
+              use the explicit close action below.
             </Text>
             <Text variant="bodySm" color="muted">
               Try clicking outside or pressing Escape — nothing happens.
@@ -302,8 +309,8 @@ export const NoSwipeDismiss: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Text>
-            This bottom drawer has swipe-to-dismiss disabled. On mobile, you cannot
-            swipe down to close it — use the close button or tap the backdrop instead.
+            This bottom drawer has swipe-to-dismiss disabled. On mobile, you cannot swipe down to
+            close it — use the close button or tap the backdrop instead.
           </Text>
         </Drawer.Body>
       </Drawer.Portal>
@@ -326,12 +333,10 @@ export const SwipeDismiss: Story = {
         </Drawer.Header>
         <Drawer.Body>
           <Stack gap="md">
-            <Text>
-              Drag this drawer downward to dismiss it. The backdrop fades as you drag.
-            </Text>
+            <Text>Drag this drawer downward to dismiss it. The backdrop fades as you drag.</Text>
             <Text variant="bodySm" color="muted">
-              Swipe past 30% of the panel height or flick quickly to dismiss.
-              Otherwise it snaps back.
+              Swipe past 30% of the panel height or flick quickly to dismiss. Otherwise it snaps
+              back.
             </Text>
           </Stack>
         </Drawer.Body>
@@ -354,9 +359,7 @@ export const SwipeDismissRight: Story = {
           <Drawer.Close />
         </Drawer.Header>
         <Drawer.Body>
-          <Text>
-            Drag this panel to the right to dismiss it. Works with touch and mouse.
-          </Text>
+          <Text>Drag this panel to the right to dismiss it. Works with touch and mouse.</Text>
         </Drawer.Body>
       </Drawer.Portal>
     </Drawer.Root>

package/src/components/Drawer/Drawer.tsx

@@ -252,10 +252,7 @@ function Portal({children, size = 'md'}: PortalProps) {
       />
 
       {/* Viewport */}
-      <html.div
-        style={[styles.viewport, viewportAnchorMap[anchor]]}
-        data-drawer-viewport=""
-      >
+      <html.div style={[styles.viewport, viewportAnchorMap[anchor]]} data-drawer-viewport="">
         <html.div
           ref={panelRef}
           role="dialog"
@@ -338,11 +335,7 @@ function Close({children, 'aria-label': ariaLabel = 'Close'}: CloseProps) {
   }
 
   return (
-    <html.button
-      onClick={requestClose}
-      aria-label={ariaLabel}
-      style={styles.closeButton}
-    >
+    <html.button onClick={requestClose} aria-label={ariaLabel} style={styles.closeButton}>
       <svg width={16} height={16} viewBox="0 0 16 16" fill="none">
         <path
           d="M4 4l8 8M12 4l-8 8"

package/src/components/Drawer/useSwipeDismiss.ts

@@ -97,9 +97,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
 
         panelEl.style.transform = ''
         panelEl.style.boxShadow =
-          shadowSpread > 0
-            ? `0 0 ${shadowSpread * 2}px ${shadowSpread}px rgba(0, 0, 0, 0.15)`
-            : ''
+          shadowSpread > 0 ? `0 0 ${shadowSpread * 2}px ${shadowSpread}px rgba(0, 0, 0, 0.15)` : ''
       }
     },
     [anchor, isHorizontal],
@@ -255,8 +253,7 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
       }
 
       const fraction = movement / state.panelSize
-      const shouldDismiss =
-        fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
+      const shouldDismiss = fraction > DISMISS_THRESHOLD || velocity > VELOCITY_THRESHOLD
 
       if (shouldDismiss) {
         animateDismiss(panel!)
@@ -291,5 +288,15 @@ export function useSwipeDismiss({anchor, enabled, onDismiss, panelRef}: UseSwipe
       panel.removeEventListener('pointercancel', handlePointerCancel)
       panel.removeEventListener('touchmove', handleTouchMove)
     }
-  }, [enabled, panelRef, anchor, isHorizontal, getMovement, applyTransform, resetStyles, animateSnapBack, animateDismiss])
+  }, [
+    enabled,
+    panelRef,
+    anchor,
+    isHorizontal,
+    getMovement,
+    applyTransform,
+    resetStyles,
+    animateSnapBack,
+    animateDismiss,
+  ])
 }

package/src/components/EmptyState/EmptyState.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Placeholder for empty content areas. Shows an icon, message, and optional action button. Use when a list, table, or section has no data to display.',
+  whenToUse: [
+    'Empty tables or lists with no results',
+    'Search results with no matches',
+    'First-time use before any data exists',
+  ],
+  whenNotToUse: [
+    'Loading states — use Spinner',
+    'Error states — use Alert or Callout',
+  ],
+  example: `<Card>
+  <EmptyState
+    icon={<Icon name="info-circle" size={48} />}
+    message="No results found"
+    action={<Button variant="secondary">Clear filters</Button>}
+  />
+</Card>`,
+}

package/src/components/Heading/Heading.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Semantic heading element (h1-h6) with typography presets. Always use the correct level for document hierarchy. Visual size can differ from semantic level via the variant prop.',
+  whenToUse: [
+    'Page titles (level 1)',
+    'Section headers (level 2-3)',
+    'Card or panel titles (level 3-4)',
+  ],
+  whenNotToUse: [
+    'Body text — use Text',
+    'Form labels — use Field.Label',
+    'Non-semantic bold text — use Text with weight',
+  ],
+  relatedTo: [
+    {component: 'Text', relationship: 'Text for body/label; Heading for semantic headings'},
+  ],
+  example: `<Stack gap="md">
+  <Heading level={1}>Page Title</Heading>
+  <Heading level={2} variant="headingMd">Section</Heading>
+  <Heading level={3}>Subsection</Heading>
+</Stack>`,
+}

package/src/components/Icon/Icon.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'SVG icon component. Renders stroke or filled icons from the design system icon set. Size scales with the size prop. Use inside buttons, badges, or standalone.',
+  whenToUse: [
+    'Button icons (inside Button children)',
+    'Status indicators alongside text',
+    'Navigation or action indicators',
+  ],
+  whenNotToUse: [
+    'Decorative images — use img elements',
+    'Complex illustrations — use custom SVGs',
+  ],
+  relatedTo: [
+    {component: 'StatusIcon', relationship: 'StatusIcon wraps Icon with a colored background circle'},
+  ],
+  example: `<Inline gap="sm" align="center">
+  <Icon name="check-circle" size={20} />
+  <Icon name="alert-triangle" size={20} />
+  <Icon name="shield-filled" size={20} />
+</Inline>`,
+}

package/src/components/InputGroup/InputGroup.meta.ts

@@ -0,0 +1,28 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Wraps an Input with prefix and/or suffix addons (icons, text, buttons). Addons are visually attached to the input edges.',
+  whenToUse: [
+    'Inputs with units (e.g. "$" prefix, "kg" suffix)',
+    'Search inputs with an icon prefix',
+    'URL inputs with protocol prefix',
+  ],
+  whenNotToUse: [
+    'Standalone inputs without addons — use Input directly',
+    'Form field labels — use Field.Label',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Addon'],
+  },
+  relatedTo: [
+    {component: 'Input', relationship: 'InputGroup enhances Input with addons'},
+    {component: 'Field', relationship: 'Field provides label/error; InputGroup provides visual addons'},
+  ],
+  example: `<InputGroup.Root>
+  <InputGroup.Addon>$</InputGroup.Addon>
+  <Input type="number" placeholder="0.00" />
+  <InputGroup.Addon>USD</InputGroup.Addon>
+</InputGroup.Root>`,
+}

package/src/components/Spinner/Spinner.meta.ts

@@ -0,0 +1,19 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Animated loading indicator. Use while content is being fetched or an action is processing. Always provide a label for accessibility.',
+  whenToUse: [
+    'Page or section loading states',
+    'Button loading states (inside a button)',
+    'Async operation feedback',
+  ],
+  whenNotToUse: [
+    'Skeleton loading — use placeholder skeleton patterns',
+    'Progress with known completion — use a progress bar',
+  ],
+  example: `<Stack gap="md" align="center">
+  <Spinner size="lg" label="Loading data..." />
+  <Button disabled><Spinner size="sm" /> Saving...</Button>
+</Stack>`,
+}

package/src/components/StatusIcon/StatusIcon.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Icon with a colored background circle. Combines an Icon with a status-colored container for visual emphasis. Use for status indicators in dashboards or lists.',
+  whenToUse: [
+    'Dashboard status indicators',
+    'List item status icons with colored backgrounds',
+    'Feature or capability indicators',
+  ],
+  whenNotToUse: [
+    'Inline icons without background — use Icon',
+    'Status text labels — use Badge',
+  ],
+  relatedTo: [
+    {component: 'Icon', relationship: 'StatusIcon wraps Icon with background; Icon is bare SVG'},
+    {component: 'Badge', relationship: 'Badge for text status; StatusIcon for icon status'},
+  ],
+  example: `<Inline gap="md">
+  <StatusIcon name="check-circle" variant="success" size="md" />
+  <StatusIcon name="alert-triangle" variant="warning" size="md" />
+  <StatusIcon name="x-circle" variant="error" size="md" />
+</Inline>`,
+}

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

@@ -271,10 +271,7 @@ function CheckboxTableDemo() {
         </Table.Body>
       </Table.Root>
 
-      <ActionBar
-        selectedItemCount={selected.size}
-        onClearSelection={() => setSelected(new Set())}
-      >
+      <ActionBar selectedItemCount={selected.size} onClearSelection={() => setSelected(new Set())}>
         <Button variant="danger" size="small">
           Delete
         </Button>

package/src/components/Text/Text.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Body and label typography component. Renders a span or paragraph with design system typography presets. Use for all non-heading text content.',
+  whenToUse: [
+    'Body text (paragraphs, descriptions)',
+    'UI labels and metadata',
+    'Captions, code snippets, overlines',
+  ],
+  whenNotToUse: [
+    'Page or section titles — use Heading',
+    'Form field labels — use Field.Label (auto-binds to form)',
+  ],
+  relatedTo: [
+    {component: 'Heading', relationship: 'Heading for semantic h1-h6; Text for body/label'},
+  ],
+  example: `<Stack gap="xs">
+  <Text variant="label">Email</Text>
+  <Text variant="bodySm" color="muted">We will never share your email.</Text>
+  <Text variant="code">user@example.com</Text>
+</Stack>`,
+}

package/src/components/ThemeProvider/ThemeProvider.meta.ts

@@ -0,0 +1,16 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Theme context provider. Must wrap the entire app at the root level. Sets dark, light, or high-contrast theme for all child components via CSS custom properties.',
+  whenToUse: [
+    'App root — required for all Duro components to render correctly',
+    'Theme switching (dark/light mode toggle)',
+  ],
+  whenNotToUse: [
+    'Never omit — all Duro components require ThemeProvider',
+  ],
+  example: `<ThemeProvider theme="dark">
+  <App />
+</ThemeProvider>`,
+}

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

@@ -57,7 +57,8 @@ export const styles = css.create({
     borderRadius: 0,
     borderRightWidth: 1,
     borderRightStyle: 'solid',
-    borderRightColor: colors.border,
+    // Override any borderColor set by pressed state — dividers always use border token
+    borderColor: colors.border,
   },
   disabled: {
     opacity: 0.5,