@duro-app/ui 0.16.0 → 0.17.1

package/package.json

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

package/src/components/ActionBar/ActionBar.tsx

@@ -13,6 +13,8 @@ export interface ActionBarProps {
   isEmphasized?: boolean
   /** Called when the clear/close button is pressed. */
   onClearSelection: () => void
+  /** Whether the bar can be dismissed. When false, the close button is hidden. @default true */
+  dismissible?: boolean
   /** Action buttons to display. */
   children: ReactNode
 }
@@ -22,6 +24,7 @@ function ActionBarInner({
   selectedLabel,
   isEmphasized = false,
   onClearSelection,
+  dismissible = true,
   children,
 }: ActionBarProps) {
   const container = useOverlayContainer()
@@ -42,21 +45,23 @@ function ActionBarInner({
       </html.span>
       <html.div style={[styles.separator, isEmphasized && styles.separatorEmphasized]} />
       <html.div style={styles.actions}>{children}</html.div>
-      <html.button
-        type="button"
-        aria-label="Clear selection"
-        onClick={onClearSelection}
-        style={[styles.closeButton, isEmphasized && styles.closeButtonEmphasized]}
-      >
-        <svg width={10} height={10} viewBox="0 0 10 10" fill="none" aria-hidden="true">
-          <path
-            d="M1 1l8 8M9 1l-8 8"
-            stroke="currentColor"
-            strokeWidth={1.5}
-            strokeLinecap="round"
-          />
-        </svg>
-      </html.button>
+      {dismissible && (
+        <html.button
+          type="button"
+          aria-label="Clear selection"
+          onClick={onClearSelection}
+          style={[styles.closeButton, isEmphasized && styles.closeButtonEmphasized]}
+        >
+          <svg width={10} height={10} viewBox="0 0 10 10" fill="none" aria-hidden="true">
+            <path
+              d="M1 1l8 8M9 1l-8 8"
+              stroke="currentColor"
+              strokeWidth={1.5}
+              strokeLinecap="round"
+            />
+          </svg>
+        </html.button>
+      )}
     </html.div>
   )
 

package/src/components/Button/Button.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Standard interactive button. For navigation (links styled as buttons), use LinkButton instead.',
+  whenToUse: [
+    'Triggering actions: submit, save, delete, open dialog',
+    'Primary and secondary actions in forms and toolbars',
+  ],
+  whenNotToUse: [
+    'Navigating to a URL — use LinkButton (renders <a>)',
+    'Toggling state — use Toggle',
+  ],
+  relatedTo: [
+    {component: 'LinkButton', relationship: 'LinkButton for navigation; Button for actions'},
+    {component: 'Toggle', relationship: 'Toggle for pressed/unpressed state'},
+  ],
+  example: `<Inline gap="sm">
+  <Button variant="primary" type="submit">Save</Button>
+  <Button variant="secondary">Cancel</Button>
+  <Button variant="danger">Delete</Button>
+</Inline>`,
+}

package/src/components/Checkbox/Checkbox.meta.ts

@@ -0,0 +1,21 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Checkbox input with optional visible label. Supports controlled and uncontrolled modes.',
+  whenToUse: [
+    'Boolean opt-in/opt-out (terms acceptance, feature toggle)',
+    'Multi-select from a list (inside a Fieldset)',
+  ],
+  whenNotToUse: [
+    'Binary toggle in settings — prefer Switch for on/off semantics',
+    'Selecting one of several options — use Select or ToggleGroup',
+  ],
+  relatedTo: [
+    {component: 'Switch', relationship: 'Switch for on/off settings; Checkbox for opt-in/selection'},
+    {component: 'Toggle', relationship: 'Toggle for toolbar actions; Checkbox for form input'},
+  ],
+  example: `<Checkbox name="terms" onChange={(e) => console.log(e.target.checked)}>
+  I agree to the terms and conditions
+</Checkbox>`,
+}

package/src/components/Cluster/Cluster.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Horizontal flex layout that WRAPS to the next line when items overflow.',
+  whenToUse: [
+    'Tags, badges, or chips that should wrap when they exceed the container width',
+    'Any set of inline elements with unknown/dynamic count',
+    'Filter pills, keyword lists, avatar groups',
+  ],
+  whenNotToUse: [
+    'Items that must stay on one line — use Inline',
+    'Vertical stacking — use Stack',
+  ],
+  relatedTo: [
+    {component: 'Inline', relationship: 'Same but does NOT wrap (nowrap)'},
+    {component: 'Stack', relationship: 'Vertical equivalent'},
+  ],
+  example: `<Cluster gap="xs">
+  <Badge>React</Badge>
+  <Badge>TypeScript</Badge>
+  <Badge>Design Systems</Badge>
+  <Badge>Accessibility</Badge>
+</Cluster>`,
+}

package/src/components/Field/Field.meta.ts

@@ -0,0 +1,37 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Compound form field with label, description, and error display. Inside Form, auto-binds to react-hook-form via name prop. Works standalone with manual invalid prop.',
+  whenToUse: [
+    'Any form input that needs a label and/or error message',
+    'Standalone labeled input (without Form) with manual error display',
+  ],
+  whenNotToUse: [
+    'Bare input without label — use Input directly (rare)',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Label', 'Description', 'Error'],
+  },
+  relatedTo: [
+    {component: 'Form', relationship: 'Field.Root auto-binds when name matches schema key'},
+    {component: 'Input', relationship: 'Place Input inside Field.Root'},
+    {component: 'Textarea', relationship: 'Place Textarea inside Field.Root'},
+    {component: 'Select', relationship: 'Place Select inside Field.Root'},
+  ],
+  example: `// Inside Form (auto-binds validation)
+<Field.Root name="email">
+  <Field.Label>Email</Field.Label>
+  <Input type="email" placeholder="you@example.com" />
+  <Field.Description>We'll never share your email.</Field.Description>
+  <Field.Error />
+</Field.Root>
+
+// Standalone (manual error)
+<Field.Root invalid>
+  <Field.Label>Email</Field.Label>
+  <Input variant="error" />
+  <Field.Error>This email is already taken.</Field.Error>
+</Field.Root>`,
+}

package/src/components/Field/Field.tsx

@@ -50,7 +50,16 @@ function ControlledRoot({
       },
       errorMessage: fieldState.error?.message,
     }),
-    [id, invalid, field.value, field.onChange, field.onBlur, field.ref, field.name, fieldState.error],
+    [
+      id,
+      invalid,
+      field.value,
+      field.onChange,
+      field.onBlur,
+      field.ref,
+      field.name,
+      fieldState.error,
+    ],
   )
 
   return (

package/src/components/Fieldset/Fieldset.meta.ts

@@ -0,0 +1,38 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Groups related form controls with consistent gap spacing and an optional legend. Supports disabled cascade.',
+  whenToUse: [
+    'Grouping related fields within a form (e.g., "Personal Info", "Address")',
+    'Applying consistent vertical gap between form fields',
+  ],
+  whenNotToUse: [
+    'Non-form content grouping — use Stack or Card',
+  ],
+  anatomy: {
+    required: ['Root'],
+    optional: ['Legend'],
+  },
+  relatedTo: [
+    {component: 'Form', relationship: 'Fieldset.Root goes inside Form'},
+    {component: 'Field', relationship: 'Field.Root goes inside Fieldset.Root'},
+    {component: 'Stack', relationship: 'Similar vertical spacing, but Fieldset has form semantics'},
+  ],
+  example: `<Form schema={schema} defaultValues={defaults} onSubmit={onSubmit}>
+  <Fieldset.Root gap="md">
+    <Fieldset.Legend>Account Details</Fieldset.Legend>
+    <Field.Root name="email">
+      <Field.Label>Email</Field.Label>
+      <Input type="email" />
+      <Field.Error />
+    </Field.Root>
+    <Field.Root name="password">
+      <Field.Label>Password</Field.Label>
+      <Input type="password" />
+      <Field.Error />
+    </Field.Root>
+    <Button type="submit">Create account</Button>
+  </Fieldset.Root>
+</Form>`,
+}

package/src/components/Form/Form.meta.ts

@@ -0,0 +1,38 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Form wrapper with Effect Schema validation and react-hook-form integration. Provides FormContext to child Field components.',
+  whenToUse: [
+    'Any form that needs validation',
+    'Multi-field forms with submit handling',
+  ],
+  whenNotToUse: [
+    'Single standalone field without validation — use Field.Root directly',
+    'Non-form interactive UIs — use individual components',
+  ],
+  relatedTo: [
+    {component: 'Field', relationship: 'Field.Root auto-binds to Form via name prop'},
+    {component: 'Fieldset', relationship: 'Groups fields visually within a Form'},
+  ],
+  example: `import {Schema} from 'effect'
+
+const MySchema = Schema.Struct({
+  email: Schema.String.pipe(
+    Schema.pattern(/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/, {message: () => 'Invalid email'}),
+  ),
+})
+
+<Form schema={MySchema} defaultValues={{email: ''}} onSubmit={handleSubmit}>
+  {({formState}) => (
+    <Fieldset.Root gap="md">
+      <Field.Root name="email">
+        <Field.Label>Email</Field.Label>
+        <Input type="email" />
+        <Field.Error />
+      </Field.Root>
+      <Button type="submit" disabled={!formState.isValid}>Submit</Button>
+    </Fieldset.Root>
+  )}
+</Form>`,
+}

package/src/components/Form/Form.stories.tsx

@@ -93,11 +93,7 @@ export const ValidationOnBlur: Story = {
   name: 'Validation — on blur',
   render: () => (
     <html.div style={wrapStyles.wrap}>
-      <Form
-        schema={LoginSchema}
-        defaultValues={{username: '', password: ''}}
-        onSubmit={fn()}
-      >
+      <Form schema={LoginSchema} defaultValues={{username: '', password: ''}} onSubmit={fn()}>
         <Fieldset.Root gap="md">
           <Field.Root name="username">
             <Field.Label>Username</Field.Label>
@@ -131,10 +127,13 @@ export const ValidationOnBlur: Story = {
       await expect(alert).toHaveTextContent('Username must be at least 3 characters')
     })
 
-    await step('Fix username by typing more — error clears (reValidateMode: onChange)', async () => {
-      await userEvent.type(usernameInput, 'c') // now "abc"
-      expect(canvas.queryByText('Username must be at least 3 characters')).not.toBeInTheDocument()
-    })
+    await step(
+      'Fix username by typing more — error clears (reValidateMode: onChange)',
+      async () => {
+        await userEvent.type(usernameInput, 'c') // now "abc"
+        expect(canvas.queryByText('Username must be at least 3 characters')).not.toBeInTheDocument()
+      },
+    )
 
     await step('Blur empty password — error appears', async () => {
       await userEvent.click(passwordInput)
@@ -150,11 +149,7 @@ export const WithTextarea: Story = {
   name: 'With Textarea',
   render: () => (
     <html.div style={wrapStyles.wrap}>
-      <Form
-        schema={FeedbackSchema}
-        defaultValues={{email: '', message: ''}}
-        onSubmit={fn()}
-      >
+      <Form schema={FeedbackSchema} defaultValues={{email: '', message: ''}} onSubmit={fn()}>
         {({formState}) => (
           <Fieldset.Root gap="md">
             <Field.Root name="email">
@@ -193,11 +188,7 @@ export const SuccessfulSubmit: Story = {
     const onSubmit = fn()
     return (
       <html.div style={wrapStyles.wrap}>
-        <Form
-          schema={LoginSchema}
-          defaultValues={{username: '', password: ''}}
-          onSubmit={onSubmit}
-        >
+        <Form schema={LoginSchema} defaultValues={{username: '', password: ''}} onSubmit={onSubmit}>
           <Fieldset.Root gap="md">
             <Field.Root name="username">
               <Field.Label>Username</Field.Label>

package/src/components/Grid/Grid.meta.ts

@@ -0,0 +1,30 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'CSS grid layout. Supports fixed column count (1-6) or responsive auto-fit via minColumnWidth.',
+  whenToUse: [
+    'Card grids, dashboard layouts, multi-column forms',
+    'Responsive layouts that should auto-adjust column count',
+  ],
+  whenNotToUse: [
+    'Single-column vertical layout — use Stack',
+    'Simple horizontal row — use Inline or Cluster',
+  ],
+  relatedTo: [
+    {component: 'Stack', relationship: 'Single-column vertical layout'},
+  ],
+  example: `// Responsive: columns auto-fit based on min width
+<Grid minColumnWidth="280px" gap="md">
+  <Card>A</Card>
+  <Card>B</Card>
+  <Card>C</Card>
+</Grid>
+
+// Fixed: always 3 columns
+<Grid columns={3} gap="md">
+  <Card>A</Card>
+  <Card>B</Card>
+  <Card>C</Card>
+</Grid>`,
+}

package/src/components/Inline/Inline.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Horizontal flex layout with NO wrapping. Items stay on one line and may overflow.',
+  whenToUse: [
+    'Toolbar or button group that must stay on one row',
+    'Horizontal alignment of a known, small number of items',
+    'Icon + text pairs, breadcrumbs, action rows',
+  ],
+  whenNotToUse: [
+    'Items that should wrap to the next line — use Cluster',
+    'Vertical stacking — use Stack',
+  ],
+  relatedTo: [
+    {component: 'Cluster', relationship: 'Same but wraps to next line'},
+    {component: 'Stack', relationship: 'Vertical equivalent'},
+  ],
+  example: `<Inline gap="sm" align="center">
+  <Button>Save</Button>
+  <Button variant="secondary">Cancel</Button>
+</Inline>`,
+}

package/src/components/Input/Input.meta.ts

@@ -0,0 +1,23 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Text input with automatic Field/Form integration. Variant auto-switches to error when inside an invalid Field.',
+  whenToUse: [
+    'Single-line text entry (text, email, password, url, tel, number, search)',
+  ],
+  whenNotToUse: [
+    'Multi-line text — use Textarea',
+    'Picking from predefined options — use Select',
+  ],
+  relatedTo: [
+    {component: 'Field', relationship: 'Wrap in Field.Root for label + error'},
+    {component: 'InputGroup', relationship: 'Wrap in InputGroup.Root for prefix/suffix addons'},
+    {component: 'Textarea', relationship: 'Multi-line variant'},
+  ],
+  example: `<Field.Root name="email">
+  <Field.Label>Email</Field.Label>
+  <Input type="email" placeholder="you@example.com" autoComplete="email" />
+  <Field.Error />
+</Field.Root>`,
+}

package/src/components/LinkButton/LinkButton.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Button-styled hyperlink. Renders an <a> tag, not a <button>. Use for navigation, not actions.',
+  whenToUse: [
+    'Navigation that should look like a button (e.g., "Get started", "View all")',
+    'Links to external pages with button styling',
+  ],
+  whenNotToUse: [
+    'Triggering in-page actions — use Button',
+    'Plain text links — use a styled <a> tag',
+  ],
+  relatedTo: [
+    {component: 'Button', relationship: 'Button for actions; LinkButton for navigation'},
+  ],
+  example: `<LinkButton href="/signup" variant="primary">
+  Get started
+</LinkButton>
+
+<LinkButton href="https://docs.example.com" target="_blank" variant="secondary">
+  Read the docs
+</LinkButton>`,
+}

package/src/components/Menu/Menu.meta.ts

@@ -0,0 +1,33 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Dropdown action menu. Triggers actions (not value selection). Compound component — Root is required (throws without it).',
+  whenToUse: [
+    'Context menu or "more actions" dropdown',
+    'Navigation links in a dropdown',
+    'Overflow menu for toolbar actions',
+  ],
+  whenNotToUse: [
+    'Picking a value — use Select',
+    'Primary navigation — use SideNav or Tabs',
+  ],
+  anatomy: {
+    required: ['Root', 'Trigger', 'Popup', 'Item'],
+    optional: ['LinkItem'],
+  },
+  relatedTo: [
+    {component: 'Select', relationship: 'Select picks values; Menu triggers actions'},
+    {component: 'Button', relationship: 'Often used as Menu.Trigger content'},
+  ],
+  example: `<Menu.Root>
+  <Menu.Trigger>
+    <Button variant="secondary">Actions</Button>
+  </Menu.Trigger>
+  <Menu.Popup>
+    <Menu.Item onClick={() => console.log('edit')}>Edit</Menu.Item>
+    <Menu.Item onClick={() => console.log('duplicate')}>Duplicate</Menu.Item>
+    <Menu.LinkItem href="/settings">Settings</Menu.LinkItem>
+  </Menu.Popup>
+</Menu.Root>`,
+}

package/src/components/PageShell/PageShell.meta.ts

@@ -0,0 +1,24 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Page-level layout wrapper. Centers content with max-width, padding, and an optional sticky header.',
+  whenToUse: [
+    'Top-level page layout',
+    'Any full-page view that needs centered content with consistent padding',
+  ],
+  whenNotToUse: [
+    'Nested section layouts — use Stack or Card',
+    'Sidebar layouts — combine with SideNav manually',
+  ],
+  relatedTo: [
+    {component: 'Stack', relationship: 'Use Stack for content within PageShell'},
+    {component: 'SideNav', relationship: 'Often placed alongside PageShell'},
+  ],
+  example: `<PageShell maxWidth="lg" padding="md" header={<Heading level={1}>Dashboard</Heading>}>
+  <Stack gap="lg">
+    <Card>Content section 1</Card>
+    <Card>Content section 2</Card>
+  </Stack>
+</PageShell>`,
+}

package/src/components/ScrollArea/ScrollArea.meta.ts

@@ -0,0 +1,27 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Custom scrollbar region with draggable thumb. Supports vertical and horizontal scrolling. Compound component — Root is required.',
+  whenToUse: [
+    'Custom-styled scrollbars for content overflow areas',
+    'Chat logs, code blocks, or long lists with constrained height',
+  ],
+  whenNotToUse: [
+    'Simple page-level scrolling — browser scroll is fine',
+    'Very short content that never overflows',
+  ],
+  anatomy: {
+    required: ['Root', 'Viewport', 'Content', 'Scrollbar', 'Thumb'],
+  },
+  example: `<ScrollArea.Root>
+  <ScrollArea.Viewport maxHeight={300}>
+    <ScrollArea.Content>
+      {/* Long content here */}
+    </ScrollArea.Content>
+  </ScrollArea.Viewport>
+  <ScrollArea.Scrollbar orientation="vertical">
+    <ScrollArea.Thumb orientation="vertical" />
+  </ScrollArea.Scrollbar>
+</ScrollArea.Root>`,
+}

package/src/components/Select/Select.meta.ts

@@ -0,0 +1,34 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it).',
+  whenToUse: [
+    'User must pick one option from a predefined list',
+    'Form field for country, category, role selection',
+  ],
+  whenNotToUse: [
+    'Triggering actions — use Menu',
+    'Multiple selections — use ToggleGroup or Checkbox group',
+    'Fewer than 3 options — consider Toggle or ToggleGroup',
+  ],
+  anatomy: {
+    required: ['Root', 'Trigger', 'Popup', 'Item'],
+    optional: ['Value', 'Icon', 'ItemText'],
+  },
+  relatedTo: [
+    {component: 'Menu', relationship: 'Menu triggers actions; Select picks a value'},
+    {component: 'ToggleGroup', relationship: 'For visible, small option sets'},
+  ],
+  example: `<Select.Root name="role" defaultValue="viewer">
+  <Select.Trigger>
+    <Select.Value placeholder="Select role" />
+    <Select.Icon />
+  </Select.Trigger>
+  <Select.Popup>
+    <Select.Item value="admin">Admin</Select.Item>
+    <Select.Item value="editor">Editor</Select.Item>
+    <Select.Item value="viewer">Viewer</Select.Item>
+  </Select.Popup>
+</Select.Root>`,
+}

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

@@ -0,0 +1,31 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Vertical side navigation with collapsible groups. Supports controlled and uncontrolled active item. Compound component — Root is required.',
+  whenToUse: [
+    'App-level sidebar navigation',
+    'Settings navigation with grouped sections',
+  ],
+  whenNotToUse: [
+    'In-page content switching — use Tabs',
+    'Top-level horizontal nav — use Inline with LinkButton',
+  ],
+  anatomy: {
+    required: ['Root', 'Group', 'Item'],
+  },
+  relatedTo: [
+    {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
+    {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
+  ],
+  example: `<SideNav.Root defaultValue="dashboard">
+  <SideNav.Group label="Main">
+    <SideNav.Item value="dashboard">Dashboard</SideNav.Item>
+    <SideNav.Item value="analytics">Analytics</SideNav.Item>
+  </SideNav.Group>
+  <SideNav.Group label="Settings" defaultExpanded={false}>
+    <SideNav.Item value="profile">Profile</SideNav.Item>
+    <SideNav.Item value="billing">Billing</SideNav.Item>
+  </SideNav.Group>
+</SideNav.Root>`,
+}

package/src/components/Stack/Stack.meta.ts

@@ -0,0 +1,22 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Vertical flex layout. Stacks children top-to-bottom with consistent gap.',
+  whenToUse: [
+    'Vertically stacking form fields, cards, or sections',
+    'Any column-direction layout with uniform spacing',
+  ],
+  whenNotToUse: [
+    'Horizontal layouts — use Inline (no wrap) or Cluster (wraps)',
+    'Grid layouts — use Grid',
+  ],
+  relatedTo: [
+    {component: 'Inline', relationship: 'Horizontal equivalent (no wrap)'},
+    {component: 'Cluster', relationship: 'Horizontal equivalent (wraps)'},
+  ],
+  example: `<Stack gap="md" align="stretch">
+  <Card>First</Card>
+  <Card>Second</Card>
+</Stack>`,
+}

package/src/components/Switch/Switch.meta.ts

@@ -0,0 +1,25 @@
+import type {ComponentMeta} from '../component-meta'
+
+export const meta: ComponentMeta = {
+  description:
+    'Toggle switch for on/off settings. Renders a hidden checkbox for form submission + a styled switch button.',
+  whenToUse: [
+    'On/off toggles in settings (notifications, dark mode, feature flags)',
+    'Immediate-effect toggles where the change applies instantly',
+  ],
+  whenNotToUse: [
+    'Form opt-in checkboxes — use Checkbox',
+    'Selecting between multiple options — use Select or ToggleGroup',
+  ],
+  relatedTo: [
+    {component: 'Checkbox', relationship: 'Checkbox for selection/opt-in; Switch for on/off settings'},
+    {component: 'Toggle', relationship: 'Toggle for toolbar pressed state; Switch for settings'},
+  ],
+  example: `<Switch
+  name="notifications"
+  defaultChecked={true}
+  onCheckedChange={(checked) => console.log(checked)}
+>
+  Enable notifications
+</Switch>`,
+}