prime-ui-kit 0.10.0 → 0.11.0

package/src/components/chat/examples/search.tsx

@@ -0,0 +1,61 @@
+/** Search and pinned messages: the search bar marks every match in the texts and transcripts, counts them and steps between them while the others step back; a pinned message's press jumps to it and blinks the others — `Chat.SearchButton`, `Chat.Search`, `defaultSearch`, `Chat.Pinned`. */
+import { Card, Chat, Message, VoicePlayer } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const AUDIO = "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3";
+const WAVE = [0.3, 0.6, 0.4, 0.8, 0.5, 0.9, 0.6, 0.35, 0.7, 0.5, 0.3, 0.6, 0.8, 0.45, 0.25, 0.5];
+
+const PINNED = [{ value: "p1", text: "Реквизиты склада для накладных" }];
+
+const LINES = [
+  "Счёт INV-3010 выставлен, проверьте реквизиты.",
+  "Склад подтвердил отгрузку по заказу №3011.",
+  "Бухгалтерия закрыла акт сверки за неделю.",
+  "Счёт INV-3013 оплачен, закрываю заказ.",
+  "Поставщик прислал новые цены.",
+  "Заказ №3015 собран, ждём курьера.",
+];
+
+export default function ChatSearchExample() {
+  return (
+    <Card.Root className={styles.short}>
+      <Chat.Root defaultSearch="счёт">
+        <Chat.Header>
+          <Chat.Title>Склад и бухгалтерия</Chat.Title>
+          <Chat.Description>4 участника</Chat.Description>
+          <Chat.Actions>
+            <Chat.SearchButton />
+          </Chat.Actions>
+        </Chat.Header>
+        <Chat.Search />
+        <Chat.Pinned items={PINNED} />
+        <Chat.Messages>
+          <Message.Root value="p1" time="09:00">
+            <Message.Text>
+              Реквизиты склада для накладных: ИНН 7701234567, КПП 770101001.
+            </Message.Text>
+          </Message.Root>
+          {LINES.map((line, index) => (
+            <Message.Root
+              key={line}
+              value={`l${index}`}
+              direction={index % 3 === 2 ? "outgoing" : "incoming"}
+              time={`10:${String(10 + index).padStart(2, "0")}`}
+            >
+              <Message.Text>{line}</Message.Text>
+            </Message.Root>
+          ))}
+          <Message.Root value="v1" time="11:02">
+            <VoicePlayer
+              src={AUDIO}
+              waveform={WAVE}
+              duration={12}
+              transcript="Счёт на доставку пришлю после обеда."
+            />
+          </Message.Root>
+        </Chat.Messages>
+      </Chat.Root>
+    </Card.Root>
+  );
+}

package/src/components/chat/examples/structure.tsx

@@ -0,0 +1,28 @@
+/** The list alone, written as parts: `Chat.Root` with only `Chat.Messages`, a date that stays on top while its day scrolls, an event of the chat and the unread band — `Chat.Messages`, `Chat.Separator`, `Chat.Service`, `Chat.Unread`. */
+import { Card, Chat, Message } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ChatStructureExample() {
+  return (
+    <Card.Root className={styles.short}>
+      <Chat.Root>
+        <Chat.Messages aria-label="Чат проекта «Интеграция с 1С»">
+          <Chat.Separator>12 марта</Chat.Separator>
+          <Chat.Service>Анна Котова добавила Олега Смирнова в чат</Chat.Service>
+          <Message.Root value="row-1" time="10:00">
+            <Message.Text>Олег, добро пожаловать! Вводная — в закреплённом.</Message.Text>
+          </Message.Root>
+          <Message.Root value="row-2" direction="outgoing" time="10:04" status="read">
+            <Message.Text>Спасибо, изучу до обеда.</Message.Text>
+          </Message.Root>
+          <Chat.Separator>Сегодня</Chat.Separator>
+          <Chat.Unread />
+          <Message.Root value="row-3" time="09:41">
+            <Message.Text>Обмен справочниками заработал на тестовой базе.</Message.Text>
+          </Message.Root>
+        </Chat.Messages>
+      </Chat.Root>
+    </Card.Root>
+  );
+}

package/src/components/checkbox/COMPONENT.md

@@ -46,6 +46,7 @@ Checkbox.Indicator     the box alone, no input — a mark inside option / menu r
 | `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on every toggle (not while `readOnly`). |
 | `indeterminate` | `boolean` | `false` | Mixed state (a partial «select all»): a bar instead of the check; wins over `checked` visually and sets the native `indeterminate`. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the box, the text and the gap. Without it the tier of its host (a form, a panel, a table), else `m`. |
+| `shape` | `"square" \| "circle"` | `"square"` | Outline of the box: `square` is the rounded square; `circle` is a full circle (a selection mark in lists and chats). Size, the check draw-in, the indeterminate bar and states are the same. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the unchecked box and `aria-invalid`. A non-empty `error` implies it. |
@@ -68,12 +69,21 @@ Checkbox.Indicator     the box alone, no input — a mark inside option / menu r
 | `checked` | `boolean` | `false` | Shows the check. |
 | `indeterminate` | `boolean` | `false` | Shows the bar; wins over `checked`. |
 | `disabled` | `boolean` | `false` | Disabled fill. |
+| `shape` | `"square" \| "circle"` | `"square"` | Outline of the box: `square` is the rounded square; `circle` is a full circle (a selection mark in lists and chats). The rest is the same. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | — | Box tier; without it the nearest control size (the Select or menu it sits in), else `m`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className`, `data-*` and the other span attributes. |
 
 ## Variants
 Checkbox has no `variant` / `tone` / `color`.
 
+### shape
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `square` | rounded square (radius from the tier) | forms, settings, tables | yes |
+| `circle` | full circle, the same size, check and states | selection marks in lists and chat messages | |
+
+The circle changes only the outline (`--prime-radius-full`); the check draw-in, the indeterminate bar, focus ring and touch target are the square's. `Checkbox.Indicator` takes the same `shape`.
+
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -109,7 +119,7 @@ Checkbox has no `variant` / `tone` / `color`.
 | pressed | pointer press | the box scales to the compact press scale |
 | focus-visible | keyboard focus | outer focus ring around the box |
 
-Root also carries `data-size`. Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
+Root also carries `data-size`; the box carries `data-shape`. Controlled: `checked` + `onCheckedChange`. Uncontrolled: `defaultChecked` (+ optional `onCheckedChange`). There is no native `onChange` prop.
 
 ## Layout & spacing
 - Grid `[box][text]`; the hint or error sits under the text column, not under the box.
@@ -140,6 +150,7 @@ No `labels`.
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A checkbox with its label; a click anywhere on the row toggles it. |
+| [variants.tsx](examples/variants.tsx) | The rounded square next to the circle, in three states — `shape`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the box and the text follow the control tier — `size`. |
 | [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. |
 | [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. |
@@ -156,5 +167,5 @@ No `labels`.
 - `style` on `Checkbox.Root` expecting to style the field → it goes to the hidden input; use `className`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (the row), [Hint](../hint/COMPONENT.md) (`hint`, `error`)
-- **See also:** [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md)
+- **Built from:** [Hint](../hint/COMPONENT.md) (`hint`, `error`); the row is a native `<label>`
+- **See also:** [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md); `Checkbox.Indicator` inside [Select](../select/COMPONENT.md) and [TagSelect](../tag-select/COMPONENT.md) rows

package/src/components/checkbox/examples/variants.tsx

@@ -0,0 +1,30 @@
+/** The rounded square next to the circle, in three states — `shape`. */
+import { Checkbox } from "prime-ui-kit";
+
+const SHAPES = ["square", "circle"] as const;
+
+export default function CheckboxVariantsExample() {
+  return (
+    <>
+      {SHAPES.map((shape) => (
+        <div key={shape}>
+          <div>
+            <Checkbox.Root shape={shape}>
+              <Checkbox.Label>{shape}</Checkbox.Label>
+            </Checkbox.Root>
+          </div>
+          <div>
+            <Checkbox.Root shape={shape} defaultChecked>
+              <Checkbox.Label>{shape} · checked</Checkbox.Label>
+            </Checkbox.Root>
+          </div>
+          <div>
+            <Checkbox.Root shape={shape} indeterminate>
+              <Checkbox.Label>{shape} · indeterminate</Checkbox.Label>
+            </Checkbox.Root>
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}

package/src/components/color-field/COMPONENT.md

@@ -0,0 +1,163 @@
+# ColorField
+
+**Category:** selection
+**Kind:** field
+
+> A form field for any color: the swatch and its hex in a field box that opens the ColorPicker in a popover.
+
+## When to use
+- A free color is a field of a form or settings page: brand, theme or button color, a chart series, a stage or project color that is not limited to a palette.
+- The value is stored as text (hex) and submitted with the form (`name`).
+- A few ready colors should sit one click away, while any other color stays possible (`presets`).
+
+## When not to use
+- The color comes from a short fixed palette and the choice should be visible at once → use [ColorSwatches](../color-swatches/COMPONENT.md).
+- A compact color next to a field or in a dense list row → use [ColorPresets](../color-picker/COMPONENT.md) (square trigger + palette).
+- The picker panel itself is the screen (a design tool, an inline editor) → compose [ColorPicker](../color-picker/COMPONENT.md) parts.
+- A plain text field for a hex code → use [Input](../input/COMPONENT.md).
+
+## Import
+```tsx
+import { ColorField } from "prime-ui-kit/color-picker";
+```
+
+ColorField ships from the `prime-ui-kit/color-picker` entry with ColorPicker: it needs the optional peer `react-aria-components`. Its styles are in `prime-ui-kit/bundle.css`.
+
+## Anatomy
+```
+ColorField                       field frame: label · field button · hint | error (single export)
+├─ button                        field trigger: color chip · hex · chevron
+├─ Popover.Content               role="dialog", the field tier
+│  └─ ColorPicker.Panel
+│     ├─ ColorPicker.Area        saturation × lightness
+│     ├─ ColorPicker.Slider      hue (+ opacity with `alpha`)
+│     ├─ ColorPicker.ChannelStrip eyedropper + hex cell
+│     └─ ColorPicker.Swatches    ready colors (`presets`)
+└─ input[type=hidden]            submits the hex (`name`)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ColorField
+`ref` → `HTMLDivElement` (the field frame). A field (label, hint / error, the field button with the color swatch, its hex and a chevron) that opens the ColorPicker panel in a Popover: area, hue, optional opacity, channels with the eyedropper, optional presets.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Controlled color: a CSS color string (hex, `rgb()`, `hsl()`). |
+| `defaultValue` | `string` | `"#000000"` | Initial color when uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Called with the new color as hex: `#RRGGBB`, or `#RRGGBBAA` when `alpha` lowers the opacity. A controlled field that does not take the value keeps its color. |
+| `presets` | `readonly ColorPreset[]` | — | Ready colors under the channels (`{ value, label }`), picked in one click; none by default. |
+| `alpha` | `boolean` | `false` | Adds the opacity slider; the value then carries alpha. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Field tier (height 28 · 32 · 36 · 40 · 48); the panel uses the same tier. |
+| `label` | `ReactNode` | — | Field label above; with the hex it names the field button. |
+| `required` | `boolean` | `false` | Red `*` after the label. |
+| `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | — | Danger ring and `aria-invalid` without a message. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disables the field: it shows the color and does not open. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring (`data-focus-ring="false"`); focus, keyboard and ARIA are unchanged. |
+| `name` | `string` | — | Form field name: a hidden input submits the hex value. |
+| `id` | `string` | — | Id of the field button; hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-label` | `string` | — | Accessible name without a visible `label`; the current hex is appended. |
+| `aria-labelledby` | `string` | — | Names the field button by an outside element. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `labels` | `Partial<ColorFieldLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+## Variants
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 field, compact panel | Dense tables and side panels | |
+| `s` | 32 field | Compact forms and popovers | |
+| `m` | 36 field | Regular forms | yes |
+| `l` | 40 field | Spacious settings pages | |
+| `xl` | 48 field | Touch-first screens | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `presets` | a row of named swatches under the channels | a few brand or palette colors should be one click away | — |
+| `alpha` | an opacity slider under the hue; the hex gets two more digits | the color may be translucent (overlays, shadows) | `false` |
+| `disabled` | disabled fill, the color shown at half opacity, does not open | not editable now | `false` |
+| `invalid` / `error` | danger ring (+ the message) | validation failed | — |
+
+**Combinations**
+- Recommended: `label` + `name` inside a form; `presets` with the brand palette; `alpha` only where transparency means something.
+- Avoid: a ColorField next to a ColorSwatches for the same value; `alpha` for colors that become text or button fills.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| closed / open | click, `Enter` · `Space`, `Escape`, an outside press | `aria-expanded` and `data-state` on the button; the chevron turns; the button keeps the focus fill while open |
+| value | `value` / `defaultValue`, the panel | the chip and the hex follow the color as it is dragged; `onValueChange` gets every change as hex |
+| invalid | `invalid` or `error` | `data-invalid="true"`, `aria-invalid` on the button; the field shakes once when an error arrives (`data-shake` on the frame) |
+| disabled | `disabled` | native `disabled` on the button, `data-disabled` on the frame; the hidden `name` input is disabled too, so the form does not submit the value |
+
+Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`. A controlled field whose parent does not take a change keeps showing the parent's color.
+
+## Layout & spacing
+- The field is 100% wide; set the width with the layout.
+- The chip is the tier icon size and sits `field-px` from the edge and from the hex, like the icon of Select or Datepicker.
+- The panel is one and a half panel widths (the area and four channel cells fit), within the viewport; it flips near the edge.
+- Label → field and field → hint use the tier `label-gap` / `hint-gap`; field → field 20.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Enter` · `Space` | Open the panel from the field; in a channel cell, apply the value. |
+| `ArrowLeft` · `ArrowRight` · `ArrowUp` · `ArrowDown` | Move the area or a channel slider; in the ready colors, move between swatches. |
+| `PageUp` · `PageDown` | Large step of the area and the sliders. |
+| `Tab` | Cycles through the parts of the panel. |
+| `Escape` | Closes the panel and returns focus to the field. |
+
+### ARIA
+- The field is a `<button>` with `aria-haspopup="dialog"` and `aria-expanded`; it is named by the label and the current hex (`aria-labelledby`), or by `aria-label` plus the hex.
+- The panel is `role="dialog"` named by the field; the area and the sliders are React Aria `role="slider"`, the sliders named by `labels.hue` and `labels.alpha`.
+- The ready colors are a `role="radiogroup"` named by `labels.presets`.
+- The hint and the error are linked by `aria-describedby`; the error sets `aria-invalid`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+| `presets` | `"Готовые цвета"` | Accessible name of the preset swatches in the panel. |
+| `hue` | `"Оттенок, градусы"` | Hue slider and the hue cell of the channels. |
+| `alpha` | `"Непрозрачность, проценты"` | Opacity slider (`alpha`) and the opacity cell. |
+| `hex` | `"Hex"` | Hex cell of the channels. |
+| `eyeDropper` | `"Пипетка"` | Eyedropper button of the channels. |
+| `format` | `"Формат значений цвета"` | Value format select (the ColorPicker labels are shared). |
+| `saturation` | `"Насыщенность, проценты"` | Saturation cell. |
+| `lightness` | `"Яркость, проценты"` | Lightness cell. |
+| `red` | `"Красный, 0–255"` | Red cell. |
+| `green` | `"Зелёный, 0–255"` | Green cell. |
+| `blue` | `"Синий, 0–255"` | Blue cell. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A brand color field: the swatch and hex open the picker in a popover, the new color applies as you drag — `label`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier: the field is 28 to 48 px high, the swatch follows the tier icon — `size`. |
+| [states.tsx](examples/states.tsx) | A default field next to an invalid one and a disabled one that shows its color but does not open — `invalid`, `disabled`. |
+| [validation.tsx](examples/validation.tsx) | A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint and an optional field — `required`, `optional`, `hint`, `error`. |
+| [presets.tsx](examples/presets.tsx) | Brand colors under the channels in the panel and a translucent overlay color — `presets`, `alpha`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color: the hint names it and a button resets it to the brand default — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | A pipeline stage form: the color goes with the form by `name`, a calm note confirms the save — `name`, `required`. |
+
+## Mistakes
+- `ColorField.Root` → ColorField is a single export: `<ColorField … />`.
+- Importing it from `prime-ui-kit` → it lives in `prime-ui-kit/color-picker` with ColorPicker.
+- A hand-built «swatch button + Popover + ColorPicker» next to a hex Input → use ColorField.
+- Expecting a `Color` object in `onValueChange` → the field speaks hex strings; use ColorPicker parts for `Color`.
+
+## Related
+- **Built from:** [ColorPicker](../color-picker/COMPONENT.md) (area, sliders, channel strip, swatches), [Popover](../popover/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md) (`presets`), [Button](../button/COMPONENT.md) (eyedropper), `Icon` (chevron), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (field frame)
+- **See also:** [ColorSwatches](../color-swatches/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md)

package/src/components/color-field/examples/controlled.tsx

@@ -0,0 +1,33 @@
+/** The parent owns the color: the hint names it and a button resets it to the brand default — `value`, `onValueChange`. */
+import { Button } from "prime-ui-kit";
+import { ColorField } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const BRAND_DEFAULT = "#5B5BD6";
+
+export default function ColorFieldControlledExample() {
+  const [accent, setAccent] = React.useState(BRAND_DEFAULT);
+
+  return (
+    <>
+      <ColorField
+        label="Акцентный цвет"
+        hint={`Сейчас: ${accent}`}
+        value={accent}
+        onValueChange={setAccent}
+      />
+      <div className={styles.actions}>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          disabled={accent === BRAND_DEFAULT}
+          onClick={() => setAccent(BRAND_DEFAULT)}
+        >
+          Цвет бренда по умолчанию
+        </Button.Root>
+      </div>
+    </>
+  );
+}

package/src/components/color-field/examples/examples.module.css

@@ -0,0 +1,22 @@
+/* Layout of the ColorField scenarios: semantic tokens only. */
+
+/* in-form.tsx: a form in a Card. */
+.formCard {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+/* Field → field 20. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+}
+
+/* A row of actions at the end. */
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}

package/src/components/color-field/examples/in-form.tsx

@@ -0,0 +1,45 @@
+/** A pipeline stage form: the color goes with the form by `name`, a calm note confirms the save — `name`, `required`. */
+import { Button, Card, Input, Typography } from "prime-ui-kit";
+import { ColorField } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ColorFieldInFormExample() {
+  const [saved, setSaved] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const data = new FormData(event.currentTarget);
+    setSaved(`Этап «${data.get("stage")}» сохранён, цвет ${data.get("stageColor")}.`);
+  };
+
+  return (
+    <Card.Root className={styles.formCard}>
+      <Card.Body>
+        <form className={styles.form} noValidate onSubmit={submit}>
+          <Input.Root label="Название этапа" required>
+            <Input.Wrapper>
+              <Input.Field name="stage" defaultValue="Переговоры" />
+            </Input.Wrapper>
+          </Input.Root>
+          <ColorField
+            label="Цвет этапа"
+            required
+            name="stageColor"
+            defaultValue="#F76B15"
+            onValueChange={() => setSaved(undefined)}
+          />
+          <div className={styles.actions}>
+            {saved ? (
+              <Typography as="p" variant="body-s" tone="secondary" role="status">
+                {saved}
+              </Typography>
+            ) : null}
+            <Button.Root type="submit">Сохранить этап</Button.Root>
+          </div>
+        </form>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/color-field/examples/overview.tsx

@@ -0,0 +1,6 @@
+/** A brand color field: the swatch and hex open the picker in a popover, the new color applies as you drag — `label`, `defaultValue`. */
+import { ColorField } from "prime-ui-kit/color-picker";
+
+export default function ColorFieldOverviewExample() {
+  return <ColorField label="Цвет бренда" defaultValue="#5b5bd6" />;
+}

package/src/components/color-field/examples/presets.tsx

@@ -0,0 +1,20 @@
+/** Brand colors under the channels in the panel and a translucent overlay color — `presets`, `alpha`. */
+import { ColorField } from "prime-ui-kit/color-picker";
+
+const BRAND_COLORS = [
+  { value: "#5b5bd6", label: "Индиго" },
+  { value: "#0090ff", label: "Синий" },
+  { value: "#12a594", label: "Бирюзовый" },
+  { value: "#30a46c", label: "Зелёный" },
+  { value: "#f76b15", label: "Оранжевый" },
+  { value: "#e5484d", label: "Красный" },
+];
+
+export default function ColorFieldPresetsExample() {
+  return (
+    <>
+      <ColorField label="Цвет проекта" defaultValue="#12a594" presets={BRAND_COLORS} />
+      <ColorField label="Затемнение обложки" defaultValue="#0000008C" alpha />
+    </>
+  );
+}

package/src/components/color-field/examples/sizes.tsx

@@ -0,0 +1,14 @@
+/** Every size tier: the field is 28 to 48 px high, the swatch follows the tier icon — `size`. */
+import { ColorField } from "prime-ui-kit/color-picker";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ColorFieldSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <ColorField key={size} size={size} label={size} defaultValue="#0090ff" />
+      ))}
+    </>
+  );
+}

package/src/components/color-field/examples/states.tsx

@@ -0,0 +1,12 @@
+/** A default field next to an invalid one and a disabled one that shows its color but does not open — `invalid`, `disabled`. */
+import { ColorField } from "prime-ui-kit/color-picker";
+
+export default function ColorFieldStatesExample() {
+  return (
+    <>
+      <ColorField label="default" defaultValue="#30a46c" />
+      <ColorField label="invalid" defaultValue="#f5f5f5" invalid />
+      <ColorField label="disabled" defaultValue="#30a46c" disabled />
+    </>
+  );
+}

package/src/components/color-field/examples/validation.tsx

@@ -0,0 +1,29 @@
+/** A button color checked live: a too light color shakes in an error that leaves once the color is darker; a hint and an optional field — `required`, `optional`, `hint`, `error`. */
+import { ColorField, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+const MAX_LIGHTNESS = 80;
+
+/** The error for a color white text cannot sit on, or nothing. */
+function contrastError(value: string) {
+  const lightness = parseColor(value).toFormat("hsl").getChannelValue("lightness");
+  return lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined;
+}
+
+export default function ColorFieldValidationExample() {
+  const [buttonColor, setButtonColor] = React.useState("#F2F2F2");
+
+  return (
+    <>
+      <ColorField
+        label="Цвет кнопок"
+        required
+        hint="Под белый текст кнопки"
+        value={buttonColor}
+        onValueChange={setButtonColor}
+        error={contrastError(buttonColor)}
+      />
+      <ColorField label="Цвет ссылок" optional defaultValue="#0090ff" />
+    </>
+  );
+}