prime-ui-kit 0.0.1

package/src/components/drawer/examples/cart-preview.tsx

@@ -0,0 +1,60 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Icon } from "@/icons";
+
+import styles from "./examples-scenarios.module.css";
+
+const lines = [
+  { title: "Canvas tote", meta: "Qty 1 · Navy", price: "$48.00" },
+  { title: "Studio mug", meta: "Qty 2 · Matte black", price: "$36.00" },
+] as const;
+
+/**
+ * Trailing-edge preview of the cart: scroll line items; primary checkout stays in the footer.
+ */
+export default function DrawerExampleCartPreview() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Cart (3)
+      </Button.Root>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        side="right"
+        title="Your cart"
+        description="2 products ready for checkout"
+        icon={<Icon name="nav.itemDot" tone="subtle" />}
+        footer={
+          <div className={styles.footerActions}>
+            <Button.Root
+              type="button"
+              variant="neutral"
+              mode="stroke"
+              onClick={() => setOpen(false)}
+            >
+              View cart
+            </Button.Root>
+            <Button.Root type="button" variant="primary" onClick={() => setOpen(false)}>
+              Checkout
+            </Button.Root>
+          </div>
+        }
+      >
+        {lines.map((line) => (
+          <div key={line.title} className={styles.cartLine}>
+            <div className={styles.cartLineMain}>
+              <p className={styles.cartTitle}>{line.title}</p>
+              <p className={styles.cartPrice}>{line.price}</p>
+            </div>
+            <p className={styles.cartMeta}>{line.meta}</p>
+          </div>
+        ))}
+      </Drawer>
+    </>
+  );
+}

package/src/components/drawer/examples/examples-scenarios.module.css

@@ -0,0 +1,79 @@
+.intro {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.muted {
+  margin: 0;
+  color: var(--prime-sys-color-content-secondary);
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+}
+
+.filterStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+}
+
+.cartLine {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-x1);
+  padding-block: var(--prime-sys-spacing-m);
+  border-bottom: var(--prime-sys-unit-1px) solid var(--prime-sys-color-border-subtle);
+}
+
+.cartLine:last-child {
+  border-bottom: none;
+}
+
+.cartLineMain {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--prime-sys-spacing-m);
+}
+
+.cartTitle {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+}
+
+.cartMeta {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodySmall-fontSize);
+  line-height: var(--prime-sys-typography-role-bodySmall-lineHeight);
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.cartPrice {
+  margin: 0;
+  font-size: var(--prime-sys-typography-role-bodyDefault-fontSize);
+  line-height: var(--prime-sys-typography-role-bodyDefault-lineHeight);
+  color: var(--prime-sys-color-content-primary);
+  white-space: nowrap;
+}
+
+.footerActions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-m);
+  justify-content: flex-end;
+}
+
+.settingsStack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-l);
+}

package/src/components/drawer/examples/explicit-panel.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Icon } from "@/icons";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Canonical new API with icon + subtitle in header and actions in footer.
+ */
+export default function DrawerExampleExplicitPanel() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Open details
+      </Button.Root>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        title="Details"
+        description="Only body scrolls when content overflows"
+        icon={<Icon name="nav.layoutGrid" tone="subtle" />}
+        side="right"
+        footer={
+          <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(false)}>
+            Close
+          </Button.Root>
+        }
+      >
+        <p className={styles.intro}>
+          This drawer uses the new single-component API: header with icon/title/description,
+          scrollable content area, and footer actions.
+        </p>
+      </Drawer>
+    </>
+  );
+}

package/src/components/drawer/examples/filters-panel.tsx

@@ -0,0 +1,58 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Checkbox } from "@/components/checkbox/Checkbox";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Icon } from "@/icons";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Filter drawer from the leading edge; footer keeps Apply / Reset visible while criteria scroll.
+ */
+export default function DrawerExampleFiltersPanel() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Filters
+      </Button.Root>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        side="left"
+        title="Filters"
+        description="Choose product visibility constraints"
+        icon={<Icon name="nav.itemDot" tone="subtle" />}
+        footer={
+          <div className={styles.footerActions}>
+            <Button.Root
+              type="button"
+              variant="neutral"
+              mode="stroke"
+              onClick={() => setOpen(false)}
+            >
+              Reset
+            </Button.Root>
+            <Button.Root type="button" variant="primary" onClick={() => setOpen(false)}>
+              Apply
+            </Button.Root>
+          </div>
+        }
+      >
+        <div className={styles.filterStack}>
+          <Checkbox.Root defaultChecked>
+            <Checkbox.Label>In stock only</Checkbox.Label>
+          </Checkbox.Root>
+          <Checkbox.Root>
+            <Checkbox.Label>On sale</Checkbox.Label>
+          </Checkbox.Root>
+          <Checkbox.Root>
+            <Checkbox.Label>Ships today</Checkbox.Label>
+          </Checkbox.Root>
+        </div>
+      </Drawer>
+    </>
+  );
+}

package/src/components/drawer/examples/mobile-nav-sheet.tsx

@@ -0,0 +1,48 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Icon } from "@/icons";
+
+import styles from "./examples-scenarios.module.css";
+
+const items = ["Home", "Catalog", "Orders", "Account"] as const;
+
+/**
+ * Mobile navigation surface with explicit close on item selection.
+ */
+export default function DrawerExampleMobileNavSheet() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Menu
+      </Button.Root>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        side="left"
+        title="Navigate"
+        description="Primary sections"
+        icon={<Icon name="nav.home" tone="subtle" />}
+      >
+        <nav className={styles.nav} aria-label="Primary">
+          {items.map((label) => (
+            <Button.Root
+              key={label}
+              type="button"
+              variant="neutral"
+              mode="ghost"
+              fullWidth
+              onClick={() => setOpen(false)}
+            >
+              {label}
+            </Button.Root>
+          ))}
+        </nav>
+        <p className={styles.muted}>In a real app, wire each action to routing and state sync.</p>
+      </Drawer>
+    </>
+  );
+}

package/src/components/drawer/examples/settings-side.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+
+import { Button } from "@/components/button/Button";
+import { Drawer } from "@/components/drawer/Drawer";
+import { Input } from "@/components/input/Input";
+import { Icon } from "@/icons";
+
+import styles from "./examples-scenarios.module.css";
+
+/**
+ * Settings on the trailing edge: form fields live in the scroll body, actions are fixed in footer.
+ */
+export default function DrawerExampleSettingsSide() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <>
+      <Button.Root type="button" variant="neutral" mode="stroke" onClick={() => setOpen(true)}>
+        Workspace settings
+      </Button.Root>
+      <Drawer
+        open={open}
+        onOpenChange={setOpen}
+        title="Workspace"
+        description="Team defaults and scheduling options"
+        icon={<Icon name="nav.layoutGrid" tone="subtle" />}
+        side="right"
+        footer={
+          <div className={styles.footerActions}>
+            <Button.Root
+              type="button"
+              variant="neutral"
+              mode="stroke"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button.Root>
+            <Button.Root type="button" variant="primary" onClick={() => setOpen(false)}>
+              Save changes
+            </Button.Root>
+          </div>
+        }
+      >
+        <div className={styles.settingsStack}>
+          <Input.Root label="Workspace name">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Acme Design" />
+            </Input.Wrapper>
+          </Input.Root>
+          <Input.Root label="Default timezone" hint="Used for scheduled reports.">
+            <Input.Wrapper>
+              <Input.Field defaultValue="Europe/Berlin" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      </Drawer>
+    </>
+  );
+}

package/src/components/dropdown/COMPONENT.md

@@ -0,0 +1,242 @@
+# Dropdown
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+**What:** `Dropdown` is a **portaled action menu** (`role="menu"`): one trigger toggles a floating list of **`menuitem`** rows. **`Dropdown.Trigger`** clones **exactly one** child element and merges **`aria-expanded`**, **`aria-haspopup="menu"`**, **`aria-controls`**, **`id`**, ref, and toggle **`onClick`**. **`Dropdown.Content`** renders **only when open**, applies focus trap, Escape/outside close, and arrow-key roving focus among items.
+
+**Parts:** `Root` → `Trigger` + `Content`. Inside `Content`: `Block`, `Header` (+ `HeaderRow`, `HeaderLeading`, `HeaderMain`, `HeaderTitle`, `HeaderDescription`, `HeaderTrailing`), `Group` + `GroupLabel`, `Separator`, `Item` (+ `ItemIcon`).
+
+**State:** Uncontrolled: **`defaultOpen`** on `Root`. Controlled: **`open`** + **`onOpenChange`**. **`Item.onSelect`** runs on activation, then the menu closes unless **`disabled`**.
+
+**Position:** **`Content.align`**: `start` | `center` | `end`. **`Content.side`**: `bottom` | `top` (may flip). **`sameMinWidthAsTrigger`** widens the panel to at least the trigger width. Resolved side is on **`data-side`** on the menu node.
+
+**Runnable examples**
+
+**Playground snippets** (order matches [`playground/sections/DropdownSection.tsx`](../../../playground/sections/DropdownSection.tsx); keep **`examples/`** in sync when changing these):
+
+| Snippet | Scenario |
+|---------|----------|
+| [`playground/snippets/dropdown/sizes.tsx`](../../../playground/snippets/dropdown/sizes.tsx) | **`Content.size`** s–xl: panel, rows, group label, default **`ItemIcon`** size |
+| [`playground/snippets/dropdown/variants.tsx`](../../../playground/snippets/dropdown/variants.tsx) | Plain rows and **`Item.destructive`** |
+| [`playground/snippets/dropdown/states.tsx`](../../../playground/snippets/dropdown/states.tsx) | **`Item.disabled`** (no activation / no close) |
+| [`playground/snippets/dropdown/placement.tsx`](../../../playground/snippets/dropdown/placement.tsx) | **`align`** start/center/end and **`side`** top |
+| [`playground/snippets/dropdown/controlled.tsx`](../../../playground/snippets/dropdown/controlled.tsx) | **`open`** / **`onOpenChange`** on **`Root`** |
+| [`playground/snippets/dropdown/composition.tsx`](../../../playground/snippets/dropdown/composition.tsx) | **`Block`**, header slots, **`GroupLabel`**, **`ItemIcon`**, nested trailing **Button** |
+| [`playground/snippets/dropdown/full-width.tsx`](../../../playground/snippets/dropdown/full-width.tsx) | **`sameMinWidthAsTrigger`** with narrow trigger |
+| [`playground/snippets/dropdown/as-child.tsx`](../../../playground/snippets/dropdown/as-child.tsx) | **`Trigger`** merges props into a single child (e.g. link) |
+
+**Package `examples/`** (same folder as this file; `@/` imports in-repo, **`prime-ui-kit`** for consumers):
+
+| File | Mirrors snippet | Scenario |
+|------|-----------------|----------|
+| [`examples/sizes.tsx`](examples/sizes.tsx) | `sizes.tsx` | Same as playground sizes |
+| [`examples/variants.tsx`](examples/variants.tsx) | `variants.tsx` | Same as playground variants |
+| [`examples/states.tsx`](examples/states.tsx) | `states.tsx` | Same as playground states |
+| [`examples/placement-demo.tsx`](examples/placement-demo.tsx) | `placement.tsx` | Same as playground placement |
+| [`examples/controlled.tsx`](examples/controlled.tsx) | `controlled.tsx` | Same as playground controlled |
+| [`examples/composition.tsx`](examples/composition.tsx) | `composition.tsx` | Same as playground composition |
+| [`examples/full-width.tsx`](examples/full-width.tsx) | `full-width.tsx` | Same as playground full-width |
+| [`examples/as-child.tsx`](examples/as-child.tsx) | `as-child.tsx` | Same as playground as-child |
+| [`examples/actions-menu.tsx`](examples/actions-menu.tsx) | — | Icon-only trigger, row icons, separator, **`destructive`** |
+| [`examples/account-menu.tsx`](examples/account-menu.tsx) | — | Header + avatar, **`sameMinWidthAsTrigger`**, sign out |
+| [`examples/select-like-list.tsx`](examples/select-like-list.tsx) | — | Trigger shows choice; still **`role="menu"`** (not **Select**) |
+
+Shared layout tokens for some examples: [`examples/dropdown-examples.module.css`](examples/dropdown-examples.module.css) (mirrors [`playground/snippets/dropdown/dropdown-snippets.module.css`](../../../playground/snippets/dropdown/dropdown-snippets.module.css)).
+
+**Minimal import:**
+
+```tsx
+import { Button, Dropdown } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" variant="neutral" mode="stroke">
+          Actions
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content>
+        <Dropdown.Item>Edit</Dropdown.Item>
+        <Dropdown.Item>Duplicate</Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}
+```
+
+---
+
+## Extended
+
+### About
+
+A composite **action menu**: the trigger toggles a portaled panel with commands, optional groups, a header block, and separators. Positioning and focus behavior follow a single-level `role="menu"` pattern.
+
+- **Use** for secondary operations on cards, table rows, or toolbars without a full settings page.
+- **Use** when you need a compact “more” menu next to an avatar, text, or icon trigger.
+- **Use** with **controlled** `open` / `onOpenChange` when another part of the UI must stay in sync (tours, hints, analytics).
+- **Use** `destructive` items and **groups** when you must separate safe vs dangerous or unrelated actions.
+- **Do not use** for choosing a single value shown on the trigger — that is **[Select](../select/COMPONENT.md)**.
+- **Do not use** for arbitrary floating content without menu semantics — prefer **[Popover](../popover/COMPONENT.md)**.
+- **Do not use** for nested multi-level submenus; the API is a **flat** menu only.
+
+### Composition
+
+- **`Dropdown.Root`** wraps everything and owns open state (controlled or uncontrolled).
+- **`Dropdown.Trigger`** must wrap **exactly one** React element; refs, `id`, `aria-*`, and toggle `onClick` are merged into that child.
+- **`Dropdown.Content`** renders **only when open** (portal + `role="menu"`). Put **`Dropdown.Block`** / **`Dropdown.Group`** / **`Dropdown.Item`** children inside it.
+- **`Dropdown.Block`** — generic section; **`Dropdown.Header`** and **`HeaderRow`**, **`HeaderLeading`**, **`HeaderMain`**, **`HeaderTitle`**, **`HeaderDescription`**, **`HeaderTrailing`** compose a header area inside the panel.
+- **`Dropdown.Item`** — actionable row (`role="menuitem"`); may include **`Dropdown.ItemIcon`** before text.
+- **`Dropdown.Group`** + **`Dropdown.GroupLabel`** label a set of items; **`Dropdown.Separator`** is an `hr` between blocks.
+
+### Rules
+
+- **Uncontrolled:** set **`defaultOpen`** on `Root` (defaults to `false`); internal state updates on toggle.
+- **Controlled:** pass **`open`** and **`onOpenChange`**; the parent is the source of truth for visibility.
+- **`Dropdown.Trigger`** accepts a **single** `ReactElement` — wrap composite UI in one node if needed.
+- **`onSelect`** on **`Dropdown.Item`** runs on activation, then the menu **closes**, unless the item is **`disabled`** (disabled items do not activate or close).
+- **Keyboard:** **ArrowUp** / **ArrowDown**, **Home**, **End** move focus among enabled menu items; **Enter** and **Space** activate; **Escape** closes and focus returns via the focus trap.
+- **Pointer / outside:** clicks outside the trigger and panel close the menu; outside clicks are suppressed for portaled Select listboxes owned by the panel container.
+- **A11y:** trigger gets **`aria-expanded`**, **`aria-haspopup="menu"`**, **`aria-controls`**; the menu has **`aria-labelledby`** pointing at the trigger **`id`**. Icon-only triggers need an accessible name (**`aria-label`** or visible text).
+- **`Dropdown.Content` · `size`** drives the tier for padding, row height, typography, and default **`ItemIcon`** size unless you pass an explicit **`size`** on **`ItemIcon`**.
+- **`align`** / **`side`** are preferences; **`data-side`** on the menu reflects the **resolved** side after layout.
+- **Portal:** the menu is not a DOM child of the trigger — mind **z-index** and stacking when opening from **[Modal](../modal/COMPONENT.md)** or **[Drawer](../drawer/COMPONENT.md)**.
+
+### API
+
+#### Dropdown.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| open | `boolean` | — | No | Controlled open state. |
+| defaultOpen | `boolean` | `false` | No | Initial open state when uncontrolled. |
+| onOpenChange | `(open: boolean) => void` | — | No | Called when open state changes. |
+| children | `React.ReactNode` | — | Yes | Trigger, content, and nested parts. |
+
+#### Dropdown.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement` | — | Yes | Single element; ref, `id`, ARIA, and merged `onClick` are applied to it. |
+| asChild | `boolean` | `true` | No | Kept for API consistency; the trigger always clones the child element. |
+
+#### Dropdown.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| align | `"start" \| "center" \| "end"` | `"start"` | No | Horizontal alignment of the panel to the trigger. |
+| side | `"bottom" \| "top"` | `"bottom"` | No | Preferred side; may flip when space is tight. |
+| sameMinWidthAsTrigger | `boolean` | `false` | No | Panel minimum width is not less than the trigger width. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Tier for panel metrics, rows, group labels, and default icon size. |
+| className | `string` | — | No | Extra class on the portaled menu container. |
+| children | `React.ReactNode` | — | Yes | Menu body: blocks, groups, items, etc. |
+
+#### Dropdown.Block
+
+Inherits `React.HTMLAttributes<HTMLDivElement>` (e.g. `className`, `children`).
+
+#### Dropdown.Header
+
+Same as `Dropdown.Block`.
+
+#### Dropdown.HeaderRow
+
+Same as `Dropdown.Block`.
+
+#### Dropdown.HeaderLeading
+
+Same as `Dropdown.Block`.
+
+#### Dropdown.HeaderMain
+
+Same as `Dropdown.Block`.
+
+#### Dropdown.HeaderTitle
+
+Same as `Dropdown.Block`.
+
+#### Dropdown.HeaderDescription
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| truncate | `boolean` | — | No | Single-line truncation with ellipsis. |
+| className | `string` | — | No | Extra class. |
+| children | `React.ReactNode` | — | No | Description text. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
+
+#### Dropdown.HeaderTrailing
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| alignSelf | `"start" \| "center"` | `"start"` | No | Vertical alignment within the header row. |
+| className | `string` | — | No | Extra class. |
+| children | `React.ReactNode` | — | No | Trailing slot content. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
+
+#### Dropdown.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| onSelect | `() => void` | — | No | Called on activation; then the menu closes (if not `disabled`). |
+| disabled | `boolean` | — | No | Inactive item; no activation or close. |
+| destructive | `boolean` | — | No | Danger styling (`data-destructive`). |
+| className | `string` | — | No | Extra class on the `<button>`. |
+| children | `React.ReactNode` | — | Yes | Label, `ItemIcon`, etc. |
+
+#### Dropdown.ItemIcon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `"span"` | No | Root element or icon component. |
+| aria-hidden | `boolean \| "true" \| "false"` | `true` | No | Hide decorative icons when the item has text. |
+| className | `string` | — | No | Extra class on the wrapper. |
+| children | `React.ReactNode` | — | No | Content when not using `as` alone. |
+| size | `number` | from `Content` `size` tier | No | Icon size in px; overrides the automatic tier size. |
+| …rest | `Record<string, unknown>` | — | No | Passed through to the `as` element (e.g. icon props), except reserved fields. |
+
+#### Dropdown.Group
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Extra class (`role="group"`). |
+| children | `React.ReactNode` | — | No | Group label and items. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other `div` attributes. |
+
+#### Dropdown.GroupLabel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Extra class. |
+| children | `React.ReactNode` | — | Yes | Group heading text. |
+
+#### Dropdown.Separator
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Extra class on the `hr`. |
+
+### Related
+
+- [Button](../button/COMPONENT.md) — typical trigger.
+- [Link button](../link-button/COMPONENT.md) — text-style trigger when a button chrome is not desired.
+- [Select](../select/COMPONENT.md) — single-value field with a labeled trigger.
+- [Popover](../popover/COMPONENT.md) — generic portaled surface without `menu` / `menuitem` behavior.
+- [Modal](../modal/COMPONENT.md) / [Drawer](../drawer/COMPONENT.md) — shells where menus often open from headers or rows.
+- [Avatar](../avatar/COMPONENT.md), [Badge](../badge/COMPONENT.md), [Typography](../typography/COMPONENT.md) — common header and row content.
+
+---
+
+## LLM note
+
+- **Do not** invent submenu APIs or nest another `role="menu"` inside items — flat list only.
+- **Trigger contract:** `Dropdown.Trigger` → single `ReactElement`; fragments or multiple nodes break `cloneElement`.
+- **Prefer `Button.Root`** (or `LinkButton`) as trigger with **`type="button"`** when inside forms.
+- **Icon-only trigger:** set **`aria-label`** on the trigger element (merged onto the cloned child).
+- **Choosing a form value** with listbox/combobox semantics → **Select**, not Dropdown; a “workspace switcher” that only mimics selection in the trigger label is still a menu — call that out in copy if users might confuse them.
+- **Destructive actions:** use **`destructive`** on **`Dropdown.Item`**, often after **`Separator`**, not a different component.
+- **Layout:** `Content.align="end"` is common for right-aligned toolbars; pair with **`sameMinWidthAsTrigger`** when the panel should match a narrow control.
+- **Imports for consumers:** `import { Dropdown, … } from "prime-ui-kit"`. In-repo examples under `examples/` use `@/components/...` paths.
+- **Playground source of truth for visuals:** `playground/snippets/dropdown/*.tsx` — keep docs and snippets aligned when API changes.

package/src/components/dropdown/examples/account-menu.tsx

@@ -0,0 +1,50 @@
+import { LogOut, Settings, UserRound } from "lucide-react";
+import { Avatar } from "@/components/avatar/Avatar";
+import { Button } from "@/components/button/Button";
+import { Dropdown } from "@/components/dropdown/Dropdown";
+
+/** Меню аккаунта: шапка с идентичностью, группа настроек, выход. */
+export default function DropdownAccountMenuExample() {
+  return (
+    <Dropdown.Root>
+      <Dropdown.Trigger>
+        <Button.Root type="button" variant="neutral" mode="stroke">
+          Аккаунт
+        </Button.Root>
+      </Dropdown.Trigger>
+      <Dropdown.Content align="end" sameMinWidthAsTrigger>
+        <Dropdown.Block>
+          <Dropdown.Header>
+            <Dropdown.HeaderRow>
+              <Dropdown.HeaderLeading>
+                <Avatar.Root size="l">
+                  <Avatar.Fallback>ИП</Avatar.Fallback>
+                </Avatar.Root>
+              </Dropdown.HeaderLeading>
+              <Dropdown.HeaderMain>
+                <Dropdown.HeaderTitle>Иван Петров</Dropdown.HeaderTitle>
+                <Dropdown.HeaderDescription truncate>
+                  ivan.petrov@example.com
+                </Dropdown.HeaderDescription>
+              </Dropdown.HeaderMain>
+            </Dropdown.HeaderRow>
+            <Dropdown.Separator />
+          </Dropdown.Header>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={UserRound} strokeWidth={2} />
+            Профиль
+          </Dropdown.Item>
+          <Dropdown.Item>
+            <Dropdown.ItemIcon as={Settings} strokeWidth={2} />
+            Настройки
+          </Dropdown.Item>
+        </Dropdown.Block>
+        <Dropdown.Separator />
+        <Dropdown.Item destructive>
+          <Dropdown.ItemIcon as={LogOut} strokeWidth={2} />
+          Выйти
+        </Dropdown.Item>
+      </Dropdown.Content>
+    </Dropdown.Root>
+  );
+}