prime-ui-kit 0.2.5 → 0.3.1

package/dist/tokens/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../tokens/semantic.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAwGvB,2FAA2F;;;;;;;;;;;;;;;;;;QAkB3F;;WAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2FH;;;;;;WAMG;;YAED,yEAAyE;;;;;YAKzE,sEAAsE;;;;;YAKtE,sEAAsE;;;;;YAKtE,qEAAqE;;;;;YAKrE,mEAAmE;;;;;YAKnE,+FAA+F;;;;;YAK/F,mEAAmE;;;;;YAKnE,4EAA4E;;;;;YAK5E,6DAA6D;;;;;YAK7D,0GAA0G;;;;;YAK1G,+CAA+C;;;;;YAK/C,8CAA8C;;;;;;;;;;;;;;;;;;;;;;;IAuBlD;;OAEG;;;;;;;;;;;;;;;;;;;;;;;;IAwBH;;;OAGG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAsCD;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAkHH,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAuExE,yGAAyG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAsEzG,mFAAmF;;;;;;;;;;;;;;;;;;;;;;;;;;;QA2BnF,2FAA2F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmC3F,+DAA+D;;;;;;;;;;;;;;;;;;;;;;;CAuBzD,CAAC"}

package/dist/tokens/themes/dark.d.ts

@@ -0,0 +1,143 @@
+export declare const darkThemeOverrides: {
+    readonly color: {
+        readonly status: {
+            readonly information: {
+                readonly background: "{color.blue.950}";
+                readonly backgroundEmphasis: "{color.blue.500}";
+                readonly foreground: "{color.blue.200}";
+                readonly border: "{color.blue.800}";
+            };
+            readonly warning: {
+                readonly background: "{color.orange.950}";
+                readonly backgroundEmphasis: "{color.orange.500}";
+                readonly foreground: "{color.orange.200}";
+                readonly border: "{color.orange.800}";
+            };
+            readonly success: {
+                readonly background: "{color.green.950}";
+                readonly backgroundEmphasis: "{color.green.500}";
+                readonly foreground: "{color.green.200}";
+                readonly border: "{color.green.800}";
+            };
+            readonly away: {
+                readonly background: "{color.yellow.950}";
+                readonly backgroundEmphasis: "{color.yellow.500}";
+                readonly foreground: "{color.yellow.200}";
+                readonly border: "{color.yellow.800}";
+            };
+            readonly feature: {
+                readonly background: "{color.purple.950}";
+                readonly backgroundEmphasis: "{color.purple.500}";
+                readonly foreground: "{color.purple.200}";
+                readonly border: "{color.purple.800}";
+            };
+            readonly verified: {
+                readonly background: "{color.sky.950}";
+                readonly backgroundEmphasis: "{color.sky.500}";
+                readonly foreground: "{color.sky.200}";
+                readonly border: "{color.sky.800}";
+            };
+            readonly error: {
+                readonly background: "{color.red.950}";
+                readonly backgroundEmphasis: "{color.red.500}";
+                readonly foreground: "{color.red.200}";
+                readonly border: "{color.red.800}";
+            };
+        };
+        readonly surface: {
+            readonly default: "{color.gray.950}";
+            readonly raised: "{color.gray.900}";
+            readonly elevated: "{color.gray.800}";
+            readonly accentSoft: "{color.gray.800}";
+            readonly dangerSoft: "{color.red.950}";
+            readonly overlay: "{color.overlay.scrimDark}";
+        };
+        readonly content: {
+            readonly primary: "{color.gray.50}";
+            readonly secondary: "{color.gray.300}";
+            readonly muted: "{color.gray.400}";
+            readonly disabled: "{color.gray.600}";
+            readonly inverse: "{color.gray.950}";
+            readonly accent: "{color.gray.200}";
+            readonly danger: "{color.red.200}";
+        };
+        readonly border: {
+            readonly subtle: "{color.gray.800}";
+            readonly separator: "{color.gray.500}";
+            readonly strong: "{color.gray.600}";
+            readonly emphasis: "{color.gray.50}";
+            readonly muted: "{color.gray.700}";
+            readonly accent: "{color.gray.500}";
+            readonly danger: "{color.red.400}";
+            readonly disabled: "{color.gray.800}";
+            readonly inverse: "{color.white}";
+        };
+        readonly action: {
+            readonly primaryBackground: "{color.gray.50}";
+            readonly primaryBackgroundHover: "{color.gray.200}";
+            readonly primaryForeground: "{color.gray.950}";
+            readonly primarySoftBackground: "color-mix(in srgb, var(--prime-ref-color-gray-50) 42%, var(--prime-ref-color-gray-950))";
+            readonly primarySoftForeground: "{color.gray.50}";
+            readonly neutralBackground: "{color.gray.900}";
+            readonly neutralBackgroundHover: "{color.gray.800}";
+            readonly neutralForeground: "{color.gray.50}";
+            readonly errorBackground: "{color.red.500}";
+            readonly errorBackgroundHover: "{color.red.600}";
+            readonly errorForeground: "{color.white}";
+        };
+        readonly focus: {
+            readonly ring: "{color.gray.100}";
+        };
+        readonly field: {
+            readonly bg: "{color.gray.900}";
+            readonly text: "{color.gray.50}";
+            readonly placeholder: "{color.gray.500}";
+            readonly border: "{color.gray.700}";
+            readonly borderHover: "{color.gray.600}";
+            readonly borderFocus: "{color.gray.300}";
+            readonly borderError: "{color.red.400}";
+        };
+        readonly tooltip: {
+            readonly background: "{color.gray.100}";
+            readonly foreground: "{color.gray.950}";
+            readonly border: "{color.gray.300}";
+        };
+        readonly dataTable: {
+            readonly dividerVertical: "color-mix(in srgb, var(--prime-sys-color-border-subtle) 78%, transparent)";
+            readonly dividerHorizontal: "color-mix(in srgb, var(--prime-sys-color-border-subtle) 86%, transparent)";
+            readonly headBackground: "{color.surface.elevated}";
+            readonly rowBackground: "{color.surface.default}";
+        };
+        readonly badge: {
+            readonly grayFilled: {
+                readonly background: "{color.gray.500}";
+            };
+            readonly pink: {
+                readonly backgroundSoft: "{color.pink.950}";
+                readonly foregroundOnSoft: "{color.pink.200}";
+                readonly backgroundEmphasis: "{color.pink.500}";
+                readonly border: "{color.pink.800}";
+            };
+            readonly teal: {
+                readonly backgroundSoft: "{color.teal.950}";
+                readonly foregroundOnSoft: "{color.teal.200}";
+                readonly backgroundEmphasis: "{color.teal.500}";
+                readonly border: "{color.teal.800}";
+            };
+        };
+    };
+    readonly elevation: {
+        readonly shadow: {
+            readonly surface: "0 1px 2px rgba(8, 10, 14, 0.35)";
+            readonly modal: "0 24px 48px rgba(8, 10, 14, 0.45)";
+            readonly tooltip: "0 14px 30px rgba(8, 10, 14, 0.5), 0 4px 10px rgba(8, 10, 14, 0.4)";
+            readonly buttonFocus: "0 0 0 2px rgba(244, 244, 245, 0.28)";
+            readonly primaryFocus: "0 0 0 2px rgba(244, 244, 245, 0.4)";
+            readonly errorFocus: "0 0 0 2px rgba(248, 113, 113, 0.38)";
+            readonly fancyButtonNeutral: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-content-primary)";
+            readonly fancyButtonPrimary: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-action-primaryBackground)";
+            readonly fancyButtonError: "0 1px 2px rgba(8, 10, 14, 0.45), 0 0 0 1px var(--prime-sys-color-action-errorBackground)";
+        };
+    };
+};
+//# sourceMappingURL=dark.d.ts.map

package/dist/tokens/themes/dark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dark.d.ts","sourceRoot":"","sources":["../../../tokens/themes/dark.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJrB,CAAC"}

package/dist/tokens/themes/light.d.ts

@@ -0,0 +1,16 @@
+export declare const lightThemeOverrides: {
+    readonly color: {
+        readonly focus: {
+            readonly ring: "{color.gray.950}";
+        };
+    };
+    readonly elevation: {
+        readonly shadow: {
+            readonly tooltip: "0 12px 28px rgba(15, 17, 21, 0.22), 0 4px 10px rgba(15, 17, 21, 0.16)";
+            readonly buttonFocus: "0 0 0 2px rgba(15, 17, 21, 0.14)";
+            readonly primaryFocus: "0 0 0 2px rgba(15, 17, 21, 0.2)";
+            readonly errorFocus: "0 0 0 2px rgba(220, 38, 38, 0.2)";
+        };
+    };
+};
+//# sourceMappingURL=light.d.ts.map

package/dist/tokens/themes/light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light.d.ts","sourceRoot":"","sources":["../../../tokens/themes/light.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;CActB,CAAC"}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "React 19 UI kit: CSS Modules, semantic design tokens (--prime-sys-*), composable components — forms, modals, selects, tables, navigation, overlays. TypeScript, ESM, a11y-oriented.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "keywords": [
     "a11y",
     "accessible",
@@ -59,7 +62,8 @@
   "homepage": "https://github.com/esurkov1/prime-ui#readme",
   "files": [
     "dist",
-    "src/styles",
+    "src/styles/*.css",
+    "src/components/**/COMPONENT.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -80,7 +84,6 @@
     "@vitest/coverage-v8": "^4.1.0",
     "jsdom": "latest",
     "esbuild": "^0.27.0",
-    "tsup": "latest",
     "typescript": "^5",
     "vite": "^7",
     "vitest": "latest"
@@ -109,8 +112,10 @@
     "./components.css": "./dist/components/index.css"
   },
   "scripts": {
+    "clean": "rm -rf dist .dts-stage coverage playground/dist",
     "tokens:build": "bun run scripts/build-tokens.ts",
-    "build": "bun run tokens:build && tsup --dts-only --config tsup.dts.config.ts && bun run scripts/rm-dist.ts && bun run scripts/bundle-lib.ts && bun run scripts/copy-dts-to-dist.ts",
+    "build": "bun run tokens:build && bun run scripts/bundle-lib.ts",
+    "prepublishOnly": "bun run clean && bun run build",
     "dev": "bun run scripts/bundle-lib.ts --watch",
     "playground:dev": "vite playground --config playground/vite.config.ts",
     "check": "biome check .",

package/src/components/accordion/COMPONENT.md

@@ -0,0 +1,137 @@
+# Accordion
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compound disclosure pattern: each item has a header trigger and expandable body content, with optional height animation. Use it to stack optional sections (FAQ, settings groups, legal blocks) without leaving the page.
+
+**When to use**
+
+- Long pages where users open only the sections they need: FAQs, delivery and return copy, grouped settings, order or project detail blocks, knowledge-base articles, sidebars and narrow columns.
+- One-at-a-time expansion (`type="single"`) or several open panels (`type="multiple"`) when comparing sections side by side.
+- Visual density control via `layout="grouped"` (single frame) vs `layout="separate"` (card-like items).
+
+**When not to use**
+
+- Switching one shared panel with a horizontal tab list — prefer [Tabs](../tabs/COMPONENT.md).
+- When every section must stay visible without extra interaction.
+- Deep hierarchical navigation — prefer a flat list, tree, or separate routes instead of nested accordions.
+- Very heavy bodies inside animated panels (large lists, charts) if `ResizeObserver`-driven height updates become costly.
+
+## Composition
+
+- **`Accordion.Root`** wraps all items and supplies `size`, `type`, `layout`, and open-state (`value` / `defaultValue` / `onValueChange`).
+- Per item the order is: **`Accordion.Item`** (required `value`) → **`Accordion.Header`** → **`Accordion.Trigger`** (native `button`) as a **direct** child of the header → **`Accordion.Content`** as a **sibling** of the header (same item), not nested inside the trigger.
+- Put label text, optional **`Accordion.Icon`**, and optional **`Accordion.Arrow`** inside the trigger as needed.
+- **`Accordion.Content`** renders an outer **`section`** (ARIA region) and an inner padded block; `className` applies to the inner block; `style` is merged onto the outer node with the animation height variable.
+
+### Minimal example
+
+```tsx
+import { Accordion } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Accordion.Root type="single">
+      <Accordion.Item value="one">
+        <Accordion.Header>
+          <Accordion.Trigger>Section title</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Content>Section body.</Accordion.Content>
+      </Accordion.Item>
+    </Accordion.Root>
+  );
+}
+```
+
+## Rules
+
+- Use **`type="single"`** for at most one open item, **`type="multiple"`** for any subset open; `defaultValue` is a string or string array matching the type.
+- **Controlled:** pass **`value`** (`string` or `string[]`); updates go through **`onValueChange`**. In `single`, the callback receives a string; closing the open item yields **`""`**. In `multiple`, the callback receives the open id array.
+- **Uncontrolled:** omit `value` and optionally set **`defaultValue`**.
+- **`collapsible`** applies only to **`type="single"`**; set **`collapsible={false}`** to keep at least one item open once opened (cannot collapse to none).
+- **`disabled`** on **`Accordion.Item`** disables the trigger and blocks toggling for that item.
+- **`Accordion.Trigger`:** custom **`onClick`** runs first; call **`preventDefault()`** on the event if you need to cancel the built-in toggle. Prefer **`type="button"`** (default) inside forms.
+- **`Accordion.Arrow`** icons use **`aria-hidden`**; the accessible name must come from trigger text (or an explicit label pattern you add).
+- Keyboard: trigger is a button — **Enter** / **Space** activate; focus ring follows **`focus-visible`** from the theme.
+- **`data-state`** is **`open` | `closed`** on item, trigger, and content wrapper; **`data-disabled`** when the item is disabled.
+- **`AccordionContentProps`** is typed from **`HTMLDivElement`** attributes even though the outer DOM node is **`section`** — target the real **`section`** in tests and CSS when needed.
+
+## API
+
+### Accordion.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"single" \| "multiple"` | `"single"` | No | One open item vs many. |
+| value | `string \| string[]` | — | No | Controlled open value(s). |
+| defaultValue | `string \| string[]` | — | No | Initial open value(s) when uncontrolled. |
+| onValueChange | `(value: string \| string[]) => void` | — | No | `single`: string (empty string if none open). `multiple`: string array. |
+| collapsible | `boolean` | `true` | No | `single` only: if `false`, the open item cannot be closed to leave none open. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Trigger, icons, and content spacing. |
+| layout | `"grouped" \| "separate"` | `"grouped"` | No | Shared frame vs card-like items. |
+| className | `string` | — | No | Root wrapper class. |
+| children | `React.ReactNode` | — | No | `Accordion.Item` nodes. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Passed to the root `div`. |
+
+### Accordion.Item
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| value | `string` | — | Yes | Unique id among siblings under one root. |
+| disabled | `boolean` | `false` | No | Item cannot open; trigger disabled. |
+| className | `string` | — | No | Item wrapper class. |
+| children | `React.ReactNode` | — | No | Header + content. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Passed to the item `div`. |
+
+### Accordion.Header
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Header class. |
+| children | `React.ReactNode` | — | No | Typically one `Accordion.Trigger`. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Rendered as `h3`. |
+
+### Accordion.Trigger
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Prefer `button` in forms. |
+| className | `string` | — | No | Button class. |
+| children | `React.ReactNode` | — | No | Label and optional icon/arrow slots. |
+| …rest | `React.ButtonHTMLAttributes<HTMLButtonElement>` | — | No | `onClick` invoked before internal toggle. |
+
+### Accordion.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `"div"` | No | Polymorphic element for the icon wrapper. |
+| className | `string` | — | No | Wrapper class. |
+| children | `React.ReactNode` | — | No | Icon content when using a text-only element. |
+| …rest | Depends on `as` | — | No | Props for the chosen element (except `as` / `className`). |
+
+### Accordion.Arrow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| openIcon | `React.ElementType` | `ChevronDown` | No | Default chevron rotates when closed vs open; or paired with `closeIcon`. |
+| closeIcon | `React.ElementType` | — | No | If set and differs from `openIcon`, shows two icons without rotation. |
+| className | `string` | — | No | `span` wrapper class. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Icons are `aria-hidden`. |
+
+### Accordion.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Class on the inner padded block. |
+| style | `React.CSSProperties` | — | No | Merged on the outer `section` with the animated height CSS variable. |
+| children | `React.ReactNode` | — | No | Panel body. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Spread on the outer `section`; `aria-labelledby` / `aria-hidden` come from context. |
+
+## Related
+
+- [Typography](../typography/COMPONENT.md) — body copy inside `Accordion.Content`.
+- [Button](../button/COMPONENT.md) — external actions coordinated with controlled `value` on the root.
+- [Tabs](../tabs/COMPONENT.md) — alternative when one panel switches without a vertical stack of headers.
+- [Modal](../modal/COMPONENT.md) and [Drawer](../drawer/COMPONENT.md) — often host accordions in limited vertical space.

package/src/components/avatar/COMPONENT.md

@@ -0,0 +1,100 @@
+# Avatar
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+Circular avatar with an optional photo (`Avatar.Image`), a fallback layer (`Avatar.Fallback`), and an optional horizontal stack (`Avatar.Group`) with an overflow cell.
+
+- **Use** for profile pictures, participant lists, assignees in tables, and compact identity in headers or comments when a face or initials aid recognition.
+- **Use** `Avatar.Group` when several avatars should overlap in one row and you may show a “+N” overflow.
+- **Do not use** as the only focusable control without a wrapping `button` or `link` when the avatar itself must be actionable.
+- **Do not use** for non-circular crops or rich media cards; keep this primitive for round avatars and short fallback content.
+- **Do not use** expecting an external “controlled” image load state; status lives inside `Avatar.Root` and resets when `src` changes (see Rules).
+
+## Composition
+
+- **`Avatar.Root`** — outer `div` with `data-size`, provides context (`size`, internal image status). Place **`Avatar.Image`** (optional) and **`Avatar.Fallback`** inside; image is painted above the fallback in the layout.
+- **`Avatar.Image`** — `img` with `data-status` (`loading` \| `loaded` \| `error`). Requires **`src`**; the implementation remounts when **`src`** changes, which restarts loading and context status.
+- **`Avatar.Fallback`** — `span` shown when the image is absent, loading, or in error; when the image has loaded successfully, the fallback gets **`aria-hidden`**.
+- **`Avatar.Group.Root`** — horizontal flex row; passes its **`size`** into child **`Avatar.Root`** and **`Avatar.Group.Overflow`** that omit their own **`size`** (including through **`React.Fragment`** children).
+- **`Avatar.Group.Overflow`** — cell matching avatar dimensions for text such as `+3`.
+
+### Minimal example
+
+```tsx
+import { Avatar } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Avatar.Root>
+      <Avatar.Image src="/avatar.png" alt="" />
+      <Avatar.Fallback>AB</Avatar.Fallback>
+    </Avatar.Root>
+  );
+}
+```
+
+## Rules
+
+- Image lifecycle is **internal**: context status is `idle` \| `loading` \| `loaded` \| `error`; there is no prop to control it from outside—change **`src`** (or remove **`Avatar.Image`**) to reset behavior.
+- Put **`Avatar.Image`** and **`Avatar.Fallback`** only under **`Avatar.Root`**; **`Avatar.Fallback`** does not accept a **`src`**—photos go through **`Avatar.Image`** only.
+- Give **`Avatar.Root`** or a wrapper a clear name for assistive tech (**`aria-label`**, **`aria-labelledby`**, or nearby visible text). On **`Avatar.Image`**, use a non-empty **`alt`** when the photo conveys meaning; use **`alt=""`** when it duplicates a visible name.
+- After a successful load, **`Avatar.Fallback`** is **`aria-hidden`** so screen readers do not double-announce initials and alt text.
+- For **`Avatar.Group.Root`** and **`Avatar.Group.Overflow`**, prefer summary labels (**`aria-label`**) when the stack or “+N” needs context.
+- There is no **`disabled`** prop; mute or disable via the parent (e.g. button **`disabled`**, link **`aria-disabled`**, reduced opacity).
+- **`Avatar.Group`** is laid out as a **horizontal** row only; nesting **`Avatar.Root`** inside another **`Avatar.Root`** is not a supported pattern.
+
+## API
+
+### Avatar.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | `"s" \| "m" \| "l" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl"` | `"m"` | No | Diameter, radius, and fallback typography scale |
+| children | `React.ReactNode` | — | No | Typically `Avatar.Image` and `Avatar.Fallback` |
+| className | `string` | — | No | Additional class on the root |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other root attributes |
+
+### Avatar.Image
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| src | `string` | — | Yes | Image URL; changing `src` remounts the image and resets status |
+| alt | `string` | `""` | No | Alternative text for the image |
+| className | `string` | — | No | Class on the `img` |
+| …rest | `Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" \| "alt">` | — | No | e.g. `loading`, `decoding`, event handlers |
+
+### Avatar.Fallback
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| children | `React.ReactNode` | — | No | Initials, icon, or placeholder |
+| className | `string` | — | No | Class on the `span` |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other attributes |
+
+### Avatar.Group.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | same as `Avatar.Root` | `"m"` | No | Size applied to child `Avatar.Root` and `Avatar.Group.Overflow` without their own `size` |
+| children | `React.ReactNode` | — | No | `Avatar.Root` nodes and optional `Avatar.Group.Overflow` |
+| className | `string` | — | No | Class on the group container |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes |
+
+### Avatar.Group.Overflow
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| size | same as `Avatar.Root` | `"m"` | No | Local size when not inherited from the group |
+| children | `React.ReactNode` | — | No | e.g. `+3` |
+| className | `string` | — | No | Class on the overflow cell |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes |
+
+## Related
+
+- [Button](../button/COMPONENT.md)
+- [Dropdown](../dropdown/COMPONENT.md)
+- [Label](../label/COMPONENT.md)
+- [Tooltip](../tooltip/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)

package/src/components/badge/COMPONENT.md

@@ -0,0 +1,78 @@
+# Badge
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+A compact, non-interactive label for status, category, or counts. Optional `Badge.Dot` and `Badge.Icon` slots align a decorative dot or an icon with text; `variant="status"` adds a built-in presence dot and live-region semantics.
+
+- **When to use:** surface short metadata next to headings, table rows, or list items (stage, environment, stock, role).
+- **When to use:** show presence or mode with `variant="status"` when short visible copy fits the layout; use `label` when screen readers need more than `children` alone (see Rules).
+- **When to use:** pair a semantic `color` and `variant` (`filled`, `light`, `lighter`, `stroke`) with density and emphasis needs on dashboards and catalogs.
+- **When to use:** combine `Badge.Icon` with text or icon-only content when the icon should inherit badge sizing from `ControlSizeProvider`.
+- **When not to use:** as the primary control for a click or navigation — use [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md) instead.
+- **When not to use:** for removable or selectable tags — use [Tag](../tag/COMPONENT.md).
+- **When not to use:** for keyboard shortcut glyphs — use [Kbd](../kbd/COMPONENT.md).
+
+## Composition
+
+- **`Badge.Root`** — root `div`; wraps `children` in `ControlSizeProvider` so nested icons can inherit control size. With **`variant="status"`**, renders a built-in status dot (`aria-hidden`), sets `role="status"`, optional `aria-label` from `label`, and ignores `color` for styling (dot color follows `status`).
+- **`Badge.Dot`** — optional decorative dot inside the label (`span`, `aria-hidden`); use with non-status variants when you need a manual indicator next to text or icons.
+- **`Badge.Icon`** — optional `span` wrapper for an icon node; place it before or after text, or use it alone for icon-only badges. Order of `Dot`, `Icon`, and text is up to layout needs.
+
+### Minimal example
+
+```tsx
+import { Badge } from "prime-ui-kit";
+
+export function Example() {
+  return <Badge.Root>New</Badge.Root>;
+}
+```
+
+## Rules
+
+- Omit `size` to inherit from the nearest `ControlSizeProvider` / control-surface context; if none is present, the effective size is **`m`**. Context value **`xs`** maps to badge size **`s`**.
+- With **`variant="status"`**, pass **`label`** when visible `children` alone are not enough for assistive tech (e.g. a generic word without whose status it is).
+- **`Badge.Dot`** (both manual and the built-in status dot) is **`aria-hidden`** — do not rely on it alone to communicate state.
+- **`disabled`** dims the badge via `data-disabled`; there is no loading, error, or focus ring — the badge is not keyboard-operable.
+- **`color`** applies only when **`variant` is not `"status"`**; for status mode, dot appearance is driven by **`status`** (default **`online`** when unset).
+
+## API
+
+### Badge.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `color` | `"gray" \| "red" \| "blue" \| "green" \| "orange" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | No | Semantic palette; ignored for styling when `variant="status"`. |
+| `variant` | `"filled" \| "light" \| "lighter" \| "stroke" \| "status"` | `"light"` | No | Fill, stroke, or status layout with built-in dot. |
+| `size` | `"s" \| "m" \| "l" \| "xl"` | from context or `"m"` | No | Explicit size; otherwise derived from control surface context, else `"m"`. |
+| `disabled` | `boolean` | — | No | Muted look; sets `data-disabled`. |
+| `status` | `"online" \| "offline" \| "away" \| "busy"` | `"online"` | No | Dot semantics when `variant="status"`; ignored otherwise. |
+| `label` | `string` | — | No | `aria-label` on the root when `variant="status"`. |
+| `children` | `React.ReactNode` | — | No | Text, `Badge.Dot`, `Badge.Icon`, or icons. |
+| `className` | `string` | — | No | Extra class on the root. |
+| … | `React.HTMLAttributes<HTMLDivElement>` | — | No | Other attributes and `ref` on the root `div`. |
+
+### Badge.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `children` | `React.ReactNode` | — | Yes | Icon node. |
+| `className` | `string` | — | No | Wrapper class. |
+| … | `Omit<React.HTMLAttributes<HTMLDivElement>, "children">` | — | No | Other wrapper attributes. |
+
+### Badge.Dot
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `className` | `string` | — | No | Extra class on the dot. |
+| … | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other `span` attributes; node is `aria-hidden`. |
+
+## Related
+
+- [Tag](../tag/COMPONENT.md)
+- [Typography](../typography/COMPONENT.md)
+- [Button](../button/COMPONENT.md)
+- [LinkButton](../link-button/COMPONENT.md)
+- [Kbd](../kbd/COMPONENT.md)

package/src/components/banner/COMPONENT.md

@@ -0,0 +1,118 @@
+# Banner
+
+**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+
+## About
+
+An in-flow announcement strip: a root grid with a central content column and an optional dismiss control on the right. Use `status` and `variant` for semantic color and density; optional slots cover icon, title, description, and actions.
+
+- **Use** for persistent page- or section-level messages (policy, incident, feature, validation summary) where the user should read the text in context.
+- **Use** when you need optional actions (`Banner.Actions`) or dismiss without leaving the page.
+- **Use** `size` to align spacing and typography with surrounding controls (`ControlSizeProvider` context applies to `Banner.CloseButton`).
+- **Do not use** for transient overlay feedback; prefer [Notification](../notification/COMPONENT.md) or similar patterns.
+- **Do not use** as a substitute for [Modal](../modal/COMPONENT.md) or [Drawer](../drawer/COMPONENT.md) when the user must complete a blocking task.
+- **Do not use** decorative icons without `aria-hidden` (or an accessible name) when the icon is not redundant with the title.
+
+## Composition
+
+- `Banner.Root` is the outer `div` and size provider; pass `variant`, `status`, `size`, and optionally `onDismiss`.
+- Put primary copy inside `Banner.Content`. Typical order: `Banner.Icon` (optional), `Banner.Title`, `Banner.Description` (optional), `Banner.Actions` (optional).
+- `Banner.CloseButton` must be a **direct child** of `Banner.Root` (a sibling of `Banner.Content`, not nested inside `Content`). The implementation only scans **direct** children to decide whether to inject a default close button when `onDismiss` is set; a close control placed only inside `Banner.Content` does not suppress injection.
+- If `onDismiss` is provided and no direct child is `Banner.CloseButton`, the root appends a default close button that calls `onDismiss`.
+
+### Minimal example
+
+```tsx
+import { Banner } from "prime-ui-kit";
+
+export function Example() {
+  return (
+    <Banner.Root>
+      <Banner.Content>
+        <Banner.Title>Title</Banner.Title>
+      </Banner.Content>
+    </Banner.Root>
+  );
+}
+```
+
+## Rules
+
+- There is no `open` / `visible` prop: mount or unmount the root (or hide it with parent state) to show or hide the strip.
+- `variant` defaults to `filled`; `status` to `information`; `size` to `m`. `stroke` uses a neutral surface with a status-colored bottom accent bar.
+- Decorative icons: pass `aria-hidden` on the underlying SVG/component when the title already conveys the message.
+- For a meaningful page-level region, set `role="region"` and `aria-label` or `aria-labelledby` on `Banner.Root` via standard HTML attributes.
+- The auto-injected dismiss control uses `aria-label="Dismiss"`; set an explicit `aria-label` (or equivalent) on a custom `Banner.CloseButton` in the product language.
+- `Banner.Title` and `Banner.Description` render as `span` elements; keep markup intentional if you nest interactive elements.
+- `Banner.Icon` is driven by the `as` prop (not `asChild` on the root).
+
+## API
+
+### Banner.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| variant | `"filled" \| "light" \| "lighter" \| "stroke"` | `"filled"` | No | Background density and accent treatment (`stroke` adds a status-colored bottom bar). |
+| status | `"information" \| "warning" \| "error" \| "success" \| "feature"` | `"information"` | No | Semantic palette for the strip. |
+| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Spacing and type scale; feeds `Banner.CloseButton` via control-size context. |
+| onDismiss | `() => void` | — | No | When set and no direct `Banner.CloseButton` child exists, renders a default close button that invokes this callback. |
+| className | `string` | — | No | Additional class on the root `div`. |
+| children | `React.ReactNode` | — | No | Typically `Banner.Content` and optionally `Banner.CloseButton`. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the root `div` (e.g. `id`, `role`, ARIA). |
+
+### Banner.Content
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the content column `div`. |
+| children | `React.ReactNode` | — | No | Icon, title, description, and/or actions. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the inner `div`. |
+
+### Banner.Icon
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| as | `React.ElementType` | `"div"` | No | Element or component to render (often an icon component). |
+| className | `string` | — | No | Additional class on the wrapper. |
+| children | `React.ReactNode` | — | No | Content when using the default element or a custom wrapper. |
+| …rest | props of `T` without `as` and `className` | — | No | Forwarded to the element chosen by `as`. |
+
+### Banner.Title
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the `span`. |
+| children | `React.ReactNode` | — | No | Primary heading text. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
+
+### Banner.Description
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the `span`. |
+| children | `React.ReactNode` | — | No | Supporting text. |
+| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Native `span` attributes. |
+
+### Banner.Actions
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Additional class on the actions row `div`. |
+| children | `React.ReactNode` | — | No | Action controls (e.g. `Button`, `LinkButton`). |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native attributes on the row `div`. |
+
+### Banner.CloseButton
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| type | `"button" \| "submit" \| "reset"` | `"button"` | No | Native `button` type. |
+| className | `string` | — | No | Additional class on the button. |
+| children | `React.ReactNode` | — | No | Button content; defaults to a cross icon when omitted. |
+| …rest | `Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "size">` | — | No | Other button props; `size` is derived from banner context. |
+
+## Related
+
+- [Button](../button/COMPONENT.md) — actions inside `Banner.Actions`; `Banner.CloseButton` wraps `Button.Root` (ghost neutral).
+- [LinkButton](../link-button/COMPONENT.md) — text-style navigation actions in the strip.
+- [Typography](../typography/COMPONENT.md) — surrounding captions or body copy outside the banner slots.
+- [Notification](../notification/COMPONENT.md) — transient or stacked overlay messages instead of an in-flow strip.