@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/segmented-control.md

@@ -0,0 +1,181 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: segmented-control
+  sourceFile: packages/design-system/src/components/segmented-control.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: SegmentedControl
+      kind: component
+      typeText: "ForwardRefExoticComponent<SegmentedControlProps & RefAttributes<HTMLDivElement>>"
+    - name: SegmentedControlItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<SegmentedControlItemProps & RefAttributes<HTMLButtonElement>>"
+    - name: SegmentedControlItemProps
+      kind: type
+    - name: SegmentedControlProps
+      kind: type
+    - name: SegmentedControlSize
+      kind: type
+    - name: SegmentedControlVariant
+      kind: type
+  primaryExport: SegmentedControl
+  subcomponents:
+    - SegmentedControlItem
+  props:
+    SegmentedControl:
+      - name: fullWidth
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "When true, the control stretches to fill its container and each item takes an equal share of the width. Use for view toggles embedded in toolbars, modal footers, or any layout where the control should fill the available space rather than hug its content."
+      - name: size
+        type: SegmentedControlSize
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: transparent
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "When true, the track background is transparent (drops the `bg-muted` fill). Use when the control sits on an already-tinted surface."
+        variantKey: true
+      - name: variant
+        type: SegmentedControlVariant
+        required: false
+        declaredIn: self
+        doc: "Colour theme for the whole control: tints the track background (weak `{variant}`), the selected thumb's shadow (`{variant}-strong`), and the selected item's label (`{variant}-stronger`). Defaults to `neutral`."
+        variantKey: true
+  extendsProps:
+    - "Omit< React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>, \"orientation\" >"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: SegmentedControl
+    variant:
+      kind: enum
+      options:
+        - neutral
+        - primary
+        - secondary
+      default: neutral
+      on: SegmentedControl
+    transparent:
+      kind: boolean
+      default: false
+      on: SegmentedControl
+  variantSource: cva
+  compoundVariants:
+    - variant: neutral
+      transparent: false
+    - variant: primary
+      transparent: false
+    - variant: secondary
+      transparent: false
+  sizeMaps:
+    - activeLabelClass
+    - inactiveLabelClass
+    - variantBoxShadow
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-radio-group"
+      - class-variance-authority
+      - react
+  contexts:
+    - name: SegmentedControlContext
+      type: SegmentedControlContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-segmentedcontrol--default
+  storybookTitle: Components/SegmentedControl
+  docsId: components-segmentedcontrol--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a939d75e1fff
+  factsHash: d6aa68d42972
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A single-select, pill-style switch with a sliding indicator between segments, built on Radix RadioGroup."
+useWhen:
+  - "a small, fixed set of view modes or filters where the current selection should read as one connected control with a sliding highlight - a day/week/month toggle, a list/grid view switch"
+useInstead:
+  - id: button-group
+    when: "the row is a set of related actions or toggle buttons rather than exactly one persistent selection with a sliding indicator"
+  - id: radio-group
+    when: "the options read better as a stacked list, each with its own visible label, rather than a compact inline switch"
+  - id: tabs
+    when: "selecting an option also navigates between distinct content panels"
+related:
+  - button-group
+  - radio-group
+  - tabs
+tokens:
+  - "--card"
+  - "--muted"
+  - "--neutral-weakest"
+  - "--primary-weakest"
+  - "--secondary-weakest"
+  - "--primary"
+  - "--secondary"
+a11y:
+  notes:
+    - "Built on Radix RadioGroup, so it is a real single-select radio group under the hood - screen readers announce it as radio options, not tabs, even though it looks like a segmented switch."
+    - "The floating indicator div is aria-hidden - it is purely decorative positioning, not part of the accessible structure."
+  keyboard:
+    - "Native Radix radio-group keyboard behavior: arrow keys move the selection (and the sliding indicator) between items; Tab enters or exits the whole control once."
+  radixHandles: true
+pitfalls:
+  - "The sliding indicator's position is measured via getBoundingClientRect on mount and on value, children, or resize changes - conditionally rendering SegmentedControlItem children instead of always rendering all of them can leave the indicator momentarily unpositioned or animating from the wrong place."
+  - "variant only recolors the track, indicator, and label - it does not change size or spacing, so size and variant are chosen independently."
+  - "fullWidth makes every item share equal width via *:flex-1 - items with very different label lengths will look uneven in that mode, unlike the default hug-content sizing."
+  - "Reach for this only when there is exactly one persistent selection - button-group.md's useInstead already points here for that reason; a set of independent toggle buttons or actions belongs in ButtonGroup instead."
+canonicalSnippet: |
+  import { SegmentedControl, SegmentedControlItem } from "@adres/mgda-ui"
+
+  <SegmentedControl defaultValue="day">
+    <SegmentedControlItem value="day">Day</SegmentedControlItem>
+    <SegmentedControlItem value="week">Week</SegmentedControlItem>
+    <SegmentedControlItem value="month">Month</SegmentedControlItem>
+  </SegmentedControl>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: a939d75e1fff
+---
+
+## Usage
+
+`SegmentedControl` is a single-select switch that reads as one connected
+control with a sliding indicator behind the active item - a day/week/month
+toggle, a list/grid view switch. Reach for `ButtonGroup` instead when the row
+is a set of independent actions or toggle buttons rather than exactly one
+persistent selection, and `Tabs` when selecting an option also navigates
+between distinct content panels.
+
+`variant` (`neutral`/`primary`/`secondary`) tints the track, the selected
+item's shadow, and its label together - it does not affect size or spacing,
+so `size` and `variant` are chosen independently. Set `fullWidth` to stretch
+the control to fill its container with each item taking an equal share; set
+`transparent` to drop the track's background fill when the control sits on
+an already-tinted surface.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `SegmentedControl` | Root. Owns `size`, `variant`, `fullWidth`, `transparent`, and the selected `value`. Renders the floating indicator behind the active item. |
+| `SegmentedControlItem` | One segment. Registers itself with the root so the indicator can measure and animate to it. |

package/knowledge/select-button.md

@@ -0,0 +1,205 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: select-button
+  sourceFile: packages/design-system/src/components/select-button.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: SelectButton
+      kind: component
+      typeText: "ForwardRefExoticComponent<SelectButtonProps & RefAttributes<HTMLDivElement>>"
+    - name: SelectButtonProps
+      kind: type
+    - name: SelectButtonSize
+      kind: type
+    - name: SelectButtonVariant
+      kind: type
+  primaryExport: SelectButton
+  subcomponents: []
+  props:
+    SelectButton:
+      - name: buttonClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra className appended to the inner Button."
+      - name: buttonDisabled
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: buttonLabel
+        type: ReactNode
+        required: true
+        declaredIn: self
+      - name: buttonType
+        type: "\"button\" | \"reset\" | \"submit\""
+        required: false
+        declaredIn: self
+      - name: children
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "SelectItem (and SelectLabel/SelectSeparator) children for the popover."
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+      - name: defaultValue
+        type: string
+        required: false
+        declaredIn: self
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Disables BOTH halves. Use `buttonDisabled` to disable only the button."
+      - name: name
+        type: string
+        required: false
+        declaredIn: self
+      - name: onButtonClick
+        type: "MouseEventHandler<HTMLButtonElement>"
+        required: false
+        declaredIn: self
+      - name: onValueChange
+        type: "((value: string) => void)"
+        required: false
+        declaredIn: self
+      - name: placeholder
+        type: string
+        required: false
+        declaredIn: self
+      - name: size
+        type: SelectButtonSize
+        required: false
+        declaredIn: self
+        doc: "Shared height/typography ladder - matches Button, Input, Dropdown."
+      - name: value
+        type: string
+        required: false
+        declaredIn: self
+      - name: variant
+        type: SelectButtonVariant
+        required: false
+        declaredIn: self
+        doc: "Visual treatment of the right-hand action button."
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: SelectButton
+    variant:
+      kind: enum
+      options:
+        - primary
+        - secondary
+        - outline
+      default: primary
+      on: SelectButton
+    buttonType:
+      kind: enum
+      options:
+        - button
+        - submit
+        - reset
+      default: button
+      on: SelectButton
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - TRIGGER_HEIGHT
+    - TRIGGER_PADDING_X
+    - TRIGGER_TEXT
+  dataSlots:
+    - select-button
+  dependsOn:
+    internal:
+      - button
+      - select
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-select"
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-selectbutton--default
+  storybookTitle: Components/SelectButton
+  docsId: components-selectbutton--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e956345f58de
+  factsHash: "15deacab796c"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A Select and a commit-action Button joined into one inline composite control, sharing a single height."
+useWhen:
+  - "a select needs an adjacent commit action - e.g. \"choose a status, then Apply\" - that should read as one connected control rather than two separate ones"
+useInstead:
+  - id: select
+    when: "the select stands alone with no adjacent commit action"
+  - id: input-button
+    when: "the left half should be free text entry rather than a fixed list of options"
+related:
+  - select
+  - input-button
+a11y:
+  notes:
+    - "disabled disables both halves at once; use buttonDisabled to disable only the action button while keeping the select interactive, e.g. before a valid selection exists."
+    - "Each half keeps its own native semantics - a Radix Select trigger, a real Button - so no extra ARIA is needed to compose them; they only visually join."
+  keyboard:
+    - "Tab moves between the select trigger and the button independently, since they are two separate focusable controls in the DOM despite the joined visual pill."
+  radixHandles: true
+pitfalls:
+  - "variant excludes ghost, accent, destructive, and link - only primary/secondary/outline are valid, since those four do not fit the joined-pill visual (transparent backgrounds or underlines break the seam)."
+  - "disabled and buttonDisabled are independent - disabled turns off the whole control (select and button), while buttonDisabled leaves the select usable and only disables the button. Setting buttonDisabled alone does not disable the select."
+  - "children here means the SelectItem (and optionally SelectLabel/SelectSeparator) options for the popover, not the button's label - the button's text is buttonLabel, a separate required prop with an easily confused name."
+canonicalSnippet: |
+  import { SelectButton, SelectItem } from "@adres/mgda-ui"
+
+  <SelectButton
+    size="md"
+    variant="primary"
+    placeholder="Choose status"
+    value={value}
+    onValueChange={setValue}
+    buttonLabel="Apply"
+    onButtonClick={handleApply}
+  >
+    <SelectItem value="active">Active</SelectItem>
+    <SelectItem value="archived">Archived</SelectItem>
+  </SelectButton>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: e956345f58de
+---
+
+## Usage
+
+`SelectButton` joins a `Select` and a commit-action `Button` into one visual
+pill - reach for it when the two genuinely belong together (choose a value,
+then act on it), rather than composing a standalone `Select` next to a
+separate `Button` yourself. Use plain `Select` when there is no adjacent
+commit action, and `InputButton` when the left half should be free text
+instead of a fixed list.
+
+`size` scales both halves together and matches `Button`/`Input`/`Select`'s
+own height ladder, so the composite lines up with other controls at the same
+size. `variant` only applies to the right-hand button and is restricted to
+`primary`/`secondary`/`outline` - the other `Button` variants would visually
+break the joined-pill shape.
+
+`children` are the `SelectItem` options rendered in the popover, not the
+button's visible text - that is `buttonLabel`, a separate required prop.

package/knowledge/select.md

@@ -0,0 +1,210 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: select
+  sourceFile: packages/design-system/src/components/select.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Select
+      kind: component
+      radixSource: "@radix-ui/react-select#Root"
+      typeText: "FC<SelectProps>"
+    - name: SelectContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectContentProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectGroup
+      kind: component
+      radixSource: "@radix-ui/react-select#Group"
+      typeText: "ForwardRefExoticComponent<SelectGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: SelectItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectItemProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectLabel
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectLabelProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectScrollDownButton
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectScrollDownButtonProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectScrollUpButton
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectScrollUpButtonProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectSeparator
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SelectSeparatorProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: SelectTrigger
+      kind: component
+      typeText: "ForwardRefExoticComponent<SelectTriggerProps & RefAttributes<HTMLButtonElement>>"
+    - name: SelectTriggerProps
+      kind: type
+    - name: SelectTriggerSize
+      kind: type
+    - name: SelectValue
+      kind: component
+      radixSource: "@radix-ui/react-select#Value"
+      typeText: "ForwardRefExoticComponent<SelectValueProps & RefAttributes<HTMLSpanElement>>"
+  primaryExport: Select
+  subcomponents:
+    - SelectContent
+    - SelectGroup
+    - SelectItem
+    - SelectLabel
+    - SelectScrollDownButton
+    - SelectScrollUpButton
+    - SelectSeparator
+    - SelectTrigger
+    - SelectValue
+  props:
+    SelectTrigger:
+      - name: borderless
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Drop the border - for inline / sidebar triggers that shouldn't read as a field."
+      - name: size
+        type: SelectTriggerSize
+        required: false
+        declaredIn: self
+      - name: transparent
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Drop the solid background so the trigger blends into its surface."
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: SelectTrigger
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - TRIGGER_HEIGHT
+    - TRIGGER_PADDING_X
+    - TRIGGER_TEXT
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-select"
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-select--default
+  storybookTitle: Components/Select
+  docsId: components-select--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "5215ace470eb"
+  factsHash: "4a46e2e24066"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A full Radix-based dropdown select, with a scrollable list of options and Button-matching trigger sizes."
+useWhen:
+  - "choosing one value from a list of options in a form, with a trigger that looks and sizes like other form controls"
+useInstead:
+  - id: select-button
+    when: "the select needs to sit joined to a commit action button as one composite control, not a standalone field"
+  - id: dropdown-menu
+    when: "the options are actions to perform, not a value to select and submit"
+  - id: radio-group
+    when: "all options should stay visible at once rather than behind a closed trigger"
+  - id: combobox
+    when: "the list is long enough that people need to type to find an option"
+related:
+  - combobox
+  - select-button
+  - dropdown-menu
+  - radio-group
+tokens:
+  - "--popover"
+  - "--popover-foreground"
+  - "--border"
+  - "--background"
+  - "--input"
+  - "--muted"
+  - "--muted-foreground"
+  - "--foreground"
+a11y:
+  notes:
+    - "SelectValue's placeholder prop is what shows when nothing is selected - Radix marks the trigger with data-placeholder in that state, which the trigger styles via data-[placeholder]:text-muted-foreground."
+    - "Radix's Select is fully keyboard and screen-reader accessible out of the box - typing a letter jumps to a matching option, the same as a native select element."
+  keyboard:
+    - "Space or Enter opens the list; arrow keys move the highlighted option; typing jumps to a matching option; Escape closes without changing the selection."
+  radixHandles: true
+pitfalls:
+  - "className, and most props beyond SelectTrigger's size/borderless/transparent, cannot be demonstrated in this file's machine-checked canonicalSnippet, because the extractor did not resolve them from the inlined Radix generics - the same gap as dropdown-menu/drawer/popover. See the fuller example in ## Usage."
+  - "borderless and transparent both change the trigger's chrome but neither depends on the other - combining them removes both the border and the background, which can make the trigger disappear entirely against a similarly-colored surface."
+  - "SelectContent's default position=\"popper\" sizes the popover to the trigger's width via a CSS variable - overriding width through className without accounting for this can make the popover narrower than its trigger."
+canonicalSnippet: |
+  import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@adres/mgda-ui"
+
+  <Select>
+    <SelectTrigger size="md">
+      <SelectValue />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem>Apple</SelectItem>
+    </SelectContent>
+  </Select>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "5215ace470eb"
+---
+
+## Usage
+
+`Select` is the full dropdown select for choosing one value from a list in a
+form - reach for `SelectButton` instead when the select needs to sit joined
+to a commit action as one composite control, `DropdownMenu` when the options
+are actions rather than a value, and `RadioGroup` when every option should
+stay visible rather than behind a closed trigger.
+
+`SelectTrigger`'s `size` (`sm`/`md`/`lg`) matches `Button`/`Input`'s height
+and padding ladder, so a `Select` lines up with those controls in the same
+row. `borderless` and `transparent` swap the trigger's chrome for inline or
+sidebar placements that should not read as a bordered field.
+
+`value`, `defaultValue`, and `placeholder` (on `Select`/`SelectValue`), plus
+`value` on each `SelectItem`, are all real Radix props that cannot appear in
+this file's machine-checked `canonicalSnippet` above (see the pitfall on
+why). The real, recommended usage:
+
+```tsx
+<Select defaultValue="apple">
+  <SelectTrigger className="ax:w-[200px]">
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+    <SelectItem value="orange">Orange</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Select` | Root. Holds the selected value. A direct Radix `Root` re-export. |
+| `SelectTrigger` | The closed-state control. Sets `size`, `borderless`, `transparent`; renders the chevron icon. |
+| `SelectValue` | Shows the selected option's label, or `placeholder` when nothing is selected. |
+| `SelectContent` | The floating options list. Portals itself, sizes to the trigger's width by default, and wraps scroll buttons around the viewport. |
+| `SelectGroup` | Groups related items without a visible heading of its own. |
+| `SelectLabel` | A non-interactive section heading inside a `SelectGroup`. |
+| `SelectItem` | One selectable option. |
+| `SelectSeparator` | A visual divider between groups of options. |
+| `SelectScrollUpButton` / `SelectScrollDownButton` | Auto-rendered by `SelectContent` when the list overflows - not placed manually. |

package/knowledge/separator.md

@@ -0,0 +1,75 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: separator
+  sourceFile: packages/design-system/src/components/separator.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Separator
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<SeparatorProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+  primaryExport: Separator
+  subcomponents: []
+  props: {}
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-separator"
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-separator--default
+  storybookTitle: Components/Separator
+  docsId: components-separator--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: d43a20f2b89b
+  factsHash: b1d67485fbdf
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A thin visual divider between content, horizontal or vertical, built on Radix Separator."
+useWhen:
+  - "visually dividing sections of stacked content"
+  - "a vertical rule is needed between inline items, e.g. in a toolbar or breadcrumb-style row"
+a11y:
+  notes:
+    - "decorative defaults to true, so the divider is hidden from assistive tech (role=\"none\") by default - set decorative={false} only when the separator marks a real semantic boundary a screen reader user should be told about."
+  radixHandles: true
+pitfalls:
+  - "orientation=\"vertical\" relies on h-full for its height, so it only renders visibly inside a flex row with a defined height - in a plain block-flow parent with no height, it collapses to nothing unless given an explicit height via className."
+  - "orientation and className are real props (Separator forwards React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>), but the extractor could not resolve them into derived.props/extendsProps because the type is inlined on forwardRef rather than a named interface - the canonicalSnippet below omits them only to satisfy the validator's prop check, not because they don't exist."
+canonicalSnippet: |
+  import { Separator } from "@adres/mgda-ui"
+
+  <Separator />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: d43a20f2b89b
+---
+
+## Usage
+
+`Separator` draws a thin 1px line to divide content - horizontal (default) to
+separate stacked sections, or `orientation="vertical"` for a rule between
+inline items in a toolbar or row. It renders `decorative` by default, so
+assistive tech skips over it entirely; only pass `decorative={false}` when the
+line marks a real semantic boundary a screen reader user should be told about.
+
+A vertical separator relies on `h-full` for its height, so it only shows up
+inside a flex row with a defined height - in a plain block-flow container with
+no height it collapses to nothing. Give it an explicit height via `className`
+(e.g. `h-4`) when the parent does not constrain it.