prime-ui-kit 0.7.13 → 0.9.0

package/src/components/tabs/examples/two-line.tsx

@@ -0,0 +1,63 @@
+/** Two-line tabs: `Tabs.Label` + `Tabs.Count` on the first line, `Tabs.Description` with a `<strong>` value on the second. Use for dashboard sections that need a summary per tab. */
+import { type PaletteColor, Tabs, Typography } from "prime-ui-kit";
+import { useState } from "react";
+
+import styles from "./examples.module.css";
+
+const sections: {
+  value: string;
+  title: string;
+  count: number;
+  color: PaletteColor;
+  strong: string;
+  rest: string;
+}[] = [
+  { value: "new", title: "Новые", count: 12, color: "blue", strong: "3", rest: " срочных" },
+  {
+    value: "progress",
+    title: "В работе",
+    count: 5,
+    color: "orange",
+    strong: "2",
+    rest: " просрочены",
+  },
+  { value: "done", title: "Готово", count: 148, color: "green", strong: "31", rest: " за неделю" },
+  {
+    value: "returns",
+    title: "Возвраты",
+    count: 4,
+    color: "red",
+    strong: "1",
+    rest: " ждёт решения",
+  },
+];
+
+export default function TabsTwoLineExample() {
+  const [value, setValue] = useState("new");
+
+  return (
+    <div className={styles.fleet}>
+      <Tabs.Root value={value} onValueChange={setValue}>
+        <Tabs.List aria-label="Заказы">
+          {sections.map((s) => (
+            <Tabs.Trigger key={s.value} value={s.value}>
+              <Tabs.Label>{s.title}</Tabs.Label>
+              <Tabs.Count color={s.color}>{s.count}</Tabs.Count>
+              <Tabs.Description>
+                <strong>{s.strong}</strong>
+                {s.rest}
+              </Tabs.Description>
+            </Tabs.Trigger>
+          ))}
+        </Tabs.List>
+        {sections.map((s) => (
+          <Tabs.Panel key={s.value} value={s.value}>
+            <Typography.Root variant="body-m" tone="secondary">
+              {s.title}: {s.count} заказов.
+            </Typography.Root>
+          </Tabs.Panel>
+        ))}
+      </Tabs.Root>
+    </div>
+  );
+}

package/src/components/tabs/examples/vertical.tsx

@@ -0,0 +1,101 @@
+/** Vertical settings tabs inside a card: pill items on the side, section heading aligned with the first tab; stacks on top below 600px. Use for settings pages with several sections. */
+import { Bell, Trash2, UserRound } from "lucide-react";
+import { Button, Input, Switch, Tabs, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TabsVerticalExample() {
+  return (
+    <div className={styles.card}>
+      <Tabs.Root orientation="vertical" defaultValue="notifications">
+        <Tabs.List aria-label="Настройки">
+          <Tabs.Trigger value="profile">
+            <Tabs.Icon>
+              <UserRound />
+            </Tabs.Icon>
+            <Tabs.Label>Профиль</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="notifications">
+            <Tabs.Icon>
+              <Bell />
+            </Tabs.Icon>
+            <Tabs.Label>Уведомления</Tabs.Label>
+          </Tabs.Trigger>
+          <Tabs.Trigger value="danger">
+            <Tabs.Icon>
+              <Trash2 />
+            </Tabs.Icon>
+            <Tabs.Label>Удаление</Tabs.Label>
+          </Tabs.Trigger>
+        </Tabs.List>
+
+        <Tabs.Panel value="profile">
+          <div className={styles.section}>
+            <div className={styles.sectionHead}>
+              <Typography.Root as="h3" variant="title-s">
+                Профиль
+              </Typography.Root>
+            </div>
+            <div className={styles.form}>
+              <Input.Root label="Имя">
+                <Input.Wrapper>
+                  <Input.Field defaultValue="Анна Соколова" />
+                </Input.Wrapper>
+              </Input.Root>
+              <Input.Root label="Должность" optional>
+                <Input.Wrapper>
+                  <Input.Field placeholder="Например, продакт-менеджер" />
+                </Input.Wrapper>
+              </Input.Root>
+              <div>
+                <Button.Root>Сохранить</Button.Root>
+              </div>
+            </div>
+          </div>
+        </Tabs.Panel>
+
+        <Tabs.Panel value="notifications">
+          <div className={styles.section}>
+            <div className={styles.sectionHead}>
+              <Typography.Root as="h3" variant="title-s">
+                Уведомления
+              </Typography.Root>
+            </div>
+            <div className={styles.rows}>
+              <Switch.Root defaultChecked>
+                <Switch.Label>Письма о новых заказах</Switch.Label>
+                <Switch.Hint>Сразу после оформления заказа.</Switch.Hint>
+              </Switch.Root>
+              <Switch.Root>
+                <Switch.Label>Еженедельная сводка</Switch.Label>
+                <Switch.Hint>По понедельникам в 9:00.</Switch.Hint>
+              </Switch.Root>
+              <Switch.Root defaultChecked>
+                <Switch.Label>Push-уведомления</Switch.Label>
+                <Switch.Hint>В браузере, пока открыта вкладка.</Switch.Hint>
+              </Switch.Root>
+            </div>
+          </div>
+        </Tabs.Panel>
+
+        <Tabs.Panel value="danger">
+          <div className={styles.section}>
+            <div className={styles.sectionHead}>
+              <Typography.Root as="h3" variant="title-s">
+                Удаление аккаунта
+              </Typography.Root>
+            </div>
+            <Typography.Root variant="body-m" tone="secondary">
+              Аккаунт и все данные будут удалены без возможности восстановления.
+            </Typography.Root>
+            <div>
+              <Button.Root variant="outline" tone="danger">
+                Удалить аккаунт
+              </Button.Root>
+            </div>
+          </div>
+        </Tabs.Panel>
+      </Tabs.Root>
+    </div>
+  );
+}

package/src/components/tag/COMPONENT.md

@@ -1,97 +1,179 @@
 # Tag
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+**Category:** data-display
 
-## About
+> A chip for a selected value, applied filter or keyword, with an optional remove button and a palette color.
 
-A compact chip-style label: optional leading icon (`Tag.Icon`), optional removable close control when `onRemove` is set. Root is a `span` with `data-size` / `data-disabled`; the inner body wraps children in `ControlSizeProvider` so nested icons pick up the same control size tier.
+## When to use
+- Applied filters above a list or table, each one removable.
+- Selected values (cities, people, keywords) shown as chips.
+- Keywords or categories of an item, optionally colored by category.
 
-**When to use**
-
-- Filter chips and applied facets where each selection should be dismissible in one click.
-- Selected values (recipients, skills, topics) with optional removal.
-- Tight metadata labels (environment, version, channel) when a pill shape reads better than body text; add `Tag.Icon` when a small glyph clarifies meaning.
-
-**When not to use**
-
-- As a toggle or single-choice control — prefer [Checkbox](../checkbox/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md), or [Select](../select/COMPONENT.md).
-- When the whole chip must navigate or submit a primary action — prefer [Button](../button/COMPONENT.md) or [LinkButton](../link-button/COMPONENT.md).
-- Expecting localized copy for the remove control without wrapping — the built-in remove `aria-label` is fixed to `"Remove"` in source; name the surrounding group (`aria-label` / `aria-labelledby`) for context.
-- As a numeric or status **badge** — prefer [Badge](../badge/COMPONENT.md) when the UI is count-only or notification-style.
-
-## Composition
-
-- **`Tag.Root`** — outer `span`; holds a **`span`** body with **`ControlSizeProvider`** around **`children`**, then an optional remove **`button`** when **`onRemove`** is defined. Put plain text, **`Tag.Icon`**, or other nodes inside **`Tag.Root`**; place **`Tag.Icon`** before text when both are used so the icon sits on the left.
-- **`Tag.Icon`** — wrapper **`span`** for the icon node; inherits size from the surrounding **`Tag.Root`** context.
-
-### Canonical example
+## When not to use
+- A read-only status or counter → use [Badge](../badge/COMPONENT.md).
+- Choosing several values from a list in a field → use [TagSelect](../tag-select/COMPONENT.md) (it renders tags itself).
+- A toggle or a choice between options → use [ButtonGroup](../button-group/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md) or [Checkbox](../checkbox/COMPONENT.md).
+- A keyboard shortcut → use [Kbd](../kbd/COMPONENT.md).
 
+## Import
 ```tsx
 import { Tag } from "prime-ui-kit";
-
-export function Example() {
-  return <Tag.Root>Design systems</Tag.Root>;
-}
 ```
 
-### Scenarios (playground + `examples/`)
-
-Live demos use **`playground/snippets/tag/*.tsx`** (see **`playground/sections/TagSection.tsx`**). The table lists the same scenarios with package-oriented copies under **`examples/`** (aligned with those snippets; playground uses `@/` imports and shared `playground.css` layout classes).
-
-| Scenario | Snippet | Package example |
-|----------|---------|-----------------|
-| Sizes | [`playground/snippets/tag/sizes.tsx`](../../../playground/snippets/tag/sizes.tsx) | [`examples/sizes.tsx`](./examples/sizes.tsx) |
-| States | [`playground/snippets/tag/states.tsx`](../../../playground/snippets/tag/states.tsx) | [`examples/states.tsx`](./examples/states.tsx) |
-| Composition | [`playground/snippets/tag/composition.tsx`](../../../playground/snippets/tag/composition.tsx) | [`examples/composition.tsx`](./examples/composition.tsx) |
-| Basic | [`playground/snippets/tag/basic.tsx`](../../../playground/snippets/tag/basic.tsx) | [`examples/basic.tsx`](./examples/basic.tsx) |
-| Removable (dismiss + restore) | [`playground/snippets/tag/removable.tsx`](../../../playground/snippets/tag/removable.tsx) | [`examples/removable.tsx`](./examples/removable.tsx) |
-| With icon | [`playground/snippets/tag/with-icon.tsx`](../../../playground/snippets/tag/with-icon.tsx) | [`examples/with-icon.tsx`](./examples/with-icon.tsx) |
-| Controlled list | [`playground/snippets/tag/controlled.tsx`](../../../playground/snippets/tag/controlled.tsx) | [`examples/controlled.tsx`](./examples/controlled.tsx) |
-| Disabled | [`playground/snippets/tag/disabled.tsx`](../../../playground/snippets/tag/disabled.tsx) | [`examples/disabled.tsx`](./examples/disabled.tsx) |
-| Context `size` | [`playground/snippets/tag/context-size.tsx`](../../../playground/snippets/tag/context-size.tsx) | [`examples/context-size.tsx`](./examples/context-size.tsx) |
-
-**Additional extended examples** (richer layout / copy, same building blocks):
-
-- [`./examples/01-filter-chips.tsx`](./examples/01-filter-chips.tsx) — Catalog filters: applied facets as removable chips backed by a `Set` in state (`fieldset` + `legend`).
-- [`./examples/02-removable-selected-values.tsx`](./examples/02-removable-selected-values.tsx) — Selected skills: removable tags in a named group for remove-button context.
-- [`./examples/03-status-metadata.tsx`](./examples/03-status-metadata.tsx) — Release-style metadata: read-only chips with `Tag.Icon` + text, no `onRemove`.
-
-**LLM note:** Prefer reading runnable files under `./examples/*.tsx` and matching `playground/snippets/tag/*.tsx` for prop combinations; this page keeps the contract (rules + API tables) authoritative.
-
-## Rules
-
-- Omit **`size`** to follow the nearest ancestor **`ControlSizeProvider`**; context **`xs`** maps to tag size **`s`**. With no provider and no **`size`**, the effective size is **`m`**.
-- **`onRemove`** is optional; when present, a **`type="button"`** remove control is rendered with **`aria-label="Remove"`** and **`aria-hidden`** on the cross SVG. **`disabled`** sets **`aria-disabled`** on the root and disables the remove button.
-- Without **`onRemove`**, there is no focusable control inside the tag; the root is not a button or link.
-- For lists of removable tags, name the group so “Remove” has context — e.g. **`fieldset`** + **`legend`** (as in `./examples`) or **`aria-label`** / **`aria-labelledby`** on a suitable wrapper.
-- **`Tag.Icon`** does not force **`aria-hidden`** on icons; if the icon is decorative, rely on adjacent text or set **`aria-hidden`** on the icon content yourself.
-- There is no **`variant`** prop; appearance follows **`size`** and whether removal is enabled.
+## Anatomy
+```
+Tag.Root              span: fill, tier dimensions
+├── body              text and Tag.Icon (ellipsis area)
+│   ├── Tag.Icon      optional leading icon
+│   └── text
+└── remove button     rendered only with onRemove
+```
 
 ## API
 
 ### Tag.Root
+Forwards `ref` to the root `<span>`. No `asChild`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` (`PaletteColor`) | `"gray"` | Palette hue of the fill and text. |
+| `variant` | `"soft" \| "outline"` | `"soft"` | Treatment. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` (`ControlSize`) | — (inherited, else `"m"`) | Badge tier. Without it the tag follows the surrounding control one tier down; outside a control it is `m`. |
+| `onRemove` | `() => void` | — | Shows the remove button; called on its click. |
+| `labels` | `Partial<TagLabels>` | `{ remove: "Удалить" }` | System strings, see Accessibility. |
+| `disabled` | `boolean` | — | Muted look, `aria-disabled` on the root, remove button natively disabled. |
+| `children` | `ReactNode` | — | Text and an optional leading `Tag.Icon`. |
+| `className` | `string` | — | Extra class on the root. |
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` or from `ControlSizeProvider` | No | Visual tier for height, radius, text, and nested icon scale |
-| onRemove | `() => void` | — | No | When set, renders the remove button on the right |
-| disabled | `boolean` | — | No | Disables removal and sets `aria-disabled` on the root |
-| children | `React.ReactNode` | — | No | Text, `Tag.Icon`, or other nodes |
-| className | `string` | — | No | Extra class on the root `span` |
-| …rest | `React.HTMLAttributes<HTMLSpanElement>` | — | No | Other root attributes (`data-*`, `aria-*`, etc.) |
++ native `<span>` props (`HTMLAttributes<HTMLSpanElement>`).
 
 ### Tag.Icon
+No ref forwarding; does not accept other native props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The icon; inherits the tag text color, sized to the tag tier. |
+| `className` | `string` | — | Extra class on the wrapper. |
+
+### TagLabels
+| Key | Default | Description |
+|---|---|---|
+| `remove` | `"Удалить"` | Accessible name of the remove button. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | Light palette fill (`palette.<hue>.soft`), hue text, no outline | Selected values and applied filters — the normal case | yes |
+| `outline` | Transparent fill, 1px inset line in the hue text at 32%, hue text | Keywords on a filled area, or secondary tags next to soft ones | |
+
+`solid` and `ghost` are not part of Tag (the type allows only `soft | outline`).
+
+### color
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | Neutral gray wash and text | Plain values and filters | yes |
+| `blue` | Blue | Category hue | |
+| `green` | Green | Category hue | |
+| `orange` | Orange | Category hue | |
+| `red` | Red | Category hue | |
+| `yellow` | Yellow | Category hue | |
+| `purple` | Purple | Category hue | |
+| `sky` | Sky blue | Category hue | |
+| `pink` | Pink | Category hue | |
+| `teal` | Teal | Category hue | |
+
+Use hues only to group tags by category (one hue per category, consistent across screens). Applied filters stay `gray`.
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 16px high, padding 4, text 12, icon 12 | Inside `xs`/`s` controls | |
+| `s` | 20px high, padding 6, text 12, icon 12 | Inside `m` controls (inherited automatically), dense rows | |
+| `m` | 24px high, padding 8, text 12, icon 14 | Standalone filter rows and lists | yes (outside controls) |
+| `l` | 28px high, padding 10, text 13, icon 16 | Larger filter panels | |
+| `xl` | 32px high, padding 12, text 14, icon 16 | Large headers | |
+
+### removable (visual flag, from `onRemove`)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| no `onRemove` | Text only | Read-only values | yes |
+| `onRemove` set | Trailing × button the size of the tier icon, end padding reduced to 4px (`data-removable`) | The user can drop the value | |
+
+### disabled (visual flag)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` / unset | Variant colors | Normal | yes |
+| `true` | Muted fill (`fill-muted`), disabled text, no outline; remove button disabled | The value cannot be changed right now | |
+
+**Combinations**
+- Recommended: `soft` `gray` + `onRemove` for applied filters; `soft` hue for categorized keywords.
+- Allowed but rare: `outline` hue for keywords on a tinted area.
+- Avoid: many different hues in one filter row (noise); `disabled` + `onRemove` when the value will never be removable (drop the button instead).
+
+**Sizes**
+Same tiers as Badge and Kbd. Without `size` inside a control: `xs`/`s` → `xs`, `m` → `s`, `l` → `m`, `xl` → `l`. Outside a control: `m` (24px).
+
+**Hierarchy**
+Tags are secondary content: put the "Сбросить все" action as a `ghost` `s` Button next to them, not as another tag.
+
+## States
+| State / attribute | Driven by | Notes |
+|---|---|---|
+| `data-color` | `color` | Always set (default `gray`). |
+| `data-variant` | `variant` | Always set (default `soft`). |
+| `data-size` | `size`, else surrounding control size, else `m` | Nominal size. |
+| `data-tier` | resolved tier | One step down from the control when inherited. Drives dimensions. |
+| `data-removable="true"` | `onRemove` | Remove button rendered. |
+| `data-disabled="true"` + `aria-disabled` | `disabled` | Muted look; remove button `disabled`. |
+| remove hover | pointer over × | `fill-subtle-active` wash under the icon. |
+| remove focus-visible | keyboard focus on × | Focus ring around the button. |
+
+Tag has no internal state: the list of tags is controlled by the parent (remove the item in `onRemove`).
+
+## Layout & spacing
+- `width: fit-content`, never stretches in a column; `max-width: 100%`, text does not wrap.
+- A row of tags: flex-wrap with `gap: var(--prime-space-2)`.
+- Filter panel: title row and tag row separated by `--prime-space-3`.
+- The × hit area extends 4px (`--prime-space-1`) beyond the visual icon.
+
+## Accessibility
+- The tag itself is static text and not focusable; only the remove `<button type="button">` takes focus.
+- The remove button needs a unique name: pass ``labels={{ remove: `Убрать фильтр «${label}»` }}`` so screen readers do not hear several identical «Удалить».
+- After removing, move focus to a neighbouring tag or to the field the filter came from.
+- `labels.remove` — default `"Удалить"`.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | Removable tags in tiers xs–xl | Matching the density of a row |
+| [colors.tsx](examples/colors.tsx) | Ten hues in `soft` (removable) and `outline` | Categorized tags |
+| [states.tsx](examples/states.tsx) | Read-only, removable, disabled, disabled + removable | Choosing the state of a tag |
+| [with-icon.tsx](examples/with-icon.tsx) | Leading `Tag.Icon`, with and without remove | Value types (email, privacy) |
+| [surfaces.tsx](examples/surfaces.tsx) | Tags on canvas, card and floating layer | Checking contrast on any surface |
+| [applied-filters.tsx](examples/applied-filters.tsx) | Filter panel with per-tag remove and "Сбросить все" | Filters above lists and tables |
+
+```tsx
+import { Tag } from "prime-ui-kit";
+
+export function CityFilter({ onRemove }: { onRemove: () => void }) {
+  return (
+    <Tag.Root labels={{ remove: "Убрать фильтр «Москва»" }} onRemove={onRemove}>
+      Москва
+    </Tag.Root>
+  );
+}
+```
 
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | Yes | Icon or other content |
-| className | `string` | — | No | Extra class on the wrapper |
+## Mistakes
+- Tag as a read-only status "Оплачен" → use `Badge`.
+- Several tags with the default «Удалить» → pass `labels.remove` with the tag text.
+- A custom × button next to a tag → use `onRemove`.
+- `variant="solid"` on Tag → not supported; use `soft` or `outline`, or `Badge` for emphasis.
+- `<Tag.Root size="m">` inside a control → drop `size`, the tier is inherited one step down.
 
 ## Related
-
-- [Badge](../badge/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [Input](../input/COMPONENT.md)
-- [Select](../select/COMPONENT.md)
-- [LinkButton](../link-button/COMPONENT.md)
-- [SegmentedControl](../segmented-control/COMPONENT.md)
+- [Badge](../badge/COMPONENT.md) — read-only labels with the same tiers.
+- [TagSelect](../tag-select/COMPONENT.md) — multi-select field built on tags.
+- [Kbd](../kbd/COMPONENT.md) — keys and shortcuts.

package/src/components/tag/examples/applied-filters.tsx

@@ -0,0 +1,48 @@
+/** Applied filters panel: each tag removes its filter, the button clears all; `labels.remove` names the filter. Use above lists and tables with filters. */
+
+import { Button, Tag, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const INITIAL = ["Москва", "Санкт-Петербург", "Есть в наличии", "До 5 000 ₽"];
+
+export default function TagAppliedFiltersExample() {
+  const [filters, setFilters] = React.useState(INITIAL);
+  const titleId = React.useId();
+
+  return (
+    <section className={styles.filters} aria-labelledby={titleId}>
+      <div className={styles.filtersHeader}>
+        <Typography.Root as="h3" variant="title-s" id={titleId}>
+          Фильтры
+        </Typography.Root>
+        <Button.Root
+          variant="ghost"
+          tone="neutral"
+          size="s"
+          onClick={() => setFilters(filters.length > 0 ? [] : INITIAL)}
+        >
+          {filters.length > 0 ? "Сбросить все" : "Вернуть"}
+        </Button.Root>
+      </div>
+      {filters.length > 0 ? (
+        <div className={styles.tags}>
+          {filters.map((label) => (
+            <Tag.Root
+              labels={{ remove: `Убрать фильтр «${label}»` }}
+              key={label}
+              onRemove={() => setFilters((prev) => prev.filter((item) => item !== label))}
+            >
+              {label}
+            </Tag.Root>
+          ))}
+        </div>
+      ) : (
+        <Typography.Root variant="body-s" tone="muted">
+          Фильтры не выбраны — показаны все товары.
+        </Typography.Root>
+      )}
+    </section>
+  );
+}

package/src/components/tag/examples/colors.tsx

@@ -0,0 +1,49 @@
+/** Palette hues in `soft` (default) and `outline`, with and without the remove button. Use a hue to group tags by category; keep `gray` for plain values. */
+import { type PaletteColor, Tag, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const colors: PaletteColor[] = [
+  "gray",
+  "blue",
+  "sky",
+  "teal",
+  "green",
+  "yellow",
+  "orange",
+  "red",
+  "pink",
+  "purple",
+];
+
+export default function TagColorsExample() {
+  return (
+    <div className={styles.matrix}>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        soft
+      </Typography.Root>
+      <div className={styles.tags}>
+        {colors.map((color) => (
+          <Tag.Root
+            key={color}
+            color={color}
+            labels={{ remove: `Убрать «${color}»` }}
+            onRemove={() => undefined}
+          >
+            {color}
+          </Tag.Root>
+        ))}
+      </div>
+      <Typography.Root as="span" variant="caption" tone="muted">
+        outline
+      </Typography.Root>
+      <div className={styles.tags}>
+        {colors.map((color) => (
+          <Tag.Root key={color} variant="outline" color={color}>
+            {color}
+          </Tag.Root>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/tag/examples/examples.module.css

@@ -1,20 +1,47 @@
-.fieldsetPlain {
-  margin: 0;
-  padding: 0;
-  border: none;
-  min-width: 0;
+.sizes {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
 }
 
-.legend {
-  margin: 0 0 var(--prime-sys-spacing-s);
-  padding: 0;
-  font-size: var(--prime-sys-typography-sizeScale-s);
-  color: var(--prime-sys-color-content-secondary);
+.sizeCell {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.matrix {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  align-items: center;
+  column-gap: var(--prime-space-4);
+  row-gap: var(--prime-space-3);
+  width: 100%;
 }
 
-.chipRow {
+.tags {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--prime-sys-spacing-s);
   align-items: center;
+  gap: var(--prime-space-2);
+}
+
+.filters {
+  display: grid;
+  gap: var(--prime-space-3);
+  width: 100%;
+  max-width: var(--prime-modal-width-m);
+  padding: var(--prime-card-padding-m);
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-card-bg);
+}
+
+.filtersHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-3);
 }

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

@@ -1,15 +1,23 @@
-import { Tag } from "prime-ui-kit";
+/** Removable tags in the five badge tiers: 16 · 20 · 24 · 28 · 32 px, default `m`. Use to match a tag to the density of its row. */
+import { type ControlSize, Tag, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Size ladder `s` → `xl`; height, radius, type, and icon tier follow control tokens. */
-export default function TagExampleSizes() {
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+
+export default function TagSizesExample() {
   return (
-    <div className={styles.chipRow}>
-      <Tag.Root size="s">Tag s</Tag.Root>
-      <Tag.Root size="m">Tag m</Tag.Root>
-      <Tag.Root size="l">Tag l</Tag.Root>
-      <Tag.Root size="xl">Tag xl</Tag.Root>
+    <div className={styles.sizes}>
+      {sizes.map((size) => (
+        <div key={size} className={styles.sizeCell}>
+          <Tag.Root labels={{ remove: "Убрать «Москва»" }} size={size} onRemove={() => undefined}>
+            Москва
+          </Tag.Root>
+          <Typography.Root as="span" variant="caption" tone="muted">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
     </div>
   );
 }

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

@@ -1,16 +1,18 @@
+/** Read-only, removable and `disabled` tags. Only the remove button takes hover and focus; use `disabled` when the value cannot be changed right now. */
 import { Tag } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
-/** Default, removable (`onRemove`), `disabled`, and disabled with remove (inactive close control). */
-export default function TagExampleStates() {
+export default function TagStatesExample() {
   return (
-    <div className={styles.chipRow}>
-      <Tag.Root>Default</Tag.Root>
-      <Tag.Root onRemove={() => undefined}>With remove</Tag.Root>
-      <Tag.Root disabled>Disabled</Tag.Root>
-      <Tag.Root disabled onRemove={() => undefined}>
-        Disabled, remove inactive
+    <div className={styles.tags}>
+      <Tag.Root>Только чтение</Tag.Root>
+      <Tag.Root labels={{ remove: "Убрать «Удаляемый»" }} onRemove={() => undefined}>
+        Удаляемый
+      </Tag.Root>
+      <Tag.Root disabled>Отключён</Tag.Root>
+      <Tag.Root labels={{ remove: "Убрать «Заблокирован»" }} disabled onRemove={() => undefined}>
+        Заблокирован
       </Tag.Root>
     </div>
   );

package/src/components/tag/examples/surfaces.tsx

@@ -0,0 +1,16 @@
+/** Plain, removable and disabled tags that stay distinguishable on canvas, card and floating layers. Use as-is on any surface. */
+import { Tag } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function TagSurfacesExample() {
+  return (
+    <div className={styles.tags}>
+      <Tag.Root>Дизайн</Tag.Root>
+      <Tag.Root labels={{ remove: "Убрать «Маркетинг»" }} onRemove={() => undefined}>
+        Маркетинг
+      </Tag.Root>
+      <Tag.Root disabled>Архив</Tag.Root>
+    </div>
+  );
+}