prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/reference/components/code-block/COMPONENT.md

@@ -0,0 +1,108 @@
+# CodeBlock
+
+**Category:** data-display
+**Kind:** primitive
+
+> A static TypeScript / TSX snippet with syntax highlighting, on a filled panel or bare inside a host.
+
+## When to use
+- Code samples in docs, settings («API key usage») and onboarding.
+- Shell commands and config fragments (long lines scroll inside).
+- An API response sample next to its description.
+
+## When not to use
+- A keyboard key or shortcut → use [Kbd](../kbd/COMPONENT.md).
+- Editable code or text → use [Textarea](../textarea/COMPONENT.md).
+- An inline identifier inside a sentence → [Typography](../typography/COMPONENT.md) `variant="code"`.
+- A live preview with a code tab → use [ExampleFrame](../example-frame/COMPONENT.md).
+
+## Import
+```tsx
+import { CodeBlock } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+CodeBlock        <pre>; variant, colorScheme (data-theme)
+└─ code          <code> with highlighted tokens from the `code` string
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### CodeBlock
+`ref` → `HTMLPreElement`. Renders `<pre><code>`; the markup comes from the escaped, highlighted `code`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `code` | `string` | — (required) | TS / TSX source; trailing whitespace is trimmed, then highlighted. |
+| `variant` | `"soft" \| "ghost"` | `"soft"` | `soft` — a filled panel (one ladder step off its host) with padding and the `code` text role; `ghost` — bare `pre` that inherits type and background from its host. |
+| `colorScheme` | `"light" \| "dark"` | — | Fixes the theme for this block only (`data-theme`). Omit to follow the page theme. |
+| `tabIndex` | `number` | — | Default `0` for `soft` (a scrolling block stays reachable from the keyboard), none for `ghost`; pass `-1` when it never overflows. |
+| `…rest` | `Omit<HTMLAttributes<HTMLPreElement>, "children" \| "dangerouslySetInnerHTML">` | — | `className`, `aria-label` and the other `<pre>` attributes. |
+
+## Variants
+
+### variant
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `soft` | `fill-muted` panel, radius 8, padding 12 × 16, `code` text role, horizontal scroll, Tab stop | standalone snippets anywhere | yes |
+| `ghost` | bare `pre`: no padding, transparent, type inherited from the host | inside a host that draws its own panel | |
+
+### colorScheme
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| — (omitted) | token colors and fill follow the page theme | normal case | yes |
+| `light` | light palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a light sample inside a dark page | |
+| `dark` | dark palette; the soft fill becomes that scheme's floating layer (`layer-floating-bg`) | a terminal-like sample inside a light page | |
+
+Syntax tokens: keywords purple (weight 500), strings teal, numbers orange, JSX tags blue, comments muted italic — palette text tokens, readable in both themes.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| treatment | `variant` | `data-variant` (always set) |
+| fixed scheme | `colorScheme` | `data-theme` re-scopes the palette for the block |
+| focus-visible | keyboard focus on a `soft` block | inset focus ring |
+
+## Layout & spacing
+- `max-width: 100%`; the block takes the column width and long lines scroll horizontally (`white-space: pre`, tab size 2).
+- Heading / text → code block: `--prime-space-2` to `--prime-space-4`.
+- Constrain the column (`--prime-layout-reading-max-width` for docs), not the block.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses a `soft` block so overflowing code can be scrolled. |
+| `←` · `→` | Scroll a focused block horizontally. |
+
+### ARIA
+- Native `<pre>` / `<code>`; screen readers read the text.
+- A `soft` block is a Tab stop (`tabIndex=0`); pass `tabIndex={-1}` when it never overflows.
+- Give standalone blocks an `aria-label` («Команда установки»).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | An API response sample on a filled panel, named for screen readers — `code`, `aria-label`. |
+| [variants.tsx](examples/variants.tsx) | A filled panel and a bare block that takes type and background from its host — `variant`. |
+| [color-scheme.tsx](examples/color-scheme.tsx) | A block fixed to one scheme looks the same in both page themes — `colorScheme`. |
+| [narrow.tsx](examples/narrow.tsx) | In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys. |
+
+## Mistakes
+- Passing JSX children → pass the source string to `code`.
+- A hand-styled `<pre>` for code → use `CodeBlock`.
+- `variant="ghost"` directly on the page → use `soft`, or put `ghost` inside a panel.
+- Wrapping a soft block in another box → the block is already a filled panel.
+
+## Related
+- **Built from:** —
+- **See also:** [Kbd](../kbd/COMPONENT.md), [ExampleFrame](../example-frame/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/dist/skill/reference/components/code-block/examples/color-scheme.tsx

@@ -0,0 +1,16 @@
+/** A block fixed to one scheme looks the same in both page themes — `colorScheme`. */
+import { CodeBlock } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const SAMPLE = `const retries = 3; // повторы при ошибке сети
+export const isReady = (status: "idle" | "busy") => status === "idle";`;
+
+export default function CodeBlockColorSchemeExample() {
+  return (
+    <div className={styles.grid}>
+      <CodeBlock code={SAMPLE} colorScheme="light" aria-label="Светлая схема" />
+      <CodeBlock code={SAMPLE} colorScheme="dark" aria-label="Тёмная схема" />
+    </div>
+  );
+}

package/dist/skill/reference/components/code-block/examples/examples.module.css

@@ -0,0 +1,21 @@
+/* Layout of the CodeBlock scenarios: semantic tokens only. */
+
+/* overview.tsx: a reading-width column. */
+.column {
+  width: min(100%, var(--prime-layout-reading-max-width));
+  min-width: 0;
+}
+
+/* color-scheme.tsx: two blocks side by side, stacked when narrow. */
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  gap: var(--prime-space-4);
+  width: 100%;
+}
+
+/* narrow.tsx: a column narrower than the line. */
+.narrow {
+  width: min(100%, var(--prime-modal-width-s));
+  min-width: 0;
+}

package/dist/skill/reference/components/code-block/examples/narrow.tsx

@@ -0,0 +1,14 @@
+/** In a narrow column a long line scrolls inside the block and never wraps; Tab, then arrow keys. */
+import { CodeBlock } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LONG_LINE = `docker run --rm -e NODE_ENV=production -p 8080:8080 -v "$(pwd)/data:/app/data" registry.example.com/billing-api:latest --config /app/data/config.yml`;
+
+export default function CodeBlockNarrowExample() {
+  return (
+    <div className={styles.narrow}>
+      <CodeBlock code={LONG_LINE} aria-label="Команда запуска контейнера" />
+    </div>
+  );
+}

package/dist/skill/reference/components/code-block/examples/overview.tsx

@@ -0,0 +1,19 @@
+/** An API response sample on a filled panel, named for screen readers — `code`, `aria-label`. */
+import { CodeBlock } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const RESPONSE = `{
+  "id": "ord_8f2a",
+  "total": 14990,
+  "currency": "RUB",
+  "items": [{ "sku": "sku-12", "qty": 2 }]
+}`;
+
+export default function CodeBlockOverviewExample() {
+  return (
+    <div className={styles.column}>
+      <CodeBlock code={RESPONSE} aria-label="Пример ответа GET /orders/:id" />
+    </div>
+  );
+}

package/dist/skill/reference/components/code-block/examples/variants.tsx

@@ -0,0 +1,21 @@
+/** A filled panel and a bare block that takes type and background from its host — `variant`. */
+import { CodeBlock, Typography } from "prime-ui-kit";
+
+const SAMPLE = `const total = formatPrice(14990);`;
+
+const VARIANTS = ["soft", "ghost"] as const;
+
+export default function CodeBlockVariantsExample() {
+  return (
+    <div>
+      {VARIANTS.map((variant) => (
+        <div key={variant}>
+          <CodeBlock code={SAMPLE} variant={variant} />
+          <Typography as="span" variant="caption" tone="muted">
+            {variant}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}

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

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

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

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

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

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

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

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

package/dist/skill/reference/components/color-field/examples/overview.tsx

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

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

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

package/dist/skill/reference/components/color-field/examples/sizes.tsx

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

package/dist/skill/reference/components/color-field/examples/states.tsx

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

package/dist/skill/reference/components/color-field/examples/validation.tsx

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