prime-ui-kit 0.7.13 → 0.9.1

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

@@ -0,0 +1,41 @@
+/** 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 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 (
+    <ColorPicker.Root defaultValue="hsl(220, 90%, 56%)">
+      <ColorPicker.Panel surface="raised" className={styles.panel}>
+        <ColorPicker.FormatSelect />
+        <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
+          <ColorPicker.AreaThumb />
+        </ColorPicker.Area>
+        <ColorPicker.Slider channel="hue" colorSpace="hsl">
+          <ColorPicker.SliderMeta label="Оттенок" />
+          <ColorPicker.SliderTrack>
+            <ColorPicker.Thumb />
+          </ColorPicker.SliderTrack>
+        </ColorPicker.Slider>
+        <ColorPicker.Slider channel="alpha">
+          <ColorPicker.SliderMeta label="Непрозрачность" />
+          <ColorPicker.SliderTrack>
+            <ColorPicker.Thumb />
+          </ColorPicker.SliderTrack>
+        </ColorPicker.Slider>
+        <ColorPicker.ChannelStrip />
+        <ColorPicker.Swatches label="Цвета бренда" size="s" presets={BRAND_COLORS} />
+      </ColorPicker.Panel>
+    </ColorPicker.Root>
+  );
+}

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

@@ -0,0 +1,26 @@
+/** 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 ColorPickerPresetsSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <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>
+      ))}
+    </>
+  );
+}

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,79 +1,22 @@
-import { Pipette } from "lucide-react";
-import { Button, ColorPicker, Popover } from "prime-ui-kit";
-import * as React from "react";
+/** A disabled area and hue slider keep showing the color but take no input — `disabled`. */
+import { ColorPicker } from "prime-ui-kit/color-picker";
 
-const PRESETS = ["#ef4444", "#22c55e", "#3b82f6"];
-
-/** Disabled `SwatchPickerItem` and disabled hue `Slider` (playground `states`). */
-export function StatesExample() {
-  const [openSwatch, setOpenSwatch] = React.useState(false);
-  const [openSlider, setOpenSlider] = React.useState(false);
+import styles from "./examples.module.css";
 
+export default function ColorPickerStatesExample() {
   return (
-    <div style={{ display: "flex", flexWrap: "wrap", gap: "2rem", alignItems: "flex-start" }}>
-      <div>
-        <p style={{ margin: "0 0 0.5rem", fontSize: "0.875rem", opacity: 0.8 }}>
-          Preset with isDisabled
-        </p>
-        <ColorPicker.Root defaultValue="#22c55e">
-          <Popover.Root onOpenChange={setOpenSwatch} open={openSwatch}>
-            <Popover.Trigger asChild>
-              <Button.Root mode="stroke" variant="neutral">
-                <ColorPicker.TriggerSwatch />
-                Palette
-              </Button.Root>
-            </Popover.Trigger>
-            <Popover.Content align="start" side="bottom">
-              <ColorPicker.FormatProvider>
-                <ColorPicker.SwatchPicker aria-label="Palette with one disabled swatch">
-                  {PRESETS.map((c, i) => (
-                    <ColorPicker.SwatchPickerItem key={c} color={c} isDisabled={i === 0}>
-                      <ColorPicker.Swatch />
-                    </ColorPicker.SwatchPickerItem>
-                  ))}
-                </ColorPicker.SwatchPicker>
-              </ColorPicker.FormatProvider>
-            </Popover.Content>
-          </Popover.Root>
-        </ColorPicker.Root>
-      </div>
-      <div>
-        <p style={{ margin: "0 0 0.5rem", fontSize: "0.875rem", opacity: 0.8 }}>
-          Hue slider with isDisabled
-        </p>
-        <ColorPicker.Root defaultValue="hsl(200, 75%, 52%)">
-          <Popover.Root onOpenChange={setOpenSlider} open={openSlider}>
-            <Popover.Trigger asChild>
-              <Button.Root mode="stroke" variant="neutral">
-                <ColorPicker.TriggerSwatch />
-                Disabled slider
-              </Button.Root>
-            </Popover.Trigger>
-            <Popover.Content align="start" side="bottom">
-              <ColorPicker.FormatProvider>
-                <div
-                  style={{
-                    display: "flex",
-                    width: "12.5rem",
-                    maxWidth: "100%",
-                    flexDirection: "column",
-                    gap: "0.5rem",
-                  }}
-                >
-                  <ColorPicker.Slider channel="hue" colorSpace="hsl" isDisabled>
-                    <ColorPicker.SliderTrack>
-                      <ColorPicker.Thumb />
-                    </ColorPicker.SliderTrack>
-                  </ColorPicker.Slider>
-                  <ColorPicker.ChannelStrip
-                    pipetteIcon={<Pipette aria-hidden size={18} strokeWidth={1.75} />}
-                  />
-                </div>
-              </ColorPicker.FormatProvider>
-            </Popover.Content>
-          </Popover.Root>
-        </ColorPicker.Root>
-      </div>
-    </div>
+    <ColorPicker.Root defaultValue="#30a46c">
+      <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.SliderTrack>
+            <ColorPicker.Thumb />
+          </ColorPicker.SliderTrack>
+        </ColorPicker.Slider>
+      </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));
+}

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

@@ -0,0 +1,35 @@
+/** A calendar event form: the color is submitted by `name` and required on save — `name`, `required`, `error`. */
+import { Button, ColorSwatches, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function ColorSwatchesInFormExample() {
+  const [error, setError] = React.useState<string>();
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const color = new FormData(event.currentTarget).get("color");
+    setError(color ? undefined : "Выберите цвет события");
+  };
+
+  return (
+    <form className={styles.form} noValidate onSubmit={submit}>
+      <Input.Root label="Название события" required>
+        <Input.Wrapper>
+          <Input.Field name="title" defaultValue="Встреча с поставщиком" />
+        </Input.Wrapper>
+      </Input.Root>
+      <ColorSwatches
+        label="Цвет в календаре"
+        name="color"
+        required
+        error={error}
+        onValueChange={() => setError(undefined)}
+      />
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить</Button.Root>
+      </div>
+    </form>
+  );
+}

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

@@ -0,0 +1,6 @@
+/** The kit palette inline under a field label, one color chosen — `label`, `defaultValue`. */
+import { ColorSwatches } from "prime-ui-kit";
+
+export default function ColorSwatchesOverviewExample() {
+  return <ColorSwatches label="Цвет проекта" defaultValue="#5068f5" />;
+}

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

@@ -0,0 +1,19 @@
+/** Every size, swatch 20 to 40 px with the tier gap — `size`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+const PRESETS = COLOR_PRESETS.slice(0, 6);
+
+export default function ColorSwatchesSizesExample() {
+  return (
+    <>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <div>
+            <ColorSwatches size={size} label={size} presets={PRESETS} defaultValue="#5068f5" />
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}

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

@@ -0,0 +1,20 @@
+/** A default palette next to an invalid and a disabled one — `invalid`, `disabled`. */
+import { COLOR_PRESETS, ColorSwatches } from "prime-ui-kit";
+
+const PRESETS = COLOR_PRESETS.slice(0, 6);
+
+export default function ColorSwatchesStatesExample() {
+  return (
+    <div>
+      <div>
+        <ColorSwatches label="default" presets={PRESETS} defaultValue="#22c55e" />
+      </div>
+      <div>
+        <ColorSwatches label="invalid" presets={PRESETS} defaultValue="#22c55e" invalid />
+      </div>
+      <div>
+        <ColorSwatches label="disabled" presets={PRESETS} defaultValue="#22c55e" disabled />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,12 @@
+/** In a narrow column the swatches wrap by themselves and the arrows move by the visual rows. */
+import { ColorSwatches } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ColorSwatchesWrappingExample() {
+  return (
+    <div className={styles.narrow}>
+      <ColorSwatches label="Цвет этапа" defaultValue="#14b8a6" />
+    </div>
+  );
+}