@duro-app/ui 1.3.0 → 1.4.0

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

@@ -9,8 +9,16 @@ export const meta: ComponentMeta = {
     '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'},
+    {
+      component: 'Field',
+      kind: 'composition',
+      relationship: 'Field.Root auto-binds to Form via name prop',
+    },
+    {
+      component: 'Fieldset',
+      kind: 'composition',
+      relationship: 'Groups fields visually within a Form',
+    },
   ],
   example: `import {Schema} from 'effect'
 

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

@@ -11,7 +11,13 @@ export const meta: ComponentMeta = {
     'Single-column vertical layout — use Stack',
     'Simple horizontal row — use Inline or Cluster',
   ],
-  relatedTo: [{component: 'Stack', relationship: 'Single-column vertical layout'}],
+  relatedTo: [
+    {
+      component: 'Stack',
+      kind: 'contrast',
+      relationship: 'Grid for multi-column layouts; Stack for a single vertical column',
+    },
+  ],
   example: `// Responsive: columns auto-fit based on min width
 <Grid minColumnWidth="280px" gap="md">
   <Card>A</Card>

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

@@ -14,7 +14,11 @@ export const meta: ComponentMeta = {
     'Non-semantic bold text — use Text with weight',
   ],
   relatedTo: [
-    {component: 'Text', relationship: 'Text for body/label; Heading for semantic headings'},
+    {
+      component: 'Text',
+      kind: 'contrast',
+      relationship: 'Text for body/label; Heading for semantic headings',
+    },
   ],
   example: `<Stack gap="md">
   <Heading level={1}>Page Title</Heading>

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

@@ -12,6 +12,7 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'StatusIcon',
+      kind: 'composition',
       relationship: 'StatusIcon wraps Icon with a colored background circle',
     },
   ],

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

@@ -12,8 +12,16 @@ export const meta: ComponentMeta = {
     'Vertical stacking — use Stack',
   ],
   relatedTo: [
-    {component: 'Cluster', relationship: 'Same but wraps to next line'},
-    {component: 'Stack', relationship: 'Vertical equivalent'},
+    {
+      component: 'Cluster',
+      kind: 'contrast',
+      relationship: 'Cluster wraps when items overflow; Inline stays on one row',
+    },
+    {
+      component: 'Stack',
+      kind: 'contrast',
+      relationship: 'Stack stacks vertically; Inline lays out horizontally on one row',
+    },
   ],
   example: `<Inline gap="sm" align="center">
   <Button>Save</Button>

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

@@ -6,9 +6,17 @@ export const meta: ComponentMeta = {
   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'},
+    {component: 'Field', kind: 'composition', relationship: 'Wrap in Field.Root for label + error'},
+    {
+      component: 'InputGroup',
+      kind: 'composition',
+      relationship: 'Wrap in InputGroup.Root for prefix/suffix addons',
+    },
+    {
+      component: 'Textarea',
+      kind: 'contrast',
+      relationship: 'Input for single-line entry; Textarea for multi-line',
+    },
   ],
   example: `<Field.Root name="email">
   <Field.Label>Email</Field.Label>

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

@@ -17,9 +17,14 @@ export const meta: ComponentMeta = {
     optional: ['Addon'],
   },
   relatedTo: [
-    {component: 'Input', relationship: 'InputGroup enhances Input with addons'},
+    {
+      component: 'Input',
+      kind: 'composition',
+      relationship: 'InputGroup enhances Input with addons',
+    },
     {
       component: 'Field',
+      kind: 'contrast',
       relationship: 'Field provides label/error; InputGroup provides visual addons',
     },
   ],

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

@@ -11,7 +11,13 @@ export const meta: ComponentMeta = {
     'Triggering in-page actions — use Button',
     'Plain text links — use a styled <a> tag',
   ],
-  relatedTo: [{component: 'Button', relationship: 'Button for actions; LinkButton for navigation'}],
+  relatedTo: [
+    {
+      component: 'Button',
+      kind: 'contrast',
+      relationship: 'Button for actions; LinkButton for navigation',
+    },
+  ],
   example: `<LinkButton href="/signup" variant="primary">
   Get started
 </LinkButton>

package/src/components/List/List.meta.ts

@@ -20,11 +20,17 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'Table',
+      kind: 'contrast',
       relationship: 'Table for wide multi-column data; List for narrow compact items',
     },
-    {component: 'DetailPanel', relationship: 'List fits naturally inside DetailPanel.Body'},
+    {
+      component: 'DetailPanel',
+      kind: 'composition',
+      relationship: 'List fits naturally inside DetailPanel.Body',
+    },
     {
       component: 'Menu',
+      kind: 'contrast',
       relationship: 'Menu for action menus; List for data display with selection',
     },
   ],

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

@@ -14,8 +14,12 @@ export const meta: ComponentMeta = {
     optional: ['LinkItem'],
   },
   relatedTo: [
-    {component: 'Select', relationship: 'Select picks values; Menu triggers actions'},
-    {component: 'Button', relationship: 'Often used as Menu.Trigger content'},
+    {
+      component: 'Select',
+      kind: 'contrast',
+      relationship: 'Select picks values; Menu triggers actions',
+    },
+    {component: 'Button', kind: 'composition', relationship: 'Often used as Menu.Trigger content'},
   ],
   example: `<Menu.Root>
   <Menu.Trigger>

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

@@ -12,8 +12,12 @@ export const meta: ComponentMeta = {
     'Sidebar layouts — combine with SideNav manually',
   ],
   relatedTo: [
-    {component: 'Stack', relationship: 'Use Stack for content within PageShell'},
-    {component: 'SideNav', relationship: 'Often placed alongside PageShell'},
+    {
+      component: 'Stack',
+      kind: 'composition',
+      relationship: 'Use Stack for content within PageShell',
+    },
+    {component: 'SideNav', kind: 'composition', relationship: 'Often placed alongside PageShell'},
   ],
   example: `<PageShell maxWidth="lg" padding="md" header={<Heading level={1}>Dashboard</Heading>}>
   <Stack gap="lg">

package/src/components/Panel/Panel.meta.ts

@@ -20,14 +20,12 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'Card',
+      kind: 'contrast',
       relationship: 'Card is for shallow, repeated items; Panel is for deep, organized content',
     },
-    {
-      component: 'DetailPanel',
-      relationship: 'DetailPanel uses Panel internally for its structural layout',
-    },
     {
       component: 'PageShell',
+      kind: 'contrast',
       relationship: 'PageShell is for page-level layout; Panel is for section-level',
     },
   ],

package/src/components/RadioGroup/RadioGroup.meta.ts

@@ -15,10 +15,20 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'CheckboxGroup',
+      kind: 'contrast',
       relationship: 'CheckboxGroup for multi-select; RadioGroup for single-select',
     },
-    {component: 'Select', relationship: 'Select for larger option sets or when space is limited'},
-    {component: 'ToggleGroup', relationship: 'ToggleGroup for toolbar-style selection'},
+    {
+      component: 'Select',
+      kind: 'contrast',
+      relationship: 'RadioGroup keeps 2-5 options visible; Select for larger sets or tight space',
+    },
+    {
+      component: 'ToggleGroup',
+      kind: 'contrast',
+      relationship:
+        'RadioGroup for form single-select; ToggleGroup for segmented/toolbar single-select',
+    },
   ],
   example: `<RadioGroup.Root defaultValue="email" onValueChange={(v) => console.log(v)}>
   <RadioGroup.Item value="email">Email</RadioGroup.Item>

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

@@ -17,8 +17,16 @@ export const meta: ComponentMeta = {
     optional: ['Value', 'Icon', 'ItemText'],
   },
   relatedTo: [
-    {component: 'Menu', relationship: 'Menu triggers actions; Select picks a value'},
-    {component: 'ToggleGroup', relationship: 'For visible, small option sets'},
+    {
+      component: 'Menu',
+      kind: 'contrast',
+      relationship: 'Menu triggers actions; Select picks a value',
+    },
+    {
+      component: 'ToggleGroup',
+      kind: 'contrast',
+      relationship: 'Select hides options behind a dropdown; ToggleGroup keeps a small set visible',
+    },
   ],
   example: `<Select.Root name="role" defaultValue="viewer">
   <Select.Trigger>

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

@@ -20,8 +20,12 @@ export const meta: ComponentMeta = {
     optional: ['Section', 'Group'],
   },
   relatedTo: [
-    {component: 'Tabs', relationship: 'Tabs switch content in-place; SideNav navigates pages'},
-    {component: 'PageShell', relationship: 'Often placed alongside PageShell'},
+    {
+      component: 'Tabs',
+      kind: 'contrast',
+      relationship: 'Tabs switch content in-place; SideNav navigates pages',
+    },
+    {component: 'PageShell', kind: 'composition', relationship: 'Often placed alongside PageShell'},
   ],
   example: `<SideNav.Root defaultValue="identities">
   {/* Default: always-open sections. Nothing is a click away from being seen. */}

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

@@ -11,8 +11,16 @@ export const meta: ComponentMeta = {
     'Grid layouts — use Grid',
   ],
   relatedTo: [
-    {component: 'Inline', relationship: 'Horizontal equivalent (no wrap)'},
-    {component: 'Cluster', relationship: 'Horizontal equivalent (wraps)'},
+    {
+      component: 'Inline',
+      kind: 'contrast',
+      relationship: 'Stack stacks vertically; Inline lays out horizontally on one row',
+    },
+    {
+      component: 'Cluster',
+      kind: 'contrast',
+      relationship: 'Stack stacks vertically; Cluster lays out horizontally and wraps',
+    },
   ],
   example: `<Stack gap="md" align="stretch">
   <Card>First</Card>

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

@@ -10,8 +10,16 @@ export const meta: ComponentMeta = {
   ],
   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'},
+    {
+      component: 'Icon',
+      kind: 'composition',
+      relationship: 'StatusIcon wraps Icon with a colored background circle',
+    },
+    {
+      component: 'Badge',
+      kind: 'contrast',
+      relationship: 'Badge for text status; StatusIcon for icon status',
+    },
   ],
   example: `<Inline gap="md">
   <StatusIcon name="check-circle" variant="success" size="md" />

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

@@ -14,9 +14,14 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'Checkbox',
+      kind: 'contrast',
       relationship: 'Checkbox for selection/opt-in; Switch for on/off settings',
     },
-    {component: 'Toggle', relationship: 'Toggle for toolbar pressed state; Switch for settings'},
+    {
+      component: 'Toggle',
+      kind: 'contrast',
+      relationship: 'Toggle for toolbar pressed state; Switch for settings',
+    },
   ],
   example: `<Switch
   name="notifications"

package/src/components/Table/Table.meta.ts

@@ -15,7 +15,11 @@ export const meta: ComponentMeta = {
     required: ['Root', 'Header', 'Body', 'Row', 'HeaderCell', 'Cell'],
   },
   relatedTo: [
-    {component: 'ScrollArea', relationship: 'Wrap Table in ScrollArea for horizontal overflow'},
+    {
+      component: 'ScrollArea',
+      kind: 'composition',
+      relationship: 'Wrap Table in ScrollArea for horizontal overflow',
+    },
   ],
   example: `<Table.Root variant="striped" size="md" columns={3}>
   <Table.Header>

package/src/components/Tabs/Tabs.meta.ts

@@ -16,7 +16,11 @@ export const meta: ComponentMeta = {
     required: ['Root', 'List', 'Tab', 'Panel'],
   },
   relatedTo: [
-    {component: 'SideNav', relationship: 'For persistent navigation, not content switching'},
+    {
+      component: 'SideNav',
+      kind: 'contrast',
+      relationship: 'Tabs switch content in-place; SideNav navigates between pages',
+    },
   ],
   example: `<Tabs.Root defaultValue="general">
   <Tabs.List>

package/src/components/Tag/Tag.meta.ts

@@ -13,8 +13,16 @@ export const meta: ComponentMeta = {
     'Toggleable selection — use Toggle or ToggleGroup',
   ],
   relatedTo: [
-    {component: 'Badge', relationship: 'Static display variant'},
-    {component: 'TagGroup', relationship: 'Wrap in TagGroup.Root for collection management'},
+    {
+      component: 'Badge',
+      kind: 'contrast',
+      relationship: 'Tag is interactive and removable; Badge is a static label',
+    },
+    {
+      component: 'TagGroup',
+      kind: 'composition',
+      relationship: 'Wrap in TagGroup.Root for collection management',
+    },
   ],
   example: `<Tag removable onRemove={() => console.log('removed')}>
   user@example.com

package/src/components/TagGroup/TagGroup.meta.ts

@@ -14,9 +14,17 @@ export const meta: ComponentMeta = {
     'Toggle-based selection — use ToggleGroup',
   ],
   relatedTo: [
-    {component: 'Tag', relationship: 'Tag is the item inside TagGroup.List'},
-    {component: 'Badge', relationship: 'Static display alternative'},
-    {component: 'Field', relationship: 'Wrap in Field.Root for label + description + error'},
+    {component: 'Tag', kind: 'composition', relationship: 'Tag is the item inside TagGroup.List'},
+    {
+      component: 'Badge',
+      kind: 'contrast',
+      relationship: 'TagGroup manages an editable collection; Badge is a static label',
+    },
+    {
+      component: 'Field',
+      kind: 'composition',
+      relationship: 'Wrap in Field.Root for label + description + error',
+    },
   ],
   example: `<TagGroup.Root name="emails" value={emails} onValueChange={setEmails}>
   <TagGroup.List aria-label="Emails">

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

@@ -13,7 +13,11 @@ export const meta: ComponentMeta = {
     'Form field labels — use Field.Label (auto-binds to form)',
   ],
   relatedTo: [
-    {component: 'Heading', relationship: 'Heading for semantic h1-h6; Text for body/label'},
+    {
+      component: 'Heading',
+      kind: 'contrast',
+      relationship: 'Heading for semantic h1-h6; Text for body/label',
+    },
   ],
   example: `<Stack gap="xs">
   <Text variant="label">Email</Text>

package/src/components/Textarea/Textarea.meta.ts

@@ -6,8 +6,12 @@ export const meta: ComponentMeta = {
   whenToUse: ['Multi-line text entry (comments, messages, descriptions)'],
   whenNotToUse: ['Single-line input — use Input'],
   relatedTo: [
-    {component: 'Input', relationship: 'Single-line variant'},
-    {component: 'Field', relationship: 'Wrap in Field.Root for label + error'},
+    {
+      component: 'Input',
+      kind: 'contrast',
+      relationship: 'Input for single-line entry; Textarea for multi-line',
+    },
+    {component: 'Field', kind: 'composition', relationship: 'Wrap in Field.Root for label + error'},
   ],
   example: `<Field.Root name="message">
   <Field.Label>Message</Field.Label>

package/src/components/Toast/Toast.meta.ts

@@ -16,10 +16,12 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'Alert',
+      kind: 'contrast',
       relationship: 'Alert for inline/in-form status; Toast for action results',
     },
     {
       component: 'ConfirmDialog',
+      kind: 'contrast',
       relationship: 'ConfirmDialog gates a destructive action; Toast reports the outcome',
     },
   ],

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

@@ -13,9 +13,17 @@ export const meta: ComponentMeta = {
     'Submitting actions — use Button',
   ],
   relatedTo: [
-    {component: 'ToggleGroup', relationship: 'Group of Toggles with single/multi select'},
-    {component: 'Switch', relationship: 'Switch for settings; Toggle for toolbar actions'},
-    {component: 'Button', relationship: 'Button for actions; Toggle for state'},
+    {
+      component: 'ToggleGroup',
+      kind: 'composition',
+      relationship: 'Group of Toggles with single/multi select',
+    },
+    {
+      component: 'Switch',
+      kind: 'contrast',
+      relationship: 'Switch for settings; Toggle for toolbar actions',
+    },
+    {component: 'Button', kind: 'contrast', relationship: 'Button for actions; Toggle for state'},
   ],
   example: `// Standalone
 <Toggle pressed={isBold} onPressedChange={setIsBold} aria-label="Bold">

package/src/components/ToggleGroup/ToggleGroup.meta.ts

@@ -13,8 +13,12 @@ export const meta: ComponentMeta = {
     'Form checkboxes — use Checkbox group in Fieldset',
   ],
   relatedTo: [
-    {component: 'Toggle', relationship: 'Toggle children get group context'},
-    {component: 'Select', relationship: 'Select for larger option sets'},
+    {component: 'Toggle', kind: 'composition', relationship: 'Toggle children get group context'},
+    {
+      component: 'Select',
+      kind: 'contrast',
+      relationship: 'Select hides options behind a dropdown; ToggleGroup keeps a small set visible',
+    },
   ],
   example: `<ToggleGroup
   value={selected}

package/src/components/VirtualTable/VirtualTable.meta.ts

@@ -26,6 +26,7 @@ export const meta: ComponentMeta = {
   relatedTo: [
     {
       component: 'Table',
+      kind: 'contrast',
       relationship: 'Table is semantic + paginated; VirtualTable windows large lists',
     },
   ],

package/src/components/component-meta.ts

@@ -3,6 +3,21 @@ export interface ComponentMeta {
   whenToUse: string[]
   whenNotToUse: string[]
   anatomy?: {required: string[]; optional?: string[]}
-  relatedTo?: Array<{component: string; relationship: string}>
+  /**
+   * Neighbouring components and how they relate.
+   *
+   * `kind` is required because the two relationships are not interchangeable
+   * and tooling has to tell them apart: `contrast` means the two are
+   * alternatives you pick BETWEEN ("Switch for on/off settings; Checkbox for
+   * opt-in"), `composition` means one goes INSIDE the other ("Place Input
+   * inside Field.Root"). The session-start catalog surfaces the contrast half
+   * as a wrong-pick guard, so an edge filed under the wrong kind quietly
+   * either disappears from it or pollutes it.
+   */
+  relatedTo?: Array<{
+    component: string
+    kind: 'contrast' | 'composition'
+    relationship: string
+  }>
   example: string
 }