prime-ui-kit 0.0.1

package/src/components/label/examples/mixed-required-optional.tsx

@@ -0,0 +1,17 @@
+import { Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/mixed-required-optional.tsx`: asterisk vs optional `Label.Sub`. */
+export function LabelMixedRequiredOptionalExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-mx-1">
+        Contract number
+        <Label.Asterisk />
+      </Label.Root>
+      <Label.Root htmlFor="example-label-mx-2">
+        Order note
+        <Label.Sub>optional</Label.Sub>
+      </Label.Root>
+    </>
+  );
+}

package/src/components/label/examples/optional-field.tsx

@@ -0,0 +1,14 @@
+import { Label } from "prime-ui-kit";
+
+/** Optional field: clarify in `Label.Sub` without a required marker on the control. */
+export function OptionalFieldExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-optional-note">
+        Internal comment
+        <Label.Sub>optional</Label.Sub>
+      </Label.Root>
+      <input id="example-label-optional-note" type="text" name="note" />
+    </>
+  );
+}

package/src/components/label/examples/required-field.tsx

@@ -0,0 +1,20 @@
+import { Label } from "prime-ui-kit";
+
+/** Required field: visual marker via `Label.Asterisk`; semantics via `required` on the control. */
+export function RequiredFieldExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-required-email">
+        Work email
+        <Label.Asterisk />
+      </Label.Root>
+      <input
+        id="example-label-required-email"
+        type="email"
+        name="email"
+        required
+        autoComplete="email"
+      />
+    </>
+  );
+}

package/src/components/label/examples/sizes.tsx

@@ -0,0 +1,37 @@
+import { Icon, Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/sizes.tsx`: plain text and `Label.Icon` rows for `s`–`xl`. */
+export function LabelSizesExample() {
+  return (
+    <>
+      <Label.Root size="s">Label s</Label.Root>
+      <Label.Root size="m">Label m</Label.Root>
+      <Label.Root size="l">Label l</Label.Root>
+      <Label.Root size="xl">Label xl</Label.Root>
+      <Label.Root size="s">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label s
+      </Label.Root>
+      <Label.Root size="m">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label m
+      </Label.Root>
+      <Label.Root size="l">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label l
+      </Label.Root>
+      <Label.Root size="xl">
+        <Label.Icon>
+          <Icon aria-hidden name="nav.home" />
+        </Label.Icon>
+        Label xl
+      </Label.Root>
+    </>
+  );
+}

package/src/components/label/examples/states.tsx

@@ -0,0 +1,17 @@
+import { Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/states.tsx`: default, `disabled`, and `Label.Asterisk`. */
+export function LabelStatesExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-st-1">Profile display name</Label.Root>
+      <Label.Root htmlFor="example-label-st-2" disabled>
+        Read-only field
+      </Label.Root>
+      <Label.Root htmlFor="example-label-st-3">
+        Phone
+        <Label.Asterisk />
+      </Label.Root>
+    </>
+  );
+}

package/src/components/label/examples/sub-line.tsx

@@ -0,0 +1,11 @@
+import { Label } from "prime-ui-kit";
+
+/** Mirrors `playground/snippets/label/sub-line.tsx`: short secondary line via `Label.Sub`. */
+export function LabelSubLineExample() {
+  return (
+    <Label.Root htmlFor="example-label-sub-budget">
+      Campaign budget
+      <Label.Sub>in RUB, excluding VAT</Label.Sub>
+    </Label.Root>
+  );
+}

package/src/components/label/examples/with-icon.tsx

@@ -0,0 +1,16 @@
+import { Icon, Label } from "prime-ui-kit";
+
+/** Icon slot: size follows `Label.Root`; hide decorative glyphs from assistive tech. */
+export function WithIconExample() {
+  return (
+    <>
+      <Label.Root htmlFor="example-label-icon-upload">
+        <Label.Icon>
+          <Icon aria-hidden name="action.upload" />
+        </Label.Icon>
+        Attachment
+      </Label.Root>
+      <input id="example-label-icon-upload" type="file" name="attachment" />
+    </>
+  );
+}

package/src/components/link-button/COMPONENT.md

@@ -0,0 +1,108 @@
+# LinkButton
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## Canonical
+
+Text-style **navigation** control: **`LinkButton.Root`** only — control typography, inline-flex, underline on hover / `:focus-visible`, sizes **`s`–`xl`**. Import **`LinkButton`** from **`prime-ui-kit`**.
+
+```tsx
+import { LinkButton } from "prime-ui-kit";
+
+<LinkButton.Root href="/settings">
+  Settings
+</LinkButton.Root>
+```
+
+| Piece | Role |
+|--------|------|
+| `LinkButton.Root` | `<a>` with anchor props, or `<span role="link">` when `disabled` |
+
+### Playground demos
+
+Порядок и смысл совпадают с **`playground/sections/LinkButtonSection.tsx`**. Исходники с импортами **`@/`** — в **`playground/snippets/link-button/`**:
+
+| Блок в секции | Сниппет | Содержание |
+|---------------|---------|------------|
+| Размеры | [`sizes.tsx`](../../../playground/snippets/link-button/sizes.tsx) | **`size`** **`s`**–**`xl`**, подписи **LinkButton s** … **xl** |
+| Состояния | [`states.tsx`](../../../playground/snippets/link-button/states.tsx) | Активная с **`href`** и **`disabled`** (span, без перехода) |
+| Композиция с иконками | [`composition.tsx`](../../../playground/snippets/link-button/composition.tsx) | **`Icon`** слева/справа, только иконка + **`aria-label`** |
+| Внешняя ссылка | [`external-link.tsx`](../../../playground/snippets/link-button/external-link.tsx) | **`target="_blank"`** и **`rel="noopener noreferrer"`** |
+
+### Примеры в `examples/`
+
+Импорт **`"prime-ui-kit"`** — для копипаста в приложение. Зеркала сниппетов (та же структура и сценарий):
+
+| Файл | Сниппет playground |
+|------|-------------------|
+| [`sizes.tsx`](examples/sizes.tsx) | [`sizes.tsx`](../../../playground/snippets/link-button/sizes.tsx) |
+| [`disabled.tsx`](examples/disabled.tsx) | [`states.tsx`](../../../playground/snippets/link-button/states.tsx) |
+| [`composition.tsx`](examples/composition.tsx) | [`composition.tsx`](../../../playground/snippets/link-button/composition.tsx) |
+| [`external.tsx`](examples/external.tsx) | [`external-link.tsx`](../../../playground/snippets/link-button/external-link.tsx) |
+
+Дополнительные сценарии (отдельного фрейма в playground нет):
+
+| Файл | Сценарий |
+|------|----------|
+| [`inline-text-link.tsx`](examples/inline-text-link.tsx) | Встроенная ссылка в абзаце, **`size="m"`** |
+| [`footer-legal.tsx`](examples/footer-legal.tsx) | Плотный ряд legal, **`size="s"`** |
+| [`navigation-cluster.tsx`](examples/navigation-cluster.tsx) | Горизонтальная навигация с разделителями |
+
+## Extended
+
+### About
+
+- **Use** for in-app routes and sections when the UI should read as a **link**, not a filled button.
+- **Use** inline in copy (help, legal, helper text) where a compact or scaled text link fits the layout; smaller tiers often use **`size="s"`** in footers and dense chrome.
+- **Use** when nested icons should follow **control** size tokens — **`size`** sets **`ControlSizeProvider`** for children.
+- **Do not use** for actions that do not navigate (submit, toggle, open dialogs); use **Button** or another control.
+- **Do not use** expecting **`asChild`** or polymorphic roots; you cannot attach these styles to a child router **`Link`** via one prop.
+- **Do not use** **`disabled`** to mean “still in tab order with full link semantics”; disabled mode removes focus and drops anchor attributes (see Rules).
+
+### Composition
+
+- **`LinkButton`** — namespace object with **`LinkButton.Root`** only.
+- **`LinkButton.Root`** — when **`disabled`** is false (default), renders **`<a>`** with anchor attributes from props and wraps **`children`** in **`ControlSizeProvider`** for **`size`**.
+- When **`disabled`** is true, renders **`<span role="link">`** with **`aria-disabled="true"`**, **`tabIndex={-1}`**, and the same size context — no **`href`** or other spread anchor props on the DOM node.
+
+### Rules
+
+- **`size`** defaults to **`m`**; valid values are **`"s"`**, **`"m"`**, **`"l"`**, **`"xl"`** (control token tier).
+- With **`disabled={true}`**, anchor props (including **`href`**, **`target`**, **`onClick`**) are **not** applied — the root is a **`span`**; do not rely on them for accessibility or behavior in that mode.
+- Active link: native **`<a>`** with your **`href`**; keyboard **Enter** activates like a normal link.
+- Disabled presentation: **`role="link"`**, **`aria-disabled="true"`**, **`tabIndex={-1}`** — not in tab order by default; avoid if the item should remain focusable as a link.
+- For **icon-only** links, provide a name (**`aria-label`** or visible text).
+- For **`target="_blank"`**, set **`rel="noopener noreferrer"`** (and warn in UI if policy requires it).
+- There is no loading or error variant; for async work without navigation, prefer **Button** (or another pattern).
+- One visual style only (no **`variant`**); hierarchy comes from **`size`** and surrounding layout. No built-in **`fullWidth`** — use layout or **`className`** on the root if you need block-level stretch.
+- **`ref`** is forwarded to the DOM root (**`<a>`** or the disabled **`<span>`**); the public ref type is **`HTMLAnchorElement`** even though the disabled node is a **`span`**.
+
+### API
+
+#### LinkButton.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Control height / type scale; size context for nested icons via `ControlSizeProvider`. |
+| disabled | `boolean` | `false` | No | Renders `span` with `role="link"` instead of `a`; no navigation. |
+| children | `React.ReactNode` | — | No | Link content (text, icons, etc.). |
+| className | `string` | — | No | Additional class on the root element. |
+| href | `string` | — | No | Navigation target on the active `<a>`; ignored when `disabled` (no `href` on the span). |
+| …anchorProps | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | — | No | Other anchor attributes forwarded to `<a>` only when `disabled` is false (`target`, `rel`, `download`, `onClick`, `aria-*`, `tabIndex`, etc.); `ref` targets `<a>` or the disabled `<span>`. |
+
+### Related
+
+- [Button](../button/COMPONENT.md) — actions, forms, loading/disabled without link semantics.
+- [Breadcrumb](../breadcrumb/COMPONENT.md) — trail navigation; items may use `LinkButton` internally.
+- [Typography](../typography/COMPONENT.md) — body text and inline links without control padding; `LinkButton` matches control alignment and scale.
+
+## LLM note
+
+- **Import:** `import { LinkButton } from "prime-ui-kit"` — render **`LinkButton.Root`**; there is no flat **`LinkButton`** element export.
+- **Semantics:** Prefer **`LinkButton`** over **`Button`** when the primary affordance is **navigation** (URL change), not a command.
+- **`disabled`:** Forces **`span`** + **`aria-disabled`**; **`href` / `onClick` / `target`** from props are **ignored** — do not pass them expecting behavior.
+- **External / new tab:** Always pair **`target="_blank"`** with **`rel="noopener noreferrer"`**.
+- **Router:** No **`asChild`** — wrap router **`Link`** by styling it separately or use plain **`<a href>`** from the kit; do not invent a polymorphic API.
+- **Density:** Footer and legal rows → often **`size="s"`**; primary in-sentence link in body copy → usually **`m`** unless the surrounding control tier dictates otherwise.
+- **Icons:** Children can include **`Icon`**; size context flows from **`LinkButton.Root`** — keep icon tier consistent with **`size`** on the root.
+- **Verification:** Таблицы **Playground demos** и **Примеры в `examples/`** выше; исходники сниппетов — `playground/snippets/link-button/*.tsx`.

package/src/components/link-button/examples/composition.tsx

@@ -0,0 +1,27 @@
+import { Icon, LinkButton } from "prime-ui-kit";
+
+/** Icons inside root pick up control size context — mirrors [`playground/snippets/link-button/composition.tsx`](../../../../playground/snippets/link-button/composition.tsx). */
+export default function LinkButtonCompositionExample() {
+  const rowStyle = {
+    display: "flex" as const,
+    flexWrap: "wrap" as const,
+    gap: "var(--prime-sys-spacing-m)",
+    alignItems: "center" as const,
+  };
+
+  return (
+    <div style={rowStyle}>
+      <LinkButton.Root href="#">
+        <Icon name="field.email" size="s" />
+        Link with icon on the left
+      </LinkButton.Root>
+      <LinkButton.Root href="#">
+        Icon on the right
+        <Icon name="action.close" size="s" />
+      </LinkButton.Root>
+      <LinkButton.Root href="#" aria-label="Open profile">
+        <Icon name="field.email" size="s" />
+      </LinkButton.Root>
+    </div>
+  );
+}

package/src/components/link-button/examples/disabled.tsx

@@ -0,0 +1,17 @@
+import { LinkButton } from "prime-ui-kit";
+
+/**
+ * Active vs <code>disabled</code> — same intent as [`playground/snippets/link-button/states.tsx`](../../../../playground/snippets/link-button/states.tsx).
+ * Disabled link is a <code>span</code> with <code>role="link"</code> — no <code>href</code>, anchor props are not applied.
+ * Do not use for “still focusable”; use <code>aria-disabled</code> on a real control pattern if that is required.
+ */
+export default function LinkButtonDisabledExample() {
+  return (
+    <div>
+      <LinkButton.Root href="/available">Available route</LinkButton.Root>
+      <LinkButton.Root href="/ignored-when-disabled" disabled>
+        Coming soon
+      </LinkButton.Root>
+    </div>
+  );
+}

package/src/components/link-button/examples/external.tsx

@@ -0,0 +1,13 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** External URL in a new tab — mirrors [`playground/snippets/link-button/external-link.tsx`](../../../../playground/snippets/link-button/external-link.tsx); always set <code>rel="noopener noreferrer"</code> with <code>target="_blank"</code>. */
+export default function LinkButtonExternalExample() {
+  return (
+    <p>
+      Documentation in a separate tab:{" "}
+      <LinkButton.Root href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
+        Open help
+      </LinkButton.Root>
+    </p>
+  );
+}

package/src/components/link-button/examples/footer-legal.tsx

@@ -0,0 +1,22 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Dense footer legal row: smaller control tier keeps the strip compact. */
+export default function LinkButtonFooterLegalExample() {
+  return (
+    <footer>
+      <nav aria-label="Legal">
+        <LinkButton.Root href="/privacy" size="s">
+          Privacy
+        </LinkButton.Root>
+        <span aria-hidden> · </span>
+        <LinkButton.Root href="/terms" size="s">
+          Terms
+        </LinkButton.Root>
+        <span aria-hidden> · </span>
+        <LinkButton.Root href="/cookies" size="s">
+          Cookie policy
+        </LinkButton.Root>
+      </nav>
+    </footer>
+  );
+}

package/src/components/link-button/examples/inline-text-link.tsx

@@ -0,0 +1,12 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Inline link inside body copy: same line as surrounding text, default control tier. */
+export default function LinkButtonInlineTextLinkExample() {
+  return (
+    <p>
+      Need more detail? See{" "}
+      <LinkButton.Root href="/docs/billing">billing documentation</LinkButton.Root> for proration
+      rules.
+    </p>
+  );
+}

package/src/components/link-button/examples/navigation-cluster.tsx

@@ -0,0 +1,16 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** Horizontal cluster of primary nav targets; named <code>nav</code> + text separators (layout can move to page grid/flex). */
+export default function LinkButtonNavigationClusterExample() {
+  return (
+    <nav aria-label="Product sections">
+      <LinkButton.Root href="/product/overview">Overview</LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/pricing">Pricing</LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/security">Security</LinkButton.Root>
+      <span aria-hidden> · </span>
+      <LinkButton.Root href="/product/changelog">Changelog</LinkButton.Root>
+    </nav>
+  );
+}

package/src/components/link-button/examples/sizes.tsx

@@ -0,0 +1,21 @@
+import { LinkButton } from "prime-ui-kit";
+
+/** `size` ladder `s`–`xl` — mirrors [`playground/snippets/link-button/sizes.tsx`](../../../../playground/snippets/link-button/sizes.tsx). */
+export default function LinkButtonSizesExample() {
+  return (
+    <>
+      <LinkButton.Root href="#" size="s">
+        LinkButton s
+      </LinkButton.Root>
+      <LinkButton.Root href="#" size="m">
+        LinkButton m
+      </LinkButton.Root>
+      <LinkButton.Root href="#" size="l">
+        LinkButton l
+      </LinkButton.Root>
+      <LinkButton.Root href="#" size="xl">
+        LinkButton xl
+      </LinkButton.Root>
+    </>
+  );
+}

package/src/components/modal/COMPONENT.md

@@ -0,0 +1,208 @@
+# Modal
+
+## About
+
+Centered overlay dialog with a portal, backdrop, focus trap, scroll lock, and optional built-in header, body, and footer. `Modal.Panel` composes these pieces so consumers rarely touch internal layers.
+
+- **Use** for blocking confirmation, forms, or disclosures that need full attention and clear dismiss semantics.
+- **Use** when Escape, overlay click, and an explicit close control should all be able to dismiss the dialog (configurable on `Modal.Root`).
+- **Do not use** for non-blocking hints or menus; prefer lighter overlays (for example [Popover](../popover/COMPONENT.md)).
+- **Do not use** for edge-docked sheets; prefer [Drawer](../drawer/COMPONENT.md) when the pattern is a side panel.
+- **Do not use** nested modal stacks without extra focus and stacking discipline; the kit does not add a second modal layer API.
+
+## Composition
+
+- **`Modal.Root`** — holds open state (controlled via **`open`** / **`onOpenChange`** or uncontrolled via **`defaultOpen`**), and options **`closeOnEscape`** / **`closeOnOverlayClick`**, **`confirmOnEnter`** / **`onEnterConfirm`** (подтверждение по Enter). Renders **`children`** only (no DOM wrapper).
+- **`Modal.Trigger`** — optional; **`React.Children.only`**: pass **exactly one** React element; its **`onClick`** is merged to call **`onOpen`** when the event is not **`defaultPrevented`**.
+- **`Modal.Panel`** — when open: **`createPortal`** (default container `document.body`), fullscreen **`role="presentation"`** overlay, then **`role="dialog"`** with **`aria-modal="true"`**. If **`title`** is set, renders an internal header (**`h2`**, optional description, optional built-in close icon button), wraps **`children`** in an internal body, and optional **`footer`**. Without **`title`**, **`children`** render directly inside the dialog surface—supply **`aria-label`** or **`aria-labelledby`** (and **`aria-describedby`** when needed).
+- **`Modal.Close`** — same single-child contract as **`Trigger`**; merges **`onClick`** and **`ref`** to the child so **`Modal.Footer`** **`primary`** can register the DOM node for Enter. Typical placement: a control inside **`Modal.Footer`** (for example **Cancel** or **Save** when saving should dismiss the dialog).
+- **`Modal.Footer`** — **`footer`** prop on **`Modal.Panel`**: предпочтительно **`Modal.Footer`** со слотами **`secondary`** (отмена, слева/раньше в разметке), **`extra`** (дополнительные кнопки между отменой и подтверждением), **`primary`** (основное действие и цель **Enter** при **`confirmOnEnter`**). Порядок в DOM: **`secondary` → `extra` → `primary`** (в LTR с **`justify-content: flex-end`** основная кнопка справа). **`primary`** — один **`React.ReactElement`** (например **`Button.Root`** или **`Modal.Close`** с кнопкой). Произвольная разметка без **`Modal.Footer`** — допустима как **`footer`**, но подтверждение по Enter к целевой кнопке не привязывается.
+- **Order:** **`Modal.Root`** → **`Modal.Trigger`** (if any) and **`Modal.Panel`** as siblings (or only **`Modal.Panel`** in controlled flows).
+
+### Minimal example
+
+```tsx
+import { Button, Modal } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root>Open</Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel title="Title">
+        <p>Content</p>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}
+```
+
+### Canonical example (full shell)
+
+Use this when you want the complete header row (**`title`**, **`description`**, **`icon`**), a form field in the body, and a **`Modal.Footer`** with **`secondary`** (**Cancel** via **`Modal.Close`**) and **`primary`**. The header still shows the built-in icon close button by default (`showClose`).
+
+```tsx
+import { Button, Icon, Input, Modal } from "prime-ui-kit";
+
+export function InviteTeammateModal() {
+  return (
+    <Modal.Root>
+      <Modal.Trigger>
+        <Button.Root variant="neutral" mode="stroke">
+          Open workspace invite
+        </Button.Root>
+      </Modal.Trigger>
+      <Modal.Panel
+        title="Invite teammate"
+        description="We will send one invitation email. The recipient can accept or decline."
+        icon={<Icon name="field.email" tone="subtle" />}
+        footer={
+          <Modal.Footer
+            primary={
+              <Button.Root variant="primary" type="button">
+                Send invite
+              </Button.Root>
+            }
+            secondary={
+              <Modal.Close>
+                <Button.Root variant="neutral" mode="stroke">
+                  Cancel
+                </Button.Root>
+              </Modal.Close>
+            }
+          />
+        }
+      >
+        <Input.Root label="Email address" hint="Work email preferred">
+          <Input.Wrapper>
+            <Input.Field autoComplete="email" placeholder="name@company.com" type="email" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Modal.Panel>
+    </Modal.Root>
+  );
+}
+```
+
+Source of truth (stays in sync with the block above): `examples/canonical-maximal.tsx`.
+
+### Playground snippets (live demos)
+
+These files power **`playground/sections/ModalSection.tsx`** (Russian copy in UI strings). Order matches the section.
+
+| File | Intent |
+|------|--------|
+| `playground/snippets/modal/composition.tsx` | Several **`Modal.Root`** demos: header-only, header+body, form, **`LinkButton`** trigger, legal-style copy |
+| `playground/snippets/modal/states.tsx` | Default Escape/overlay dismiss vs **`closeOnEscape={false}`** **`closeOnOverlayClick={false}`** + **`showClose={false}`** |
+| `playground/snippets/modal/controlled.tsx` | **`open`** / **`onOpenChange`** without **`Modal.Trigger`** |
+| `playground/snippets/modal/full-width.tsx` | Footer stack with **`Button.Root`** **`fullWidth`** (uses playground **`previewBannerColumn`**) |
+| `playground/snippets/modal/features.tsx` | **`container`** portal host + long body with **`bodyStyle`** scroll |
+
+### Examples next to this file
+
+Runnable examples use `@/` in the workspace; published consumers import **`prime-ui-kit`**. **`pattern-*`** files mirror the playground snippets above in English (same APIs).
+
+| File | Intent |
+|------|--------|
+| `examples/canonical-maximal.tsx` | Full shell: title, description, icon, one field, footer with **`Modal.Close`** + primary |
+| `examples/pattern-controlled.tsx` | Controlled open state (pairs with **`controlled.tsx`** snippet) |
+| `examples/pattern-close-behavior.tsx` | Default vs strict dismiss (pairs with **`states.tsx`** snippet) |
+| `examples/pattern-full-width-footer.tsx` | Full-width footer actions (pairs with **`full-width.tsx`** snippet) |
+| `examples/pattern-portal-and-scroll.tsx` | **`container`** + **`bodyStyle`** scroll (pairs with **`features.tsx`** snippet) |
+| `examples/scenario-confirm-delete.tsx` | Destructive confirmation; **`variant="error"`** on primary action |
+| `examples/scenario-edit-entity.tsx` | Rename / edit field; **Save** wrapped in **`Modal.Close`** to dismiss after save |
+| `examples/scenario-legal-consent.tsx` | Terms-style copy; **`closeOnOverlayClick={false}`**; single **I agree** closes via **`Modal.Close`** |
+| `examples/scenario-multi-field-form.tsx` | **`Input`**, **`Select`**, **`Textarea`** in the body; submit button uses **`form`** |
+
+### Extended usage
+
+- **Controlled dialogs:** omit **`Modal.Trigger`**; pass **`open`** and **`onOpenChange`** to **`Modal.Root`**. Keep **`Modal.Panel`** as a sibling; it portals only when **`open`** is true.
+- **Dismiss on primary action:** wrap the confirming button in **`Modal.Close`** when the action should close the dialog immediately (see **edit entity** example). If you must await an API call, keep the dialog open until success, then call **`onOpenChange(false)`** from the parent.
+- **Consent / wizard steps:** set **`closeOnOverlayClick={false}`** (and optionally **`closeOnEscape={false}`**) when accidental dismiss would lose legal or multi-step state; still provide an explicit **`Modal.Close`** (or header close) path where appropriate.
+- **Long body content:** constrain scroll to the body via **`bodyStyle`** / **`bodyClassName`** (see `playground/snippets/modal/features.tsx`); overlay scroll lock remains active.
+- **Enter to confirm:** при **`confirmOnEnter={true}`** (по умолчанию) **Enter** внутри диалога имитирует **`click()`** по элементу из слота **`Modal.Footer`** **`primary`** (логика в **`useModalKeyboard`** вместе с Escape). В шапке (**`header`**) нативное поведение **Enter** на кнопке закрытия сохраняется; в **`textarea`** / **`select`** и ряде типов **`input`** подтверждение по Enter не срабатывает. Полностью своё поведение — **`onEnterConfirm`** на **`Modal.Root`**; отключить — **`confirmOnEnter={false}`**.
+- **Headless dialog surface:** omit **`title`** on **`Modal.Panel`** and supply **`aria-label`** or **`aria-labelledby`** / **`aria-describedby`** yourself; inner body wrapper is not used, so **`bodyClassName`** / **`bodyStyle`** do not apply.
+
+### Note for LLMs
+
+When generating **Modal** markup for this library: (1) **`Modal.Trigger`** and **`Modal.Close`** each require **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Modal.Panel`** with **`title`** (and usually **`description`**) so **`aria-labelledby`** / **`aria-describedby`** are wired automatically. (3) Use **`Modal.Footer`** with **`secondary`** (**`Modal.Close`** + cancel) and **`primary`** (main action) unless the design relies only on the header icon. (4) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, and documented props only. (5) For copy-paste starting points, mirror **`examples/canonical-maximal.tsx`** first, then **`examples/pattern-*`** or scenario files; playground **`playground/snippets/modal/*.tsx`** are the live-demo source of truth.
+
+## Rules
+
+- **Shell tokens:** overlay padding, panel padding, gaps between header/body/footer, and max width use **`--prime-sys-size-modal-*`** (semantic `size.modal` in `tokens/semantic.ts`). Title/description text tiers may still follow control typography tokens where the chrome matches **`size`** `m`.
+- **Controlled:** omit **`Modal.Trigger`** and drive **`open`** / **`onOpenChange`** on **`Modal.Root`**; **`Modal.Panel`** still portals when **`open`** is true.
+- **Uncontrolled:** use **`defaultOpen`** or rely on **`Modal.Trigger`**; **`onOpenChange`** fires for any transition.
+- **`Modal.Trigger`** and **`Modal.Close`** require **exactly one** child element (**`cloneElement`**); fragments or multiple nodes are invalid.
+- **Accessibility:** with **`title`** / **`description`**, **`aria-labelledby`** / **`aria-describedby`** on the dialog are wired from the internal header. Without a visible title, set **`aria-label`** on **`Modal.Panel`** or valid **`aria-labelledby`** / **`aria-describedby`** yourself.
+- While open, siblings of the portal subtree on **`document.body`** get **`inert`** and **`aria-hidden="true"`** to hide background from assistive tech; restore runs on close.
+- **Focus:** focus is trapped inside the dialog while open; initial focus follows browser / trap behavior—ensure a focusable control or manage focus if the first paint is static text only.
+- **`showClose`** (default **`true`** when a header is shown) controls the header icon button; **`closeAriaLabel`** defaults to **`"Close"`**.
+- **`container`** on **`Modal.Panel`** overrides the portal target (for tests or custom stacking); default is **`document.body`**.
+- **`overlayClassName`**, **`footerClassName`**, **`bodyClassName`**, and **`bodyStyle`** target the overlay, the **`footer`** element (merged into **`Modal.Footer`** when **`footer`** is **`Modal.Footer`**, else a wrapper **`<footer>`** for arbitrary content), and body wrapper respectively; without **`title`**, **`bodyClassName`** / **`bodyStyle`** do not apply (no inner body wrapper).
+
+## API
+
+### Modal.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| open | `boolean` | — | No | Controlled open state |
+| defaultOpen | `boolean` | `false` | No | Initial open when uncontrolled |
+| onOpenChange | `(open: boolean) => void` | — | No | Fires when open state changes |
+| closeOnEscape | `boolean` | `true` | No | Whether Escape closes the dialog |
+| closeOnOverlayClick | `boolean` | `true` | No | Whether a direct backdrop click closes |
+| confirmOnEnter | `boolean` | `true` | No | Whether Enter triggers the default confirmation action (primary button) |
+| onEnterConfirm | `(event: KeyboardEvent) => void` | — | No | Replaces default Enter confirmation; call `event.preventDefault()` if needed to suppress native control behavior |
+| children | `React.ReactNode` | — | No | e.g. `Modal.Trigger` and `Modal.Panel` |
+
+### Modal.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement<{ onClick?: React.MouseEventHandler }>` | — | Yes | Single element whose `onClick` is composed with open |
+
+### Modal.Close
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactElement<{ onClick?: React.MouseEventHandler; ref?: React.Ref<HTMLElement>; className?: string; size?: "s" \| "m" \| "l" \| "xl" }>` | — | Yes | Single element whose `onClick` and `ref` are composed with close |
+
+### Modal.Footer
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| primary | `React.ReactElement` (e.g. `Button.Root`) | — | No | Main action; target for Enter when `confirmOnEnter` and no `onEnterConfirm` |
+| secondary | `React.ReactNode` | — | No | Usually cancel / `Modal.Close` |
+| extra | `React.ReactNode` | — | No | Additional buttons between `secondary` and `primary` |
+| className | `string` | — | No | Class on the `<footer>` |
+| …rest | `Omit<React.HTMLAttributes<HTMLElement>, "children">` | — | No | Other attributes on `<footer>` |
+
+### Modal.Panel
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| title | `React.ReactNode` | — | No | If set, builds header with `h2` and optional description |
+| description | `React.ReactNode` | — | No | Shown under the title when `title` is set |
+| icon | `React.ReactNode` | — | No | Icon slot in the header row |
+| showClose | `boolean` | `true` | No | Header close icon button when `title` is set |
+| closeAriaLabel | `string` | `"Close"` | No | `aria-label` for the header close control |
+| children | `React.ReactNode` | — | No | Main content; wrapped in internal body when `title` is set |
+| footer | `React.ReactNode` | — | No | Prefer **`Modal.Footer`**; arbitrary nodes are wrapped in **`<footer>`** without Enter binding |
+| container | `HTMLElement \| null` | `document.body` | No | Portal mount node |
+| overlayClassName | `string` | — | No | Class on the fullscreen backdrop |
+| footerClassName | `string` | — | No | Merged into **`Modal.Footer`** `className` when **`footer`** is **`Modal.Footer`**; else on wrapper **`<footer>`** |
+| bodyClassName | `string` | — | No | Class on the internal body when `title` is set |
+| bodyStyle | `React.CSSProperties` | — | No | Inline style on the internal body when `title` is set |
+| aria-label | `string` | — | No | Dialog name when there is no `title`-driven label |
+| aria-labelledby | `string` | — | No | Overrides auto wiring from the built-in header |
+| aria-describedby | `string` | — | No | Overrides auto wiring from the built-in description |
+| className | `string` | — | No | Class on the `role="dialog"` root |
+| style | `React.CSSProperties` | — | No | Style on the `role="dialog"` root |
+| …rest | `Omit<React.HTMLAttributes<HTMLDivElement>, "title">` | — | No | Other attributes forwarded to the dialog root |
+
+## Related
+
+- [Button](../button/COMPONENT.md)
+- [Drawer](../drawer/COMPONENT.md)
+- [Popover](../popover/COMPONENT.md)