prime-ui-kit 0.9.3 → 0.11.0

package/dist/skill/reference/components/color-picker/COMPONENT.md

@@ -0,0 +1,339 @@
+# ColorPicker
+
+**Category:** selection
+**Kind:** field
+
+> Color selection: a full picker (hex field, area, channel sliders and fields, eyedropper, swatches) and `ColorPresets` for a quick color from a fixed palette.
+
+## When to use
+- `ColorPicker` — any color is allowed and the picker parts are laid out by hand: an inline panel, a design tool, a hex field with a custom trigger.
+- `ColorPresets` — a color from a fixed palette with an optional «no color»: label, project or calendar colors, one trigger per row.
+- `parseColor` — turning a CSS string into a `Color` for a controlled `ColorPicker`.
+
+## When not to use
+- Any color as one field of a form (swatch + hex, the panel in a popover) → use [ColorField](../color-field/COMPONENT.md).
+- The color is a field of its own in a form or dialog (stage, label, project color) → use [ColorSwatches](../color-swatches/COMPONENT.md): the palette inline, no popover.
+- Picking one of the kit palette hues for a Badge in TagSelect — the row menu of [TagSelect](../tag-select/COMPONENT.md) already does it.
+- Choosing between a few named themes or modes → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Select](../select/COMPONENT.md) instead.
+- A plain text field for a hex code without a picker → use [Input](../input/COMPONENT.md) instead.
+
+## Import
+```tsx
+import { COLOR_PRESETS, ColorPresets } from "prime-ui-kit";
+import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+```
+
+`ColorPicker` has its own entry: it is the only part of the kit built on `react-aria-components`,
+an optional peer dependency — install it only when you use `ColorPicker`. Its styles are already
+in `prime-ui-kit/bundle.css`. `ColorPresets` stays in the main entry and needs no extra package.
+
+## Anatomy
+```
+ColorPicker.Root                 shared Color + value format (no DOM)
+├─ ColorPicker.HexInput          kit Input bound to the hex of the current color
+├─ ColorPicker.TriggerSwatch     square of the current color for a trigger button
+└─ ColorPicker.Panel             vertical stack, optional raised surface
+   ├─ ColorPicker.FormatSelect   kit Select: HSL / RGB / Hex
+   ├─ ColorPicker.Area           2D area (4:3)
+   │  └─ ColorPicker.AreaThumb
+   ├─ ColorPicker.Slider         one channel
+   │  ├─ ColorPicker.SliderMeta  label + value row
+   │  └─ ColorPicker.SliderTrack
+   │     └─ ColorPicker.Thumb
+   ├─ ColorPicker.ChannelStrip   eyedropper + channel fields of the current format
+   ├─ ColorPicker.EyeDropperButton
+   └─ ColorPicker.Swatches       kit ColorSwatches bound to the color
+
+ColorPresets.Root                value, open, presets (no DOM)
+├─ ColorPresets.Trigger          slot around one element
+│  └─ ColorPresets.SwatchButton  square swatch button (or your Button with ColorPresets.Swatch)
+└─ ColorPresets.Content          popover with the swatch grid (listbox)
+```
+Helpers: `parseColor(value)` (throws on invalid input; back to text with `color.toString("hex" | "hexa" | "css")`), `COLOR_PRESETS` (16 colors: step 500 and step 700 of eight hues), types `ColorPickerColorValue`, `ColorValueFormat`, `ColorPreset`.
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ColorPicker.Root
+No DOM. Holds the color (React Aria `ColorPicker`) and the value format for every part inside.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| Color` | — | Controlled color: a CSS color string or a `Color` from `parseColor`. |
+| `defaultValue` | `string \| Color` | — | Initial color when uncontrolled. |
+| `onValueChange` | `(color: Color) => void` | — | Called with the new `Color` (`color.toString("hex")` for a string). |
+| `defaultFormat` | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | Initial value format of `FormatSelect` and `ChannelStrip`. |
+| `labels` | `Partial<ColorPickerLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — (required) | The parts. |
+
+### ColorPicker.Panel
+`ref` → `HTMLDivElement`. Vertical stack of the parts with the standard gap; native `<div>` props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `surface` | `"none" \| "raised"` | `"none"` | `none` — layout only (inside a Popover or Card). `raised` — a standalone floating panel: raised background, panel radius and padding, overlay shadow. |
+
+### ColorPicker.HexInput
+`ref` → `HTMLDivElement` (the field frame). The hex value as a kit Input field (label, hint, error); commits on blur / Enter and reverts invalid text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Field label; defaults to `labels.hex`. |
+| `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; marks the field invalid. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Field tier. Without it the tier of its host (a panel, a popover), else `m`. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the fields (`data-focus-ring="false"`); focus, keyboard and ARIA stay. |
+| `…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). |
+
+### ColorPicker.TriggerSwatch
+`ref` → `HTMLSpanElement`. A square of the current color for a trigger button (`aria-hidden`); follows the host icon size, e.g. inside `Button.Icon`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### ColorPicker.FormatSelect
+`ref` → `HTMLDivElement` (the wrapper). A kit Select of the value format (HSL · RGB · Hex), named by `labels.format`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the wrapper `<div>`. |
+
+### ColorPicker.ChannelStrip
+`ref` → `HTMLDivElement`. One row: the eyedropper, then a field per channel of the current format (or one hex field); each field commits on blur / Enter.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring of the fields (`data-focus-ring="false"`); focus, keyboard and ARIA stay. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the row `<div>`. |
+
+### ColorPicker.Area
+`ref` → `HTMLDivElement`. React Aria `ColorArea`: a two-channel square (e.g. saturation × lightness). Holds `ColorPicker.AreaThumb`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | — | Shows the color but takes no input (grayscale). |
+| `…rest` | `ColorAreaProps (react-aria-components)` | — | The other props of the React Aria `ColorArea` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.AreaThumb · ColorPicker.Thumb
+`ref` → `HTMLDivElement`. React Aria `ColorThumb` of the area / of a slider track: a thumb-colored ring with the overlay shadow and a focus ring.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `ColorThumbProps (react-aria-components)` | — | The other props of the React Aria `ColorThumb` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.Slider
+`ref` → `HTMLDivElement`. React Aria `ColorSlider` of one channel (hue, alpha…). Holds `SliderMeta` and `SliderTrack`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `disabled` | `boolean` | — | Shows the color but takes no input (grayscale). |
+| `…rest` | `ColorSliderProps (react-aria-components)` | — | The other props of the React Aria `ColorSlider` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.SliderMeta
+`ref` → `HTMLDivElement`. The slider heading: a label and the current channel value.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — (required) | Visible label of the slider. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the heading `<div>`. |
+
+### ColorPicker.SliderTrack
+`ref` → `HTMLDivElement`. React Aria `SliderTrack` with the channel gradient over a transparency checkerboard. Holds `ColorPicker.Thumb`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `SliderTrackProps (react-aria-components)` | — | The other props of the React Aria `SliderTrack` (`channel`, `colorSpace`, `aria-label`…). |
+
+### ColorPicker.Swatches
+`ref` → `HTMLDivElement` (the ColorSwatches field frame). The kit `ColorSwatches` bound to the picker color: a pick sets the color, editing the color moves the selection. Takes every ColorSwatches prop except the value ones, `allowEmpty` and `name`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches `{ value, label }`; the label names the swatch. |
+| `…rest` | `Omit<ColorSwatchesProps, "value" \| "defaultValue" \| "onValueChange" \| "allowEmpty" \| "name">` | — | `label`, `size`, `aria-label`, `disabled`… |
+
+### ColorPicker.EyeDropperButton
+`ref` → `HTMLButtonElement`. A square soft kit Button that opens the native EyeDropper, named by `labels.eyeDropper`; without browser support it is disabled and hidden from assistive tech.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Custom content; default is the pipette icon. |
+| `…rest` | `Omit<ButtonRootProps, "variant" \| "tone" \| "size" \| "aria-label">` | — | The other Button props. |
+
+### ColorPresets.Root
+No DOM. A quick color from a fixed palette: a square trigger and a popover grid of presets (Popover overlay contract).
+
+| 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` or `null`. |
+| `open` | `boolean` | — | Controlled open state of the panel. |
+| `defaultOpen` | `boolean` | `false` | Initial open state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when the panel opens or closes. |
+| `presets` | `readonly ColorPreset[]` | `COLOR_PRESETS` | Swatches in panel order. |
+| `columns` | `number` | — | Grid columns; default one row for up to 8 presets (+ «no color»), else 8. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the trigger, the swatches and the panel. Without it the tier of its host, else `m`. |
+| `disabled` | `boolean` | `false` | The trigger is disabled and does not open the panel. A disabled `Fieldset` around it sets it too. |
+| `allowEmpty` | `boolean` | `false` | Adds the «no color» swatch after the presets (value `null`). |
+| `closeOnSelect` | `boolean` | `true` | Close the panel after a pick (focus returns to the trigger). |
+| `labels` | `Partial<ColorPresetsLabels>` | — | Built-in strings, see Labels. |
+
+### ColorPresets.Trigger
+No DOM: clones the single child into the panel's trigger, merges `ref` and `onClick` (toggles), names it «`labels.trigger`: <color name>», sets `disabled` from the root and opens the panel on ArrowDown / ArrowUp. The child's own `aria-label`, `disabled` and handlers win.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactElement` | — (required) | One element: `ColorPresets.SwatchButton`, or e.g. `Button.Root` with `ColorPresets.Swatch`. |
+
+### ColorPresets.SwatchButton
+`ref` → `HTMLButtonElement`. The kit square swatch button of the root tier: a square of the control height filled with the current color. Put it in `ColorPresets.Trigger`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" \| "value">` | — | `aria-label`, `className` and the other button attributes. |
+
+### ColorPresets.Swatch
+`ref` → `HTMLSpanElement`. The current color as a small square for a custom trigger; follows the host icon size, `aria-hidden`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### ColorPresets.Content
+`ref` → `HTMLDivElement` (the panel). The floating panel with the swatch grid (`role="listbox"`); focus moves to the selected swatch.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `ReactNode` | — | Heading above the grid; also the list's accessible name (else `labels.list`). |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Side of the trigger. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children" \| "role">` | — | `className` and the other attributes of the panel. |
+
+## Variants
+No `variant` / `tone` / `color`.
+
+### surface (ColorPicker.Panel)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `none` | parts stacked with a 12px gap, no own background | inside a Popover or a Card | yes |
+| `raised` | the floating layer of the ladder (`data-depth="floating"`), panel radius and padding, `shadow-overlay`; fields take that layer's fill | a standalone panel on the page | |
+
+### defaultFormat (ColorPicker.Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `hsl` | hue °, saturation %, lightness %, alpha % fields | designers tuning a hue | yes |
+| `rgb` | red, green, blue (0–255), alpha % | developer-facing tools | |
+| `hex` | one hex field | brand colors copied from guidelines | |
+
+### size (HexInput, ColorPresets)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28px field / trigger, 16px preset swatches | dense tables | |
+| `s` | 32px, 20px swatches | rows inside popovers and lists | |
+| `m` | 36px, 24px swatches | regular forms | yes |
+| `l` | 40px, 28px swatches | spacious forms | |
+| `xl` | 48px, 32px swatches | touch-first screens | |
+
+**Sizes:** `ColorPresets.SwatchButton` is a square of the control height, so it lines up with an Input of the same size; HexInput + a square soft `Button.Root` of the same `size` with `TriggerSwatch` inside `Button.Icon` match too. Area, sliders and the channel strip have no size axis (always tier `m`).
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `allowEmpty` (ColorPresets) | checkerboard «Без цвета» swatch at the end | the color is optional | `false` |
+| `closeOnSelect={false}` (ColorPresets) | panel stays open after a pick | trying several colors in a row | `true` |
+| `disabled` (Area, Slider) | grayscale, no input | the part is locked | — |
+
+**Combinations**
+- `surface="raised"` inside a Popover → double surface; keep `none` there.
+- Several Roots with one controlled `value` → all parts edit the same color.
+- Prefer `ColorPresets` when a palette is enough; open the full `ColorPicker` only where any color is valid.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| disabled part | `disabled` on Area / Slider | React Aria `data-disabled`; muted, not interactive |
+| focus-visible | keyboard | React Aria `data-focus-visible`; `data-focus-ring="false"` on fields with `focusRing={false}` |
+| invalid hex | typing | reverts to the current color on blur / Enter |
+| hex error | `error` on HexInput | `aria-invalid`, danger ring, the error replaces the hint |
+| eyedropper unsupported | no `window.EyeDropper` | button `disabled`, `aria-hidden` |
+| selected swatch | the color | `data-state="checked"`; a check mark that contrasts with the color draws in — no ring, the check is the selection |
+| ColorPresets open | `open` / click / ArrowDown · ArrowUp on the trigger | popover `data-state`; focus on the selected swatch |
+| ColorPresets empty | value `null` | the trigger shows the checkerboard fill and is named «`labels.trigger`: `labels.empty`» |
+
+There is no `disabled` on `ColorPicker.Root` — disable parts individually. Controlled: `value` + `onValueChange` (both components), `open` + `onOpenChange` (ColorPresets). Uncontrolled: `defaultValue`, `defaultOpen`.
+
+## Layout & spacing
+- Panel width comes from the layout (e.g. `calc(var(--prime-panel-min-width) * 1.5)` fits the area and four channel fields).
+- Field + trigger row: gap `--prime-space-2`, `align-items: flex-end` so the trigger aligns with the field box under a label.
+- Panel parts gap: 12px (`--prime-space-3`) from `ColorPicker.Panel`.
+- ColorPresets.Content `align="auto"`: a trigger near the end of the screen lines up the panel's end edge and the panel grows toward the start, and the other way near the start; a fixed `align` still flips at the screen edge.
+- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); below 480px viewport width the `l` / `xl` grids wrap to half the columns.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `ArrowLeft` · `ArrowRight` · `ArrowUp` · `ArrowDown` | Move the area thumb or a slider; in the ColorPresets grid, move between swatches. |
+| `PageUp` · `PageDown` | Larger steps on the area and the sliders. |
+| `Home` · `End` | Slider ends; the first / last swatch in the ColorPresets grid. |
+| `Enter` · `Space` | Commit a field; pick the focused preset swatch and close. |
+| `Tab` | Moves through the parts; inside the ColorPresets grid returns to the trigger and closes. |
+| `Escape` | Closes the ColorPresets panel. |
+
+### ARIA
+- Area and sliders are React Aria primitives with their own `role="slider"` names.
+- `TriggerSwatch` and `ColorPresets.Swatch` are `aria-hidden` — give the trigger button an `aria-label` (ColorPresets.Trigger names its element «`labels.trigger`: <color name>» unless the element has its own `aria-label`).
+- `ColorPicker.Swatches` is a `role="radiogroup"` (ColorSwatches): name it with `label` or `aria-label`.
+- The ColorPresets grid is `role="listbox"` with `role="option"` swatches (roving tabindex), named by the Content `label` or `labels.list`.
+- Channel fields are named by `labels` (`hue`, `red`…); HexInput by its label (`labels.hex` by default).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `format` | `"Формат значений цвета"` | Name of `ColorPicker.FormatSelect`. |
+| `eyeDropper` | `"Пипетка"` | Name of `ColorPicker.EyeDropperButton`. |
+| `hex` | `"Hex"` | Hex field of `ChannelStrip` and the default `HexInput` label. |
+| `hue` | `"Оттенок, градусы"` | Hue channel field. |
+| `saturation` | `"Насыщенность, проценты"` | Saturation channel field. |
+| `lightness` | `"Яркость, проценты"` | Lightness channel field. |
+| `alpha` | `"Непрозрачность, проценты"` | Alpha channel field. |
+| `red` | `"Красный, 0–255"` | Red channel field. |
+| `green` | `"Зелёный, 0–255"` | Green channel field. |
+| `blue` | `"Синий, 0–255"` | Blue channel field. |
+| `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>». |
+| `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
+| `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A color field: a hex value and a swatch button that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.TriggerSwatch`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size of the hex field with a swatch button of the same tier — `size`. |
+| [states.tsx](examples/states.tsx) | A disabled area and hue slider keep showing the color but take no input — `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 under the other field, invalid text reverts on blur — `hint`, `error`. |
+| [panel.tsx](examples/panel.tsx) | The full raised panel and its part order: format, area, hue and alpha sliders, channels, brand swatches — `ColorPicker.Panel`, `surface`, `ColorPicker.Swatches`. |
+| [formats.tsx](examples/formats.tsx) | The channel strip in each value format; three pickers edit one color — `defaultFormat`, `ColorPicker.ChannelStrip`. |
+| [presets.tsx](examples/presets.tsx) | A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`. |
+| [presets-sizes.tsx](examples/presets-sizes.tsx) | The preset trigger in every size, a square of the control height next to an input of the same tier — `ColorPresets`, `size`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. |
+| [in-form.tsx](examples/in-form.tsx) | Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. |
+
+## Mistakes
+- Trigger in one `ColorPicker.Root` and panel in another → they will not share the color; wrap both in one Root.
+- `isDisabled` on Area / Slider → use `disabled`.
+- `onChange` on `ColorPicker.Root` → use `onValueChange`.
+- `parseColor` on raw user input without try/catch → it throws on invalid strings.
+- `surface="raised"` inside a Popover → use the default `none`.
+- Expecting `ColorPresets` to return a `Color` → it returns the preset string (or `null`).
+- `<ColorPresets.Trigger onKeyDown={…}>` or `className` on the Trigger → it is a slot with no props of its own; put them on the child element.
+- `<ColorPresets.Trigger />` with no child → put `ColorPresets.SwatchButton` (or your Button) inside it.
+
+## Related
+- **Built from:** [Input](../input/COMPONENT.md) (`HexInput`), [Select](../select/COMPONENT.md) (`FormatSelect`), [Button](../button/COMPONENT.md) (`EyeDropperButton`), [ColorSwatches](../color-swatches/COMPONENT.md) (`Swatches`), [Popover](../popover/COMPONENT.md) (`ColorPresets.Root`, `ColorPresets.Content`), `Icon` (pipette)
+- **See also:** [ColorField](../color-field/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md)

package/dist/skill/reference/components/color-picker/examples/controlled.tsx

@@ -0,0 +1,37 @@
+/** The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. */
+import { Button } 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 DEFAULT_COLOR = "#5b5bd6";
+const BRAND_COLORS = [
+  { value: "#5b5bd6", label: "Индиго" },
+  { value: "#0090ff", label: "Синий" },
+  { value: "#12a594", label: "Бирюзовый" },
+  { value: "#f76b15", label: "Оранжевый" },
+  { value: "#e5484d", label: "Красный" },
+];
+
+export default function ColorPickerControlledExample() {
+  const [color, setColor] = React.useState(() => parseColor(DEFAULT_COLOR));
+
+  return (
+    <div className={styles.panel}>
+      <ColorPicker.Root value={color} onValueChange={setColor}>
+        <ColorPicker.HexInput label="Цвет витрины" hint={`Сейчас: ${color.toString("hex")}`} />
+        <ColorPicker.Swatches aria-label="Цвета бренда" presets={BRAND_COLORS} />
+      </ColorPicker.Root>
+      <div>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          onClick={() => setColor(parseColor(DEFAULT_COLOR))}
+        >
+          Сбросить
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/dist/skill/reference/components/color-picker/examples/examples.module.css

@@ -0,0 +1,48 @@
+/* Layout of the ColorPicker and ColorPresets scenarios: semantic tokens only. */
+
+/* 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%;
+}
+
+/* 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: 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);
+  width: calc(var(--prime-panel-min-width) * 1.5);
+  max-width: 100%;
+}
+
+.inlineRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--prime-space-3);
+}
+
+/* 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);
+}

package/dist/skill/reference/components/color-picker/examples/formats.tsx

@@ -0,0 +1,26 @@
+/** 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: ColorValueFormat[] = ["hsl", "rgb", "hex"];
+
+export default function ColorPickerFormatsExample() {
+  const [color, setColor] = React.useState(() => parseColor("hsl(160, 60%, 42%)"));
+
+  return (
+    <div className={styles.panel}>
+      {FORMATS.map((format) => (
+        <ColorPicker.Root
+          key={format}
+          value={color}
+          onValueChange={setColor}
+          defaultFormat={format}
+        >
+          <ColorPicker.ChannelStrip />
+        </ColorPicker.Root>
+      ))}
+    </div>
+  );
+}

package/dist/skill/reference/components/color-picker/examples/in-form.tsx

@@ -0,0 +1,52 @@
+/** Theme settings: the color goes with the form, a too light color shakes in an error on save that leaves once the color changes — `value`, `error`. */
+import { Button, Input, Typography } 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 [saved, setSaved] = React.useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const lightness = color.toFormat("hsl").getChannelValue("lightness");
+    const next =
+      lightness > MAX_LIGHTNESS ? "Слишком светлый: белый текст на нём не читается" : undefined;
+    setError(next);
+    setSaved(next === 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);
+          setSaved(false);
+        }}
+      >
+        <ColorPicker.HexInput label="Цвет кнопок" error={error} />
+      </ColorPicker.Root>
+      <input type="hidden" name="buttonColor" value={color.toString("hex")} />
+      {saved ? (
+        <Typography as="p" variant="body-s" tone="secondary" role="status">
+          Тема сохранена.
+        </Typography>
+      ) : null}
+      <div className={styles.actions}>
+        <Button.Root type="submit">Сохранить тему</Button.Root>
+      </div>
+    </form>
+  );
+}

package/dist/skill/reference/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>
+            <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/dist/skill/reference/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/dist/skill/reference/components/color-picker/examples/presets-sizes.tsx

@@ -0,0 +1,28 @@
+/** 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.SwatchButton />
+            </ColorPresets.Trigger>
+            <ColorPresets.Content />
+          </ColorPresets.Root>
+          <Input.Root size={size}>
+            <Input.Wrapper>
+              <Input.Field aria-label={`Название метки, ${size}`} defaultValue="Маркетинг" />
+            </Input.Wrapper>
+          </Input.Root>
+        </div>
+      ))}
+    </>
+  );
+}

package/dist/skill/reference/components/color-picker/examples/presets.tsx

@@ -0,0 +1,35 @@
+/** A quick color from the palette: a square trigger next to a field and a Button trigger; «no color» allowed — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`. */
+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.SwatchButton />
+        </ColorPresets.Trigger>
+        <ColorPresets.Content />
+      </ColorPresets.Root>
+      <ColorPresets.Root defaultValue="#22c55e">
+        <ColorPresets.Trigger>
+          <Button.Root variant="soft" tone="neutral">
+            <Button.Icon>
+              <ColorPresets.Swatch />
+            </Button.Icon>
+            Цвет проекта
+          </Button.Root>
+        </ColorPresets.Trigger>
+        <ColorPresets.Content label="Цвет проекта" />
+      </ColorPresets.Root>
+    </div>
+  );
+}