@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/dropdown-menu.md

@@ -0,0 +1,238 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: dropdown-menu
+  sourceFile: packages/design-system/src/components/dropdown-menu.tsx
+  client: true
+  category: web-app-overlays
+  categoryFromBarrel: web-app-overlays
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: DropdownMenu
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#Root"
+      typeText: "FC<DropdownMenuProps>"
+    - name: DropdownMenuCheckboxItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuCheckboxItemProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<DropdownMenuContentProps & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuContentProps
+      kind: type
+    - name: DropdownMenuGroup
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#Group"
+      typeText: "ForwardRefExoticComponent<DropdownMenuGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<DropdownMenuItemProps & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuItemProps
+      kind: type
+    - name: DropdownMenuLabel
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuLabelProps & RefAttributes<HTMLDivElement>, \"ref\"> & { inset?: boolean | undefined; } & RefAttributes<...>>"
+    - name: DropdownMenuPortal
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#Portal"
+      typeText: "FC<DropdownMenuPortalProps>"
+    - name: DropdownMenuRadioGroup
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#RadioGroup"
+      typeText: "ForwardRefExoticComponent<DropdownMenuRadioGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuRadioItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuRadioItemProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuSeparator
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuSeparatorProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuShortcut
+      kind: component
+      typeText: "{ ({ className, ...props }: HTMLAttributes<HTMLSpanElement>): Element; displayName: string; }"
+    - name: DropdownMenuSub
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#Sub"
+      typeText: "FC<DropdownMenuSubProps>"
+    - name: DropdownMenuSubContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuSubContentProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: DropdownMenuSubTrigger
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<DropdownMenuSubTriggerProps & RefAttributes<HTMLDivElement>, \"ref\"> & { inset?: boolean | undefined; } & RefAttributes<...>>"
+    - name: DropdownMenuTrigger
+      kind: component
+      radixSource: "@radix-ui/react-dropdown-menu#Trigger"
+      typeText: "ForwardRefExoticComponent<DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>>"
+  primaryExport: DropdownMenu
+  subcomponents:
+    - DropdownMenuCheckboxItem
+    - DropdownMenuContent
+    - DropdownMenuGroup
+    - DropdownMenuItem
+    - DropdownMenuLabel
+    - DropdownMenuPortal
+    - DropdownMenuRadioGroup
+    - DropdownMenuRadioItem
+    - DropdownMenuSeparator
+    - DropdownMenuShortcut
+    - DropdownMenuSub
+    - DropdownMenuSubContent
+    - DropdownMenuSubTrigger
+    - DropdownMenuTrigger
+  props:
+    DropdownMenuItem:
+      - name: inset
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Indents the item to align with siblings that have a checkbox/radio indicator column."
+      - name: variant
+        type: "\"default\" | \"destructive\""
+        required: false
+        declaredIn: self
+        doc: "Colour treatment. `destructive` tints text + icon + hover/highlight background."
+    DropdownMenuLabel:
+      - name: inset
+        type: boolean
+        required: false
+        declaredIn: self
+    DropdownMenuSubTrigger:
+      - name: inset
+        type: boolean
+        required: false
+        declaredIn: self
+  extendsProps: []
+  variants:
+    variant:
+      kind: enum
+      options:
+        - default
+        - destructive
+      default: default
+      on: DropdownMenuItem
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-dropdown-menu"
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-dropdownmenu--default
+  storybookTitle: Components/DropdownMenu
+  docsId: components-dropdownmenu--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a3688fbae91f
+  factsHash: "23cea40a2ea6"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A Radix-based dropdown menu triggered by a button, with items, checkboxes, radios, submenus, and a destructive row variant."
+useWhen:
+  - "a button or icon triggers a list of actions or options, closing after a selection"
+  - "the menu needs checkbox or radio items, a nested submenu, or a destructive action row"
+useInstead:
+  - id: select
+    when: "the trigger represents a form value being chosen, not a list of actions"
+  - id: popover
+    when: "the content is more than a list of commands - a form, rich content, or anything beyond selectable rows"
+related:
+  - select
+  - popover
+tokens:
+  - "--popover"
+  - "--popover-foreground"
+  - "--border"
+  - "--muted"
+  - "--destructive"
+  - "--destructive-strong"
+a11y:
+  notes:
+    - "Wrap the real trigger element (typically a Button) with DropdownMenuTrigger asChild so Radix attaches its keyboard and ARIA handling directly to it instead of adding an extra wrapping element."
+    - "DropdownMenuShortcut is purely visual - it does not wire the actual keyboard shortcut to anything, so the real key handler must be registered separately if the shortcut should actually work."
+  keyboard:
+    - "Radix supplies full menu keyboard behavior: arrow keys move between items, Enter/Space activates, Escape closes, and typing jumps to a matching item's first letter - none of this needs to be built by hand."
+  radixHandles: true
+pitfalls:
+  - "inset only aligns an item, label, or sub-trigger's text with siblings that have a checkbox/radio indicator column - it has no other layout effect."
+  - "DropdownMenuCheckboxItem and DropdownMenuRadioItem only manage their own visual indicator - the checked or selected state is still yours to own (checked/onCheckedChange, or value/onValueChange on the parent DropdownMenuRadioGroup)."
+  - "DropdownMenuShortcut only renders text - it is decoration, not a keybinding. Adding it does not wire up the shortcut."
+  - "Most of DropdownMenuContent's and DropdownMenuTrigger's real props (align, side, asChild, sideOffset) come straight from Radix's own types via an inlined generic, which the extractor does not resolve into derived.props/extendsProps - the same gap noted for separator/aspect-ratio in 15b-ii. The machine-checked canonicalSnippet below is intentionally minimal because of this; see the fuller example in ## Usage."
+canonicalSnippet: |
+  import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from "@adres/mgda-ui"
+
+  <DropdownMenu>
+    <DropdownMenuTrigger>Account</DropdownMenuTrigger>
+    <DropdownMenuContent>
+      <DropdownMenuItem onSelect={() => {}}>Profile</DropdownMenuItem>
+      <DropdownMenuItem variant="destructive" onSelect={() => {}}>Sign out</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: a3688fbae91f
+---
+
+## Usage
+
+`DropdownMenu` is for a list of actions or options triggered from a button -
+reach for it when the trigger represents a set of commands, not a form value
+being chosen (`Select`) or richer content like a form (`Popover`).
+
+Wrap the real trigger element with `asChild` so Radix attaches its behavior
+directly to it instead of adding an extra wrapping button - this is the real,
+recommended usage, shown here since `asChild`/`align` cannot appear in this
+file's machine-checked `canonicalSnippet` (see the pitfall on why):
+
+```tsx
+import {
+  Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem,
+  DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger,
+} from "@adres/mgda-ui"
+
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="outline">Account</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="start">
+    <DropdownMenuLabel>My account</DropdownMenuLabel>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuItem>Billing</DropdownMenuItem>
+    <DropdownMenuItem variant="destructive">Sign out</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Set `variant="destructive"` on a `DropdownMenuItem` for a destructive action
+row - it tints text, icon, and hover background together. Use
+`DropdownMenuSub` + `DropdownMenuSubTrigger` + `DropdownMenuSubContent` for a
+nested submenu, and `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` (with
+`DropdownMenuRadioGroup`) when a row needs to reflect a selection state you
+own yourself.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `DropdownMenu` | Root. Holds open state. A direct Radix `Root` re-export. |
+| `DropdownMenuTrigger` | Opens the menu. Use `asChild` to wrap a real `Button`. |
+| `DropdownMenuContent` | The floating panel. Portals itself and handles positioning and animation. |
+| `DropdownMenuItem` | A single action row. `variant="destructive"` tints it; `inset` aligns it with indicator-column siblings. |
+| `DropdownMenuCheckboxItem` | A row with a checkbox indicator; you own the `checked` state. |
+| `DropdownMenuRadioGroup` / `DropdownMenuRadioItem` | A mutually-exclusive group of rows; you own the `value` state on the group. |
+| `DropdownMenuLabel` | A non-interactive section heading. |
+| `DropdownMenuSeparator` | A visual divider between groups of rows. |
+| `DropdownMenuGroup` | Groups related items semantically without adding a visible separator. |
+| `DropdownMenuShortcut` | A right-aligned, purely visual keyboard-shortcut hint. |
+| `DropdownMenuSub` / `DropdownMenuSubTrigger` / `DropdownMenuSubContent` | A nested submenu: root, the row that opens it, and its floating panel. |
+| `DropdownMenuPortal` | Escape hatch. Already rendered by `DropdownMenuContent`/`DropdownMenuSubContent`. |

package/knowledge/dropzone.md

@@ -0,0 +1,153 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: dropzone
+  sourceFile: packages/design-system/src/components/dropzone.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Dropzone
+      kind: component
+      typeText: "ForwardRefExoticComponent<DropzoneProps & RefAttributes<HTMLDivElement>>"
+    - name: DropzoneError
+      kind: type
+    - name: DropzoneErrorReason
+      kind: type
+    - name: DropzoneProps
+      kind: type
+  primaryExport: Dropzone
+  subcomponents: []
+  props:
+    Dropzone:
+      - name: accept
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accept attribute passed through to the underlying `<input>` (e.g. `\".csv\"`, `\"image/*\"`). Also enforced on drag-and-drop - browsers don't natively validate `accept` for drops."
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Disables the drop target and Browse button."
+      - name: file
+        type: File
+        required: false
+        declaredIn: self
+        doc: "Currently-selected file. When set, the dropzone collapses to a selected-file row with a \"Replace\" button."
+      - name: maxSize
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Maximum file size in bytes. Files exceeding this trigger `onError` rather than `onFile`."
+      - name: onError
+        type: "((error: DropzoneError) => void)"
+        required: false
+        declaredIn: self
+        doc: "Called when a dropped or picked file fails validation (wrong type, exceeds `maxSize`). The file is NOT forwarded to `onFile`."
+      - name: onFile
+        type: "(file: File) => void"
+        required: true
+        declaredIn: self
+        doc: "Called when a file is dropped or selected via the file picker AND passes type / size validation."
+      - name: processing
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "While true, the dropzone shows a spinner + \"Processing...\" instead of the upload affordances. Drive this from the parent's upload state."
+      - name: prompt
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Localizable prompt text. Defaults to a CSV-flavored prompt."
+      - name: templateHref
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Optional helper link rendered under the Browse button."
+      - name: templateLabel
+        type: string
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onError\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - button
+      - spinner
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-dropzone--default
+  storybookTitle: Components/Dropzone
+  docsId: components-dropzone--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e7ee09c72838
+  factsHash: b68586b1b136
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A fully-controlled file dropzone with drag-and-drop, a browse button, type/size validation, and three states: empty, selected, and processing."
+useWhen:
+  - "a single-file upload with drag-and-drop plus a fallback browse button - a CSV import, a document upload"
+useInstead:
+  - id: input-button
+    when: "the upload is a plain browse-only flow with no drag target needed"
+related:
+  - input-button
+a11y:
+  notes:
+    - "The drop target itself is not natively focusable or keyboard-operable - the Browse button is the keyboard path to select a file; drag-and-drop is a pointer-only affordance layered on top of it, not a replacement for it."
+    - "Validation errors (onError) are not announced automatically - there is no built-in live region or visible error message; render one from the DropzoneError passed to onError."
+  radixHandles: false
+pitfalls:
+  - "Dropzone is fully controlled - file and processing are props you own, not internal state. Passing onFile without also updating file yourself means the component never visually reflects a successful selection."
+  - "onFile only fires after validation passes - a rejected file (wrong type, over maxSize) goes to onError instead and never reaches onFile; there is no need to re-validate in your own handler."
+  - "accept is enforced twice for a reason: browsers apply it natively to the file picker, but do not apply it to drag-and-drop - the component re-validates accept in JavaScript specifically to cover the drop path. A permissive accept on the input alone is not enough."
+  - "processing takes over the entire render regardless of file - once processing is true, the file row and its Replace button disappear, so there is no way to swap the file mid-upload without first clearing processing."
+canonicalSnippet: |
+  import { Dropzone } from "@adres/mgda-ui"
+
+  <Dropzone
+    accept=".csv"
+    maxSize={5 * 1024 * 1024}
+    file={file}
+    onFile={setFile}
+    onError={(err) => console.error(err.message)}
+  />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: e7ee09c72838
+---
+
+## Usage
+
+`Dropzone` is a fully-controlled, single-file upload target - drag-and-drop
+onto the whole surface, or a `Browse File` button as the keyboard-accessible
+fallback. Reach for `InputButton` instead when the flow is browse-only with
+no need for a drag target.
+
+The component has three states driven entirely by props: empty (the drag or
+browse prompt), selected (`file` is set - a compact row with a `Replace`
+button), and `processing` (a spinner, which takes over regardless of
+`file`). You own `file` and `processing` in the parent and update them from
+`onFile`/`onError`.
+
+`accept` and `maxSize` gate what reaches `onFile` - a file that fails either
+check goes to `onError` instead, with a `reason` (`"invalid-type"` or
+`"too-large"`) and a ready-to-display `message`. `accept` is re-validated in
+JavaScript specifically because browsers do not enforce the native `accept`
+attribute on drag-and-drop, only on the file picker.

package/knowledge/email-chips-input.md

@@ -0,0 +1,161 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: email-chips-input
+  sourceFile: packages/design-system/src/components/email-chips-input.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: EmailChip
+      kind: type
+    - name: EmailChipsInput
+      kind: component
+      typeText: "ForwardRefExoticComponent<EmailChipsInputProps & RefAttributes<HTMLDivElement>>"
+    - name: EmailChipsInputProps
+      kind: type
+    - name: EmailChipsInputVariant
+      kind: type
+  primaryExport: EmailChipsInput
+  subcomponents: []
+  props:
+    EmailChipsInput:
+      - name: chips
+        type: "EmailChip[]"
+        required: true
+        declaredIn: self
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Disables the input and chip-removal buttons."
+      - name: id
+        type: string
+        required: false
+        declaredIn: self
+        doc: "id for the inner <input>, so a sibling <Label htmlFor> binds correctly."
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Tints the wrapper border destructive and sets `aria-invalid` on the inner input. Consumer-controlled - independent of per-chip validity."
+      - name: onChange
+        type: "(chips: EmailChip[]) => void"
+        required: true
+        declaredIn: self
+      - name: onDuplicate
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Fired when the user tries to add an address that's already in the list. Useful for surfacing a non-blocking warning toast."
+      - name: placeholder
+        type: string
+        required: false
+        declaredIn: self
+      - name: variant
+        type: EmailChipsInputVariant
+        required: false
+        declaredIn: self
+        doc: "Tone applied to valid chips. `default` is neutral, `primary` tints brand, `destructive` tints destructive. Invalid chips always render in destructive regardless of variant - the error signal stays distinct."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onChange\">"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - default
+        - primary
+        - destructive
+      default: default
+      on: EmailChipsInput
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - VARIANT_VALID_CLASS
+  dataSlots: []
+  dependsOn:
+    internal:
+      - tooltip
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-emailchipsinput--default
+    - exportName: WithValues
+      id: components-emailchipsinput--with-values
+    - exportName: WithInvalid
+      id: components-emailchipsinput--with-invalid
+    - exportName: Primary
+      id: components-emailchipsinput--primary
+    - exportName: Destructive
+      id: components-emailchipsinput--destructive
+    - exportName: Invalid
+      id: components-emailchipsinput--invalid
+    - exportName: Disabled
+      id: components-emailchipsinput--disabled
+  storybookTitle: Components/EmailChipsInput
+  docsId: components-emailchipsinput--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "6de3b913a41b"
+  factsHash: "20ca26e967ec"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A multi-email input that turns each accepted address into a removable chip, with paste-splitting and non-blocking per-chip validation."
+useWhen:
+  - "collecting multiple email addresses in one field - invite lists, notification recipients, CC/BCC-style entry"
+useInstead:
+  - id: input
+    when: "collecting a single email address, not a list"
+related:
+  - input
+a11y:
+  notes:
+    - "Each chip's remove button carries its own aria-label (\"Remove {email}\"), since the X icon alone has no accessible name."
+    - "Invalid chips get a Tooltip explaining why, wrapped in TooltipProvider automatically - no separate provider setup is needed at the call site."
+    - "invalid sets aria-invalid on the inner input and tints the wrapper - it is a consumer-controlled prop for form-level validation, independent of each chip's own valid flag. Pass it based on whatever the form's overall validity rule is, e.g. \"at least one chip\", not derived automatically from the chips array."
+  keyboard:
+    - "Enter or , commits the current text as a chip. Backspace on an empty input removes the last chip - a fast way to correct a mis-typed entry without reaching for the mouse."
+  radixHandles: false
+pitfalls:
+  - "Validation is local (regex) and non-blocking - an invalid-looking address still becomes a chip, just tinted destructive with valid: false. Nothing stops form submission on its own; filter chip.valid before using the list."
+  - "Pasting a list only splits on the paste path when the pasted text looks list-shaped (contains a separator) - a single pasted address goes through the normal typed-entry flow instead, so it is not committed as a chip until Enter or blur."
+  - "Blur commits whatever is currently typed as a chip, if non-empty - clicking away from a half-typed address does not discard it, it adds it. This can surprise a user who meant to cancel by clicking elsewhere."
+  - "onDuplicate fires but the duplicate address is silently dropped either way, in both the single-add and paste-many paths - there is no prop to allow duplicates."
+canonicalSnippet: |
+  import { EmailChipsInput } from "@adres/mgda-ui"
+
+  <EmailChipsInput chips={chips} onChange={setChips} variant="primary" />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "6de3b913a41b"
+---
+
+## Usage
+
+`EmailChipsInput` collects multiple email addresses in one field, turning
+each accepted entry into a removable chip - invite lists, notification
+recipients, CC/BCC-style entry. Reach for `Input` instead when the field is
+a single email address, not a list.
+
+Add a chip with `Enter` or `,`, or by pasting a separator-delimited list
+(commas, semicolons, newlines, tabs, or mixed) - the component splits and
+de-dupes a paste automatically. `Backspace` on an empty input removes the
+last chip.
+
+Validation is local and non-blocking: every entry becomes a chip regardless
+of whether it looks like a valid address, with invalid ones tinted
+destructive and given an explanatory tooltip. Filter `chip.valid` before
+treating the list as ready to submit - the component never blocks adding an
+invalid-looking address.
+
+`variant` only tints valid chips; invalid ones always render destructive
+regardless of `variant`, so the error signal stays visually distinct no
+matter the brand tone in use.

package/knowledge/empty-state.md

@@ -0,0 +1,106 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: empty-state
+  sourceFile: packages/design-system/src/components/empty-state.tsx
+  client: false
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: EmptyState
+      kind: component
+      typeText: "({ className, icon, title, description, action, ...props }: EmptyStateProps) => Element"
+    - name: EmptyStateProps
+      kind: type
+  primaryExport: EmptyState
+  subcomponents: []
+  props:
+    EmptyState:
+      - name: action
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: description
+        type: string
+        required: false
+        declaredIn: self
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: title
+        type: string
+        required: true
+        declaredIn: self
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-emptystate--default
+  storybookTitle: Components/EmptyState
+  docsId: components-emptystate--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "855787802b2a"
+  factsHash: "15a5f0623e3d"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A centered placeholder for a surface with no content yet, pairing an optional icon with a title, description, and action."
+useWhen:
+  - "a list, table, or panel genuinely has zero items to show, not still loading"
+  - "guiding the user toward the action that would fill the empty surface, e.g. \"Create your first project\""
+useInstead:
+  - id: skeleton
+    when: "content is still loading, not confirmed empty"
+  - id: alert
+    when: "reporting a message or error tied to the page, not describing an empty content area"
+related:
+  - skeleton
+  - alert
+a11y:
+  notes:
+    - "title renders as an h3 - check that the surrounding page's heading hierarchy still makes sense with an h3 appearing where the empty content would have been."
+    - "The icon wrapper has no aria-hidden set automatically - a purely decorative icon (the common case) needs aria-hidden=\"true\" set on the icon element you pass in yourself."
+  radixHandles: false
+pitfalls:
+  - "title is the only required prop, but description and action are what make an empty state actually useful - a bare title alone often reads as a dead end rather than guidance."
+  - "There is no built-in aria-hidden on the icon wrapper - EmptyState does not add it, so a decorative icon needs it set explicitly by the caller."
+canonicalSnippet: |
+  import { Button, EmptyState } from "@adres/mgda-ui"
+
+  <EmptyState
+    title="No projects yet"
+    description="Create your first project to get started."
+    action={<Button size="sm">New project</Button>}
+  />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "855787802b2a"
+---
+
+## Usage
+
+`EmptyState` fills the center of a surface that genuinely has nothing to show
+- an empty list, table, or search result - never a surface that is still
+loading (use `Skeleton` for that) or a message about the page itself (use
+`Alert`).
+
+Pair `title` with a `description` that explains why it is empty or what to do
+next, and an `action` (typically a `Button`) that does that next thing - a
+bare title alone often reads as a dead end rather than guidance. `icon` is
+optional decoration in a circular muted badge above the title.