prime-ui-kit 0.15.0 → 0.17.0

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

@@ -31,11 +31,12 @@ in `prime-ui-kit/bundle.css`. `ColorPresets` stays in the main entry and needs n
 ```
 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.SwatchButton   end segment of the field box: the current color, opens a panel
+├─ ColorPicker.TriggerSwatch     square of the current color for your own 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.Thumb
    ├─ ColorPicker.Slider         one channel
    │  ├─ ColorPicker.SliderMeta  label + value row
    │  └─ ColorPicker.SliderTrack
@@ -63,7 +64,10 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | `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`. |
+| `format` | `"hsl" \| "rgb" \| "hex"` | — | Controlled value format of `FormatSelect` and `ChannelStrip`. |
+| `defaultFormat` | `"hsl" \| "rgb" \| "hex"` | `"hsl"` | Initial value format, uncontrolled. |
+| `onFormatChange` | `(format: "hsl" \| "rgb" \| "hex") => void` | — | Called with the format picked in `FormatSelect`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the fields inside (`HexInput`, `FormatSelect`); without it the tier of its host (a panel, a popover), else `m`. |
 | `labels` | `Partial<ColorPickerLabels>` | — | Built-in strings, see Labels. |
 | `children` | `ReactNode` | — (required) | The parts. |
 
@@ -73,6 +77,7 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | 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. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the parts), `className` and the other div attributes. |
 
 ### 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.
@@ -82,10 +87,17 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | `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. |
+| `children` | `ReactNode` | — | End segments of the field box after the value: `ColorPicker.SwatchButton` (in a `Popover.Trigger`), so the hex and its swatch read as one field. |
 | `…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.SwatchButton
+`ref` → `HTMLButtonElement`. The current color as a button segment at the end of `HexInput`: full field height, named `labels.palette`, with a tooltip. Wrap it in `Popover.Trigger` to open the panel.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" \| "children">` | — | `className`, `disabled`, `onClick` and the other attributes of the `<button>`. |
+
 ### 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`.
 
@@ -109,15 +121,15 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | `…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`.
+`ref` → `HTMLDivElement`. React Aria `ColorArea`: a two-channel square (e.g. saturation × lightness). Holds a `ColorPicker.Thumb`.
 
 | 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.
+### ColorPicker.Thumb
+`ref` → `HTMLDivElement`. React Aria `ColorThumb` of the area or of a slider track: a thumb-colored ring with the overlay shadow and a focus ring, sized by its host.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -152,7 +164,8 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | 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`… |
+| `label · hint · error · invalid · required · optional · disabled · size · id · labels · aria-label · aria-labelledby · aria-describedby` | `ColorSwatchesProps` | — | As on `ColorSwatches`. |
+| `…rest` | `Omit<ColorSwatchesProps, "value" \| "defaultValue" \| "onValueChange" \| "allowEmpty" \| "name">` | — | `className` and the other attributes of the field frame. |
 
 ### 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.
@@ -160,10 +173,11 @@ No DOM. Holds the color (React Aria `ColorPicker`) and the value format for ever
 | 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. |
+| `fullWidth · loading · pressed · defaultPressed · onPressedChange · current · density · align · progress · holdToConfirm · onConfirm · labels` | `ButtonRootProps` | — | As on `Button.Root`. |
+| `…rest` | `Omit<ButtonRootProps, "variant" \| "tone" \| "size" \| "aria-label" \| "shape" \| "asChild">` | — | `onClick`, `className` and the other button attributes. |
 
 ### ColorPresets.Root
-A quick color from a fixed palette: a square trigger and a popover grid of presets. No DOM, except a field frame in a FieldList cell (the column heading as its label).
+No DOM and no ref, except a field frame in a FieldList cell (the column heading as its label). A quick color from a fixed palette: a square trigger and a popover grid of presets.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -173,13 +187,16 @@ A quick color from a fixed palette: a square trigger and a popover grid of prese
 | `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. |
+| `closeOnEscape` | `boolean` | `true` | Escape closes the panel and returns focus to the trigger. |
+| `closeOnOutsideClick` | `boolean` | `true` | A press outside the panel and its trigger closes it; focus follows the pointer. |
 | `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`. |
+| `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. |
+| `children` | `ReactNode` | — (required) | `ColorPresets.Trigger` and `ColorPresets.Content`. |
 
 ### 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.
@@ -221,14 +238,14 @@ No `variant` / `tone` / `color`.
 | `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)
+### format (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)
+### size (ColorPicker.Root, ColorPresets)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `xs` | 28px field / trigger, 16px preset swatches | dense tables | |
@@ -237,13 +254,15 @@ No `variant` / `tone` / `color`.
 | `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`).
+**Sizes:** `ColorPresets.SwatchButton` is a square of the control height, so it lines up with an Input of the same size; `ColorPicker.SwatchButton` is a segment inside HexInput, so it takes the field's tier with it. 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` |
+| `closeOnOutsideClick={false}` (ColorPresets) | a press beside the panel keeps it open | comparing presets with the page | `true` |
+| `closeOnEscape={false}` (ColorPresets) | Escape leaves the panel open | the panel closes only by a pick or the trigger | `true` |
 | `disabled` (Area, Slider) | grayscale, no input | the part is locked | — |
 
 **Combinations**
@@ -266,15 +285,17 @@ No `variant` / `tone` / `color`.
 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 width comes from the layout: a popover or a column wide enough for the area and four channel fields.
+- Hex field + palette trigger: `ColorPicker.SwatchButton` as a child of `HexInput` — one field box, the swatch a full-height segment at its end; no row of your own.
 - 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. On a coarse pointer every swatch grows to the 44 px touch target and the grid takes at most 5 columns, so it still fits a 320px panel; the arrow keys walk the same columns.
+- ColorPresets grid: one row for up to 8 presets (+ «no color»), else rows of 8 (`columns` overrides); a panel narrower than the row wraps the swatches into balanced rows (16 → 8 + 8, never 14 + 2). On a coarse pointer every swatch grows to the 44 px touch target and the grid wraps into more rows, so it still fits a 320px panel; the arrow keys walk the rows on screen.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `ArrowLeft` · `ArrowRight` · `ArrowUp` · `ArrowDown` | Move the area thumb or a slider; in the ColorPresets grid, move between swatches. |
@@ -285,8 +306,10 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `Escape` | Closes the ColorPresets panel. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - 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`).
+- `SwatchButton` is a button named `labels.palette` with a tooltip. `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).
@@ -294,11 +317,14 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
+#### ColorPicker.Root
+
 | 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. |
+| `palette` | `"Открыть палитру"` | Name and tooltip of `ColorPicker.SwatchButton`. |
 | `hue` | `"Оттенок, градусы"` | Hue channel field. |
 | `saturation` | `"Насыщенность, проценты"` | Saturation channel field. |
 | `lightness` | `"Яркость, проценты"` | Lightness channel field. |
@@ -306,6 +332,26 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 | `red` | `"Красный, 0–255"` | Red channel field. |
 | `green` | `"Зелёный, 0–255"` | Green channel field. |
 | `blue` | `"Синий, 0–255"` | Blue channel field. |
+
+#### ColorPicker.Swatches
+
+| Key | Default | Used for |
+|---|---|---|
+| `group` | `"Цвет"` | Name of the swatch group without a visible `label` and `aria-label`. |
+| `empty` | `"Без цвета"` | Name of the «no color» swatch (never shown here: the picker has no `allowEmpty`). |
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
+| `colorNames` | `"Серый · Красный · Оранжевый · Жёлтый · Зелёный · Бирюзовый · Голубой · Синий · Фиолетовый · Розовый"` | Names of the palette hues (unused here: the picker swatches are colors). |
+
+#### ColorPicker.EyeDropperButton
+
+| Key | Default | Used for |
+|---|---|---|
+| `holdHint` | `"Удерживайте, чтобы подтвердить"` | Description of the button with `holdToConfirm`. |
+
+#### ColorPresets.Root
+
+| Key | Default | Used for |
+|---|---|---|
 | `trigger` | `"Цвет"` | ColorPresets trigger name prefix: «<trigger>: <color name>»; in a FieldList cell the column heading. |
 | `list` | `"Цвета"` | ColorPresets swatch list name when `Content` has no `label`. |
 | `empty` | `"Без цвета"` | ColorPresets «no color» swatch and the trigger name for an empty value. |
@@ -313,15 +359,15 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 ## 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`. |
+| [overview.tsx](examples/overview.tsx) | A color field: a hex value and a swatch segment at its end that opens the picker panel — `ColorPicker.HexInput`, `ColorPicker.SwatchButton`. |
+| [sizes.tsx](examples/sizes.tsx) | Every tier of the picker: the hex field and its swatch segment take it from the root — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled area, hue slider and preset trigger 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 with «no color» and a Button trigger whose grid of four columns stays open after a pick — `ColorPresets`, `allowEmpty`, `ColorPresets.Trigger`, `columns`, `closeOnSelect`. |
 | [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`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the color and its format: brand swatches and the channels edit it, the format stays as picked, a button resets both — `value`, `onValueChange`, `format`, `onFormatChange`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent opens the preset palette from its own button and keeps the chosen color — `open`, `onOpenChange`, `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`. |
 
@@ -333,8 +379,9 @@ There is no `disabled` on `ColorPicker.Root` — disable parts individually. Con
 - `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.
+- A hex field and a separate swatch `Button` side by side in your own row → put `ColorPicker.SwatchButton` inside `HexInput`.
 - `<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)
+- **Built from:** [Input](../input/COMPONENT.md) (`HexInput`; its field action segment for `SwatchButton`), [Tooltip](../tooltip/COMPONENT.md) (`SwatchButton`), [Label](../label/COMPONENT.md) and [Hint](../hint/COMPONENT.md) (the `HexInput` label, hint and error), [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), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [ColorField](../color-field/COMPONENT.md), [ColorSwatches](../color-swatches/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md)

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

@@ -1,11 +1,12 @@
-/** The parent owns the color: brand swatches and the hex field edit it, a button resets it — `value`, `onValueChange`. */
+/** The parent owns the color and its format: brand swatches and the channels edit it, the format stays as picked, a button resets both — `value`, `onValueChange`, `format`, `onFormatChange`. */
 import { Button } from "prime-ui-kit";
-import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
+import { ColorPicker, type ColorValueFormat, parseColor } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const DEFAULT_COLOR = "#5b5bd6";
+const DEFAULT_FORMAT: ColorValueFormat = "hex";
 const BRAND_COLORS = [
   { value: "#5b5bd6", label: "Индиго" },
   { value: "#0090ff", label: "Синий" },
@@ -16,18 +17,28 @@ const BRAND_COLORS = [
 
 export default function ColorPickerControlledExample() {
   const [color, setColor] = React.useState(() => parseColor(DEFAULT_COLOR));
+  const [format, setFormat] = React.useState<ColorValueFormat>(DEFAULT_FORMAT);
 
   return (
     <div className={styles.panel}>
-      <ColorPicker.Root value={color} onValueChange={setColor}>
-        <ColorPicker.HexInput label="Цвет витрины" hint={`Сейчас: ${color.toString("hex")}`} />
+      <ColorPicker.Root
+        value={color}
+        onValueChange={setColor}
+        format={format}
+        onFormatChange={setFormat}
+      >
+        <ColorPicker.FormatSelect />
+        <ColorPicker.ChannelStrip />
         <ColorPicker.Swatches aria-label="Цвета бренда" presets={BRAND_COLORS} />
       </ColorPicker.Root>
       <div>
         <Button.Root
           variant="soft"
           tone="neutral"
-          onClick={() => setColor(parseColor(DEFAULT_COLOR))}
+          onClick={() => {
+            setColor(parseColor(DEFAULT_COLOR));
+            setFormat(DEFAULT_FORMAT);
+          }}
         >
           Сбросить
         </Button.Root>

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

@@ -5,16 +5,13 @@
   display: flex;
   flex-direction: column;
   gap: var(--prime-space-4);
-  width: calc(var(--prime-panel-min-width) * 1.5);
+  width: var(--prime-layout-min-width);
   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);
+/* overview.tsx: the hex field with its swatch segment at a field's width. */
+.field {
+  width: var(--prime-layout-min-width);
   max-width: 100%;
 }
 
@@ -23,7 +20,7 @@
   display: flex;
   align-items: center;
   gap: var(--prime-space-2);
-  width: calc(var(--prime-panel-min-width) * 1.5);
+  width: var(--prime-layout-min-width);
   max-width: 100%;
 }
 
@@ -34,15 +31,14 @@
   gap: var(--prime-space-3);
 }
 
-/* in-form.tsx: field → field 20, group → actions 32. */
+/* in-form.tsx: the field column (a Fieldset, fields 20 apart) → actions 32. */
 .form {
   display: flex;
   flex-direction: column;
-  gap: var(--prime-space-5);
-  width: min(100%, var(--prime-modal-width-s));
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-layout-form-width-s));
 }
 
 .actions {
   display: flex;
-  margin-top: var(--prime-space-3);
 }

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

@@ -1,5 +1,5 @@
 /** 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 { Button, Fieldset, Input, Typography } from "prime-ui-kit";
 import { ColorPicker, parseColor } from "prime-ui-kit/color-picker";
 import * as React from "react";
 
@@ -23,27 +23,29 @@ export default function ColorPickerInFormExample() {
 
   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}
+      <Fieldset>
+        <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}
+      </Fieldset>
       <div className={styles.actions}>
         <Button.Root type="submit">Сохранить тему</Button.Root>
       </div>

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

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

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

@@ -19,7 +19,7 @@ export default function ColorPickerPanelExample() {
       <ColorPicker.Panel surface="raised" className={styles.panel}>
         <ColorPicker.FormatSelect />
         <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness">
-          <ColorPicker.AreaThumb />
+          <ColorPicker.Thumb />
         </ColorPicker.Area>
         <ColorPicker.Slider channel="hue" colorSpace="hsl">
           <ColorPicker.SliderMeta label="Оттенок" />

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

@@ -1,26 +1,20 @@
-/** Every size of the hex field with a swatch button of the same tier — `size`. */
-import { Button } from "prime-ui-kit";
+/** Every tier of the picker: the hex field and its swatch segment take it from the root — `size`. */
 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 (
-    <>
+    <div>
       {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>
+        <div key={size}>
+          <ColorPicker.Root defaultValue="#0090ff" size={size}>
+            <ColorPicker.HexInput label={size}>
+              <ColorPicker.SwatchButton />
+            </ColorPicker.HexInput>
+          </ColorPicker.Root>
+        </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -1,31 +1,36 @@
 /** A disabled area, hue slider and preset trigger keep showing the color but take no input — `disabled`. */
-import { ColorPresets } from "prime-ui-kit";
+import { ColorPresets, Typography } from "prime-ui-kit";
 import { ColorPicker } from "prime-ui-kit/color-picker";
 
-import styles from "./examples.module.css";
-
 export default function ColorPickerStatesExample() {
   return (
-    <>
-      <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>
+    <div>
+      <div>
+        <ColorPicker.Root defaultValue="#30a46c">
+          <ColorPicker.Panel>
+            <ColorPicker.Area colorSpace="hsl" xChannel="saturation" yChannel="lightness" disabled>
               <ColorPicker.Thumb />
-            </ColorPicker.SliderTrack>
-          </ColorPicker.Slider>
-        </ColorPicker.Panel>
-      </ColorPicker.Root>
-      <ColorPresets.Root disabled defaultValue="#22c55e" labels={{ trigger: "Цвет метки" }}>
-        <ColorPresets.Trigger>
-          <ColorPresets.SwatchButton />
-        </ColorPresets.Trigger>
-        <ColorPresets.Content />
-      </ColorPresets.Root>
-    </>
+            </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>
+      </div>
+      <div>
+        <ColorPresets.Root disabled defaultValue="#22c55e" labels={{ trigger: "Цвет метки" }}>
+          <ColorPresets.Trigger>
+            <ColorPresets.SwatchButton />
+          </ColorPresets.Trigger>
+          <ColorPresets.Content />
+        </ColorPresets.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+    </div>
   );
 }