prime-ui-kit 0.9.0 → 0.9.2

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

@@ -1,92 +1,30 @@
-/* Example layout: semantic tokens only. */
+/* Layout of the ColorPicker and ColorPresets scenarios: semantic tokens only. */
 
-/* Fixed width for an inline or popover panel: area + four channel fields fit. */
+/* An inline or popover panel width: the area and four channel fields fit. */
 .panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-4);
   width: calc(var(--prime-panel-min-width) * 1.5);
   max-width: 100%;
 }
 
-/* Field + swatch trigger of the same size, bottom-aligned with the input box. */
+/* Hex field + swatch button of the same tier, bottom-aligned with the field box. */
 .fieldRow {
   display: flex;
   align-items: flex-end;
   gap: var(--prime-space-2);
-  width: 100%;
-  max-width: calc(var(--prime-panel-min-width) * 1.5);
-}
-
-.fieldRow > :first-child {
-  flex: 1 1 auto;
-  min-width: 0;
-}
-
-.sizes {
-  display: grid;
-  justify-items: center;
-  gap: var(--prime-space-4);
-  width: 100%;
-}
-
-/* The swatch fills the button's icon box, so it scales with the button size. */
-.swatchTrigger .swatchFill {
-  width: 100%;
-  height: 100%;
-}
-
-.formats {
-  display: grid;
-  gap: var(--prime-space-4);
-}
-
-.formatItem {
-  display: grid;
-  gap: var(--prime-space-2);
-}
-
-.card {
-  width: 100%;
-  max-width: var(--prime-modal-width-s);
-}
-
-.preview {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-3);
-}
-
-.previewChip {
-  width: var(--prime-control-m-height);
-  height: var(--prime-control-m-height);
-  flex-shrink: 0;
-  border-radius: var(--prime-radius-m);
-  box-shadow: inset 0 0 0 var(--prime-border-width) var(--prime-color-fill-subtle-active);
-}
-
-/* ColorPresets: label row, size ladder, tag manager list. */
-.stack {
-  display: grid;
-  gap: var(--prime-space-5);
-  width: 100%;
-  max-width: calc(var(--prime-panel-min-width) * 1.75);
-}
-
-/* "Метка: [цвет] Название" — label above, swatch trigger + field of the same tier in one row. */
-.field {
-  display: grid;
-  gap: var(--prime-control-m-label-gap);
-  min-width: 0;
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
 }
 
+/* presets-sizes.tsx: preset trigger + field of the same tier in one row. */
 .row {
   display: flex;
   align-items: center;
   gap: var(--prime-space-2);
-  min-width: 0;
-}
-
-.row > :last-child {
-  flex: 1 1 auto;
-  min-width: 0;
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
 }
 
 .inlineRow {
@@ -96,22 +34,15 @@
   gap: var(--prime-space-3);
 }
 
-/* Tag manager inside a popover: one row per tag. */
-.tagList {
-  display: grid;
-  gap: var(--prime-space-1);
-  width: calc(var(--prime-panel-min-width) * 1.25);
-  max-width: 100%;
-}
-
-.tagRow {
+/* in-form.tsx: field → field 20, group → actions 32. */
+.form {
   display: flex;
-  align-items: center;
-  gap: var(--prime-space-2);
-  min-width: 0;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-s));
 }
 
-.tagName {
-  flex: 1 1 auto;
-  min-width: 0;
+.actions {
+  display: flex;
+  margin-top: var(--prime-space-3);
 }

package/src/components/color-picker/examples/formats.tsx

@@ -1,30 +1,25 @@
-/** Three Roots sharing one controlled color with defaultFormat hsl, rgb and hex for the channel strip. Use it to pick the value format users edit. */
-import { ColorPicker, type ColorValueFormat, parseColor, Typography } from "prime-ui-kit";
+/** The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. */
+import { ColorPicker, type ColorValueFormat, parseColor } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const FORMATS: { format: ColorValueFormat; title: string }[] = [
-  { format: "hsl", title: "HSL — оттенок, насыщенность, яркость, альфа" },
-  { format: "rgb", title: "RGB — красный, зелёный, синий, альфа" },
-  { format: "hex", title: "Hex — одно поле #RRGGBB" },
-];
+const FORMATS: ColorValueFormat[] = ["hsl", "rgb", "hex"];
 
 export default function ColorPickerFormatsExample() {
-  // Three Roots with one controlled value: every strip edits the same color.
   const [color, setColor] = React.useState(() => parseColor("hsl(160, 60%, 42%)"));
 
   return (
-    <div className={`${styles.formats} ${styles.panel}`}>
-      {FORMATS.map(({ format, title }) => (
-        <div key={format} className={styles.formatItem}>
-          <Typography.Root as="p" variant="caption" tone="secondary">
-            {title}
-          </Typography.Root>
-          <ColorPicker.Root value={color} onValueChange={setColor} defaultFormat={format}>
-            <ColorPicker.ChannelStrip />
-          </ColorPicker.Root>
-        </div>
+    <div className={styles.panel}>
+      {FORMATS.map((format) => (
+        <ColorPicker.Root
+          key={format}
+          value={color}
+          onValueChange={setColor}
+          defaultFormat={format}
+        >
+          <ColorPicker.ChannelStrip />
+        </ColorPicker.Root>
       ))}
     </div>
   );

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

@@ -0,0 +1,44 @@
+/** Theme settings: the color goes with the form and a too light color fails on save — `value`, `error`. */
+import { Button, Input } from "prime-ui-kit";
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MAX_LIGHTNESS = 80;
+
+export default function ColorPickerInFormExample() {
+  const [color, setColor] = React.useState(() => parseColor("#f2f2f2"));
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const lightness = color.toFormat("hsl").getChannelValue("lightness");
+    setError(
+      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined,
+    );
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Input.Root label="Название темы" required>
+        <Input.Wrapper>
+          <Input.Field name="theme" defaultValue="Осенняя распродажа" />
+        </Input.Wrapper>
+      </Input.Root>
+      <ColorPicker.Root
+        value={color}
+        onValueChange={(next) => {
+          setColor(next);
+          setError(undefined);
+        }}
+      >
+        <ColorPicker.HexInput label="Цвет кнопок" error={error} />
+      </ColorPicker.Root>
+      <input type="hidden" name="buttonColor" value={color.toString("hex")} />
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить тему</Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,37 @@
+/** A color field: a hex value and a swatch button that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.TriggerSwatch`. */
+import { Button, Popover } from "prime-ui-kit";
+import { ColorPicker } from "prime-ui-kit/color-picker";
+
+import styles from "./examples.module.css";
+
+export default function ColorPickerOverviewExample() {
+  return (
+    <ColorPicker.Root defaultValue="#5b5bd6">
+      <div className={styles.fieldRow}>
+        <ColorPicker.HexInput label="Акцентный цвет" />
+        <Popover.Root>
+          <Popover.Trigger>
+            <Button.Root variant="soft" tone="neutral" aria-label="Открыть палитру">
+              <Button.Icon>
+                <ColorPicker.TriggerSwatch />
+              </Button.Icon>
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="end">
+            <ColorPicker.Panel className={styles.panel}>
+              <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+                <ColorPicker.AreaThumb />
+              </ColorPicker.Area>
+              <ColorPicker.Slider channel="hue" colorSpace="hsl">
+                <ColorPicker.SliderTrack>
+                  <ColorPicker.Thumb />
+                </ColorPicker.SliderTrack>
+              </ColorPicker.Slider>
+              <ColorPicker.ChannelStrip />
+            </ColorPicker.Panel>
+          </Popover.Content>
+        </Popover.Root>
+      </div>
+    </ColorPicker.Root>
+  );
+}

package/src/components/color-picker/examples/panel.tsx

@@ -1,9 +1,17 @@
-/** A standalone raised panel with format select, area, hue and alpha sliders, channel strip and brand swatches. Use it as the full picker layout and part order. */
-import { ColorPicker, Typography } from "prime-ui-kit";
+/** The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. */
+import { ColorPicker } from "prime-ui-kit/color-picker";
 
 import styles from "./examples.module.css";
 
-const PRESETS = ["#e5484d", "#f76b15", "#ffc53d", "#30a46c", "#12a594", "#0090ff", "#8e4ec6"];
+const BRAND_COLORS = [
+  { value: "#e5484d", label: "Красный" },
+  { value: "#f76b15", label: "Оранжевый" },
+  { value: "#ffc53d", label: "Янтарный" },
+  { value: "#30a46c", label: "Зелёный" },
+  { value: "#12a594", label: "Бирюзовый" },
+  { value: "#0090ff", label: "Синий" },
+  { value: "#8e4ec6", label: "Фиолетовый" },
+];
 
 export default function ColorPickerPanelExample() {
   return (
@@ -26,16 +34,7 @@ export default function ColorPickerPanelExample() {
           </ColorPicker.SliderTrack>
         </ColorPicker.Slider>
         <ColorPicker.ChannelStrip />
-        <Typography.Root as="p" variant="caption" tone="secondary">
-          Цвета бренда
-        </Typography.Root>
-        <ColorPicker.SwatchPicker aria-label="Цвета бренда">
-          {PRESETS.map((color) => (
-            <ColorPicker.SwatchPickerItem key={color} color={color}>
-              <ColorPicker.Swatch />
-            </ColorPicker.SwatchPickerItem>
-          ))}
-        </ColorPicker.SwatchPicker>
+        <ColorPicker.Swatches label="Цвета бренда" size="s" presets={BRAND_COLORS} />
       </ColorPicker.Panel>
     </ColorPicker.Root>
   );

package/src/components/color-picker/examples/presets-sizes.tsx

@@ -1,31 +1,26 @@
-/** ColorPresets in every size tier next to an Input of the same size: the trigger is a square of the control height. Use it to line the swatch trigger up with fields. */
-import { ColorPresets, Input, Label } from "prime-ui-kit";
+/** The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. */
+import { ColorPresets, Input } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-export default function ColorPresetsSizesExample() {
+export default function ColorPickerPresetsSizesExample() {
   return (
-    <div className={styles.stack}>
+    <>
       {SIZES.map((size) => (
-        <div key={size} className={styles.field}>
-          <Label.Root size={size} htmlFor={`preset-size-${size}`}>
-            Метка · {size}
-          </Label.Root>
-          <div className={styles.row}>
-            <ColorPresets.Root size={size} defaultValue="#f97316">
-              <ColorPresets.Trigger />
-              <ColorPresets.Content />
-            </ColorPresets.Root>
-            <Input.Root size={size} id={`preset-size-${size}`}>
-              <Input.Wrapper>
-                <Input.Field defaultValue="Маркетинг" />
-              </Input.Wrapper>
-            </Input.Root>
-          </div>
+        <div key={size} className={styles.row}>
+          <ColorPresets.Root size={size} defaultValue="#f97316" labels={{ trigger: "Цвет метки" }}>
+            <ColorPresets.Trigger />
+            <ColorPresets.Content />
+          </ColorPresets.Root>
+          <Input.Root size={size}>
+            <Input.Wrapper>
+              <Input.Field aria-label={`Название метки, ${size}`} defaultValue="Маркетинг" />
+            </Input.Wrapper>
+          </Input.Root>
         </div>
       ))}
-    </div>
+    </>
   );
 }

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

@@ -0,0 +1,33 @@
+/** A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `asChild`. */
+import { Button, COLOR_PRESETS, ColorPresets } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ONE_ROW = COLOR_PRESETS.slice(0, 8);
+
+export default function ColorPickerPresetsExample() {
+  return (
+    <div className={styles.inlineRow}>
+      <ColorPresets.Root
+        presets={ONE_ROW}
+        allowEmpty
+        defaultValue="#5068f5"
+        labels={{ trigger: "Цвет метки" }}
+      >
+        <ColorPresets.Trigger />
+        <ColorPresets.Content />
+      </ColorPresets.Root>
+      <ColorPresets.Root defaultValue="#22c55e">
+        <ColorPresets.Trigger asChild>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <ColorPresets.Swatch />
+            </Button.Icon>
+            Цвет проекта
+          </Button.Root>
+        </ColorPresets.Trigger>
+        <ColorPresets.Content label="Цвет проекта" />
+      </ColorPresets.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,26 @@
+/** Every size of the hex field with a swatch button of the same tier — `size`. */
+import { Button } from "prime-ui-kit";
+import { ColorPicker } from "prime-ui-kit/color-picker";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ColorPickerSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <ColorPicker.Root key={size} defaultValue="#0090ff">
+          <div className={styles.fieldRow}>
+            <ColorPicker.HexInput label={size} size={size} />
+            <Button.Root variant="soft" tone="neutral" size={size} aria-label="Открыть палитру">
+              <Button.Icon>
+                <ColorPicker.TriggerSwatch />
+              </Button.Icon>
+            </Button.Root>
+          </div>
+        </ColorPicker.Root>
+      ))}
+    </>
+  );
+}

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

@@ -1,31 +1,21 @@
-/** Disabled area and slider, a disabled swatch and a hex field that reverts invalid input. Use it as a reference for part-level states. */
-import { ColorPicker } from "prime-ui-kit";
+/** A disabled area and hue slider keep showing the color but take no input — `disabled`. */
+import { ColorPicker } from "prime-ui-kit/color-picker";
 
 import styles from "./examples.module.css";
 
-const PRESETS = ["#e5484d", "#30a46c", "#0090ff", "#8e4ec6"];
-
 export default function ColorPickerStatesExample() {
   return (
     <ColorPicker.Root defaultValue="#30a46c">
-      <ColorPicker.Panel surface="raised" className={styles.panel}>
+      <ColorPicker.Panel className={styles.panel}>
         <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
           <ColorPicker.AreaThumb />
         </ColorPicker.Area>
         <ColorPicker.Slider channel="hue" colorSpace="hsl" disabled>
-          <ColorPicker.SliderMeta label="Оттенок (disabled)" />
+          <ColorPicker.SliderMeta label="disabled" />
           <ColorPicker.SliderTrack>
             <ColorPicker.Thumb />
           </ColorPicker.SliderTrack>
         </ColorPicker.Slider>
-        <ColorPicker.SwatchPicker aria-label="Пресеты, красный недоступен">
-          {PRESETS.map((color, index) => (
-            <ColorPicker.SwatchPickerItem key={color} color={color} disabled={index === 0}>
-              <ColorPicker.Swatch />
-            </ColorPicker.SwatchPickerItem>
-          ))}
-        </ColorPicker.SwatchPicker>
-        <ColorPicker.HexInput label="Hex" />
       </ColorPicker.Panel>
     </ColorPicker.Root>
   );

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

@@ -0,0 +1,18 @@
+/** A hint under the hex field and an error that replaces it; invalid text reverts on blur — `hint`, `error`. */
+import { ColorPicker } from "prime-ui-kit/color-picker";
+
+export default function ColorPickerValidationExample() {
+  return (
+    <>
+      <ColorPicker.Root defaultValue="#0090ff">
+        <ColorPicker.HexInput label="Цвет ссылок" hint="Формат #RRGGBB или #RRGGBBAA" />
+      </ColorPicker.Root>
+      <ColorPicker.Root defaultValue="#f5f5f5">
+        <ColorPicker.HexInput
+          label="Цвет кнопок"
+          error="Слишком светлый: белый текст на нём не читается"
+        />
+      </ColorPicker.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,145 @@
+# ColorSwatches
+
+**Category:** selection
+**Kind:** control
+
+> An inline color choice: preset swatches that wrap inside a form, without a popover.
+
+## When to use
+- Picking a color for an entity in a form or dialog (pipeline stage, tag, project, calendar).
+- The palette is short (up to ~20 presets) and the choice should be visible at once.
+- Settings pages where every option is shown inline.
+
+## When not to use
+- A compact color next to a field or in a dense list row (one trigger per row) → use [ColorPresets](../color-picker/COMPONENT.md) (trigger + popover palette).
+- A free color (any hex, eyedropper, channels) → use [ColorPicker](../color-picker/COMPONENT.md).
+- Choosing a mode or a value that is not a color → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Radio](../radio/COMPONENT.md).
+
+## Import
+```tsx
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+ColorSwatches                 field frame: label → swatches → hint | error
+└─ radiogroup                 wrapping row of swatches
+   ├─ radio × presets         swatch button (color fill, faint inner ring, check when selected)
+   ├─ radio «Без цвета»       checkerboard swatch (`allowEmpty`)
+   └─ input[type=hidden]      submits the value (`name`)
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ColorSwatches
+`ref` → `HTMLDivElement` (the field frame). The field frame (label → swatches → hint | error) around a `role="radiogroup"` of swatch buttons with a roving tab stop.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| null` | — | Controlled color; `null` — no color. |
+| `defaultValue` | `string \| null` | `null` | Initial color when uncontrolled. |
+| `onValueChange` | `(value: string \| null) => void` | — | Called with the preset `value` (as written in `presets`) or `null`. |
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches in order: `{ value, label }`; the label is the swatch's accessible name and tooltip. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier: swatch = control height − 8 (20 · 24 · 28 · 32 · 40), gap = the tier gap; label and hint follow it. Without it the tier of its host, else `m`. |
+| `label` | `ReactNode` | — | Label above the swatches; names the radiogroup (`aria-labelledby`). |
+| `required` | `boolean` | — | Red `*` after the label and `aria-required` on the group. |
+| `optional` | `boolean` | — | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the swatches. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `invalid` | `boolean` | — | Danger selection ring and `aria-invalid`. A non-empty `error` implies it. |
+| `disabled` | `boolean` | `false` | Disables every swatch (grey, half transparent). |
+| `allowEmpty` | `boolean` | `false` | Adds the «no color» checkerboard swatch after the presets (value `null`). |
+| `name` | `string` | — | Form field name: a hidden input submits the selected color (empty string for no color). |
+| `id` | `string` | — | Id of the radiogroup; hint id is `<id>-hint`, error id is `<id>-error`. |
+| `aria-label` | `string` | — | Accessible name when there is no visible `label` (else `labels.group`). |
+| `aria-labelledby` | `string` | — | Names the group by an outside element. |
+| `aria-describedby` | `string` | — | Merged before the hint/error ids. |
+| `labels` | `Partial<ColorSwatchesLabels>` | — | 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` | Swatch 20, gap 4, radius 4 | Dense side panels | |
+| `s` | Swatch 24, gap 8, radius 6 | Compact dialogs and popovers | |
+| `m` | Swatch 28, gap 8, radius 6 | Forms and modals | yes |
+| `l` | Swatch 32, gap 8, radius 8 | Spacious settings pages | |
+| `xl` | Swatch 40, gap 12, radius 8 | Touch-first layouts | |
+
+**Sizes:** match the size of the form around it: an `m` form uses `m` swatches (28), which sit on the same 4px rhythm as `m` fields.
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `allowEmpty` | an extra checkerboard swatch «Без цвета» at the end | the color is optional | `false` |
+| `invalid` | the selection ring turns danger | the message is shown elsewhere; otherwise pass `error` | — |
+| `disabled` | every swatch grey at half opacity | the choice is unavailable | `false` |
+
+**Combinations**
+- Recommended: `label` + `name` inside a form; `allowEmpty` + `optional` for optional colors; `COLOR_PRESETS.slice(0, 8)` for one row of eight.
+- Avoid: more than ~24 presets (switch to ColorPicker); `required` together with `allowEmpty` (an empty choice cannot satisfy it).
+- The swatches are a field: they follow the field → field spacing (20) and never get their own card or border.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| selected | `value` / `defaultValue` | `aria-checked="true"`, `data-state="checked"` on the radio; 2px accent ring with a 2px gap and a check mark (light or dark by color contrast) |
+| hover | pointer | the swatch scales to 1.08 (fine pointers only) |
+| focus-visible | keyboard | focus ring outside the swatch |
+| invalid | `invalid` / `error` | `aria-invalid`, `data-invalid` on the group; the selected ring turns `danger-border` |
+| disabled | `disabled` | native `disabled` on every radio, `aria-disabled` and `data-disabled` on the group |
+
+Controlled with `value` + `onValueChange`; uncontrolled with `defaultValue`.
+
+## Layout & spacing
+- The swatches take the container width and wrap to new rows by themselves; no column count to set. In a content-sized container they stay in one row.
+- The selection / focus rings sit outside the swatches; kit hosts (Modal / Drawer body, panels, cards) already keep `--prime-focus-space` padding, so the rings are never clipped. In your own `overflow` container, keep that padding.
+- Label → swatches and swatches → hint use the tier `label-gap` / `hint-gap`; field → field 20.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Enters on the selected swatch (or the first one). |
+| `ArrowRight` · `ArrowLeft` | Moves to the next / previous swatch and selects it. |
+| `ArrowDown` · `ArrowUp` | Moves one visual row down / up and selects. |
+| `Home` · `End` | Jumps to the first / last swatch and selects it. |
+
+### ARIA
+- `role="radiogroup"` with one `role="radio"` button per swatch; the color name is the radio's name and `title`.
+- Named by `label`, `aria-labelledby`, `aria-label` or `labels.group`; the hint or the error is linked through `aria-describedby`.
+- The check mark is decorative; the selection is announced by `aria-checked`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `group` | `"Цвет"` | Accessible name of the group without a visible `label` and `aria-label`. |
+| `empty` | `"Без цвета"` | Name of the «no color» swatch (`allowEmpty`). |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The kit palette inline under a field label, one color chosen — `label`, `defaultValue`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size, swatch 20 to 40 px with the tier gap — `size`. |
+| [states.tsx](examples/states.tsx) | A default palette next to an invalid and a disabled one — `invalid`, `disabled`. |
+| [wrapping.tsx](examples/wrapping.tsx) | In a narrow column the swatches wrap by themselves and the arrows move by the visual rows. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. |
+| [in-form.tsx](examples/in-form.tsx) | A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. |
+
+## Mistakes
+- `<ColorSwatches.Root>` → the component is a single export: `<ColorSwatches />`.
+- A visible heading next to the swatches made by hand → pass `label`.
+- Presets without names → every preset needs a `label`; it is the swatch's accessible name.
+- Dozens of presets → use ColorPicker.
+
+## Related
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), `Icon` (check mark)
+- **See also:** [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`, `ColorPicker.Swatches`), [Radio](../radio/COMPONENT.md)

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

@@ -0,0 +1,22 @@
+/** The parent owns the color, «no color» included, and names it in the hint — `value`, `onValueChange`, `allowEmpty`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+import * as React from "react";
+
+const PRESETS = COLOR_PRESETS.slice(0, 8);
+
+export default function ColorSwatchesControlledExample() {
+  const [color, setColor] = React.useState<string | null>(null);
+  const name = PRESETS.find((preset) => preset.value === color)?.label ?? "без цвета";
+
+  return (
+    <ColorSwatches
+      label="Цвет метки"
+      optional
+      presets={PRESETS}
+      allowEmpty
+      value={color}
+      onValueChange={setColor}
+      hint={`Выбрано: ${name}`}
+    />
+  );
+}

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

@@ -0,0 +1,19 @@
+/* Layout of the ColorSwatches scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, group → actions 32. */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-5);
+  width: min(100%, var(--prime-modal-width-s));
+}
+
+.actions {
+  display: flex;
+  margin-top: var(--prime-space-3);
+}
+
+/* wrapping.tsx: a narrow column. */
+.narrow {
+  width: min(100%, calc(var(--prime-space-16) * 3));
+}