@cube-dev/ui-kit 0.155.0 → 0.157.0

package/docs/components/fields/ColorInput.md

@@ -0,0 +1,284 @@
+# ColorInput
+
+An input for a single color. It reads and writes color **text** — hex, `rgb()`,
+`hsl()`, `okhsl()`, `okhst()` and `oklch()` — shows the current color as a
+swatch, and opens a popover where the color can be dialed in on three
+perceptual axes.
+
+Every conversion goes through [Glaze](https://github.com/tenphi/glaze), so the
+canonical value the picker holds is OKHSL: bounded on every channel, and always
+inside the sRGB gamut. That is what makes an out-of-gamut state impossible and
+lets the same value be re-serialized into any of the supported notations without
+drift.
+
+## When to Use
+
+- Theme and branding forms — a seed color, an accent, a chart series color
+- Anywhere a color has to be typed *or* explored, rather than chosen from a
+  fixed palette
+- When the stored format matters (a design token file wants `oklch()`, a legacy
+  API wants hex) and the input has to guarantee it
+
+Reach for a `RadioGroup` or `Picker` of swatches instead when the choice is
+limited to a handful of approved colors.
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string | null` — The selected color (controlled)
+- **`defaultValue`** `string | null` — The selected color (uncontrolled)
+- **`onChange`** `(value: string | null) => void` — Fired with the color string, or `null` when the field is cleared
+- **`format`** `'hex' | 'rgb' | 'hsl' | 'okhsl' | 'okhst' | 'oklch'` (default: `hex`) — Notation the value is written in, and the one `forced` mode displays
+- **`formatMode`** `'forced' | 'derive' | 'free'` (default: `forced`) — How strictly the input text is tied to `format`
+- **`defaultSpace`** `'hst' | 'lch' | 'rgb'` (default: `hst`) — Color concept the popover opens with
+- **`placeholder`** `string` (default: `Pick a color`) — Text shown while the field is empty
+- **`size`** `'small' | 'medium' | 'large' | (string & {})` (default: `medium`) — Input size
+- **`isOpen`** `boolean` — Whether the popover is open (controlled)
+- **`defaultOpen`** `boolean` (default: `false`) — Whether the popover is open initially
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the popover may flip to the other side of the input
+- **`onFocus`** `(event: FocusEvent) => void` — Fired when the text input receives focus
+- **`onBlur`** `(event: FocusEvent) => void` — Fired when the text input loses focus
+
+Named CSS colors (`red`, `rebeccapurple`) are **not** accepted — they are not a
+color space, and Glaze does not resolve them either. Alpha is parsed but
+dropped: the value is always opaque.
+
+Focusing the field selects the whole value, so a pasted color replaces it
+outright. The string is the unit of editing here: a single channel is tuned with
+the sliders rather than by hand-editing one number inside `oklch(…)`. Clicking a
+field that already has focus positions the caret as usual, so the text stays
+editable by hand.
+
+Rendered inside a color popover — as `ColorPicker` does at the top of its panel
+— the trigger is dropped automatically, since the popover it would open is the
+one already showing.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the input wrapper — the element that owns the border, fill and size.
+
+**Sub-elements:**
+
+- `Prefix` — the container holding the color swatch
+- `Suffix` — the container holding the validation state, then the popover trigger
+- `InputIcon` — the swatch slot
+- `State` — the validation / loading indicator
+
+#### inputStyles
+
+Customizes the `<input>` element itself.
+
+#### triggerStyles
+
+Customizes the popover trigger button.
+
+#### swatchStyles
+
+Customizes the color swatch shown inside the input.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+- **Color:** `color`, `fill`, `fade`, `image`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier   | Type      | Description                                       |
+| ---------- | --------- | ------------------------------------------------- |
+| `focused`  | `boolean` | The text input has focus                          |
+| `hovered`  | `boolean` | The pointer is over the input                     |
+| `disabled` | `boolean` | The picker is disabled                            |
+| `valid`    | `boolean` | The field is in the valid state                   |
+| `invalid`  | `boolean` | The field is in the invalid state                 |
+| `prefix`   | `boolean` | A prefix (the swatch) is rendered                 |
+| `suffix`   | `boolean` | A suffix (the trigger) is rendered                |
+
+The swatch carries its own `empty` modifier while there is no color to show.
+
+## Format modes
+
+The three modes differ in how much freedom the *text* gets. The value is always
+a real color in every one of them.
+
+| Mode     | Text                                | Value                                                |
+| -------- | ----------------------------------- | ---------------------------------------------------- |
+| `forced` | Rewritten in `format` on blur/Enter | Written in `format` from the first change on          |
+| `derive` | Left exactly as typed               | Normalized in the notation the text is written in    |
+| `free`   | Left exactly as typed               | The text itself, verbatim                            |
+
+In every mode an entry that is not a color is rejected: the previous valid color
+stays the value while it is being typed, and the text snaps back to it on blur.
+Emptying the field is not an error — it commits `null`.
+
+**The value you pass in is left as you wrote it.** No mode reformats it on mount,
+including `forced` — doing so would mean calling `onChange` before the user has
+touched anything, which marks a form dirty for no reason. `forced` normalizes the
+text for display straight away, so the field can show `#7a4dbf` while the value
+is still the `rgb(122 77 191)` you supplied; from the first change onward the
+value is written in `format` too. Normalize before storing if the notation
+matters to you from the outset.
+
+```jsx
+// A design-token form that must store OKLCH
+<ColorInput label="Accent" format="oklch" onChange={setAccent} />
+
+// A CSS editor: keep whatever the author wrote, but guarantee it parses
+<ColorInput label="Color" formatMode="free" onChange={setCss} />
+```
+
+## Color spaces
+
+The popover edits one canonical color through three sets of axes:
+
+| Space | Axes                          | Good for                                              |
+| ----- | ----------------------------- | ----------------------------------------------------- |
+| `hst` | Hue, Saturation, Tone (OKHST) | Building ramps — equal tone steps read as equal steps |
+| `lch` | Lightness, Chroma, Hue (OKLCH)| Matching a value from a design-token file             |
+| `rgb` | Red, Green, Blue              | Matching a value from a legacy palette or a screenshot|
+
+Each of these opens on its own space; the switcher inside the popover moves
+between them at any time.
+
+`H` means the same angle in HST and LCH, so the hue strip is identical in both.
+The chroma slider is bounded by the sRGB gamut at the current lightness and hue,
+which is why its range changes as `L` moves.
+
+## Examples
+
+### Basic usage
+
+```jsx
+<ColorInput label="Brand color" defaultValue="#7a4dbf" />
+```
+
+### Controlled
+
+```jsx
+const [color, setColor] = useState('#7a4dbf');
+
+<ColorInput label="Brand color" value={color} onChange={setColor} />;
+```
+
+### Inside a form
+
+```jsx
+<Form onSubmit={onSubmit}>
+  <ColorInput
+    name="accent"
+    label="Accent color"
+    format="oklch"
+    rules={[{ required: true, message: 'Pick an accent color' }]}
+  />
+</Form>
+```
+
+### Opening on a specific space
+
+```jsx
+<ColorInput label="Series color" defaultSpace="rgb" defaultValue="#26fcb2" />
+```
+
+### Using the value as a style
+
+Because the emitted value is a plain color string, it can go straight into a
+tasty style — including the `okhsl()` and `okhst()` notations, which tasty
+parses natively.
+
+```jsx
+const [color, setColor] = useState('okhst(264 80% 60%)');
+
+<>
+  <ColorInput label="Fill" format="okhst" value={color} onChange={setColor} />
+  <Block fill={color} height="10x" radius="1r" />
+</>;
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — moves focus to the text input, then to the popover trigger
+- `Enter` — commits and normalizes the typed color without leaving the field
+- `Space` / `Enter` on the trigger — opens the popover
+- `Escape` — closes the popover
+- `Left` / `Right`, `Home` / `End` on a channel slider — moves that channel
+- `Left` / `Right` on the space switcher — moves between HST, LCH and RGB
+
+### Screen Reader Support
+
+- The text input announces as a textbox with the field's label
+- The trigger announces as "Open the color picker"
+- The popover announces as a dialog named "Color picker"
+- Each channel slider sits in a group named after its axis (`Hue`,
+  `Saturation`, `Tone`, `Lightness`, `Chroma`, `Red`, `Green`, `Blue`)
+- The swatch is decorative and is not announced — the text carries the value
+
+### ARIA Properties
+
+- `aria-label` — names the field when there is no visible label
+- `aria-describedby` — wired to the field description by the form system
+
+## Best Practices
+
+1. **Do**: name the field, so the text input is announced meaningfully
+
+   ```jsx
+   <ColorInput label="Brand color" />
+   ```
+
+2. **Don't**: rely on the swatch alone to convey the value
+
+   ```jsx
+   <ColorInput aria-label="" />
+   ```
+
+3. **Do**: pick the `format` your backend stores, and leave `formatMode` at
+   `forced` so the two can never disagree.
+
+4. **Don't**: use `free` mode when the value is later parsed by something
+   stricter than a browser — the text is passed through as written.
+
+## Integration with Forms
+
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string, and clearing the input
+stores `null`, which makes `required` rules behave as expected.
+
+## Suggested Improvements
+
+- An eyedropper that samples a pixel from the page, where
+  [`EyeDropper`](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is
+  available
+- Optional alpha support, which the canonical value currently drops
+- A row of recent or preset swatches inside the popover
+- Editable numeric inputs next to each channel slider, for exact entry without
+  going through the text field
+
+## Related Components
+
+- [ColorPicker](./ColorPicker.md) — the same popover behind a swatch button, when the color is never typed
+- [HueSlider](./HueSlider.md) — just the hue axis, when only a hue is needed
+- [Slider](./Slider.md) — the primitive each channel is built from
+- [TextInput](./TextInput.md) — the input chrome this component reuses

package/docs/components/fields/ColorPicker.md

@@ -0,0 +1,212 @@
+# ColorPicker
+
+A swatch button that opens the color popover. It is the same popover
+[ColorInput](./ColorInput.md) uses — three perceptual axes backed
+by [Glaze](https://github.com/tenphi/glaze) — without the text field in front of
+it.
+
+Reach for it when a color is **chosen but never typed**. Reach for `ColorInput`
+when someone needs to paste `#7a4dbf` from a brand guide.
+
+## When to Use
+
+- A toolbar or inspector where space is tight
+- A chart legend, a tag color, a cell in a dense table
+- Anywhere the exact notation is an implementation detail the user never sees
+
+Use [ColorInput](./ColorInput.md) instead when the color has to be
+readable and pasteable as text.
+
+## Component
+
+---
+
+### Properties
+
+- **`value`** `string | null` — The selected color (controlled)
+- **`defaultValue`** `string | null` — The selected color (uncontrolled)
+- **`onChange`** `(value: string | null) => void` — Fired with the color string
+- **`format`** `'hex' | 'rgb' | 'hsl' | 'okhsl' | 'okhst' | 'oklch'` (default: `hex`) — Notation the value is written in, and the one shown on the trigger
+- **`defaultSpace`** `'hst' | 'lch' | 'rgb'` (default: `hst`) — Color concept the popover opens with
+- **`children`** `ReactNode` — Replaces the color shown on the trigger. Pass `null` for a swatch on its own
+- **`placeholder`** `ReactNode` (default: `Pick a color`) — Shown on the trigger while there is no color
+- **`type`** `CubeItemProps['type']` (default: `outline`) — Visual type of the trigger
+- **`theme`** `CubeItemProps['theme']` (default: `default`) — Theme of the trigger
+- **`size`** `CubeItemProps['size']` — Size of the trigger
+- **`triggerTooltip`** `CubeItemProps['tooltip']` — Tooltip for the trigger, separate from the field tooltip
+- **`swatches`** `Array<string | { color: string; label?: string }>` — Colors to offer under the editor, as a [ColorSwatchGroup](./ColorSwatchGroup.md)
+- **`swatchColumns`** `number` — How many swatches per row. Defaults to a single row
+- **`isOpen`** `boolean` — Whether the popover is open (controlled)
+- **`defaultOpen`** `boolean` (default: `false`) — Whether the popover is open initially
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the popover may flip to the other side of the trigger
+
+There is no `formatMode`: with no text to reconcile, `format` alone decides how
+the value is written. Everything else about the color model — the notations it
+reads, the gamut handling, the three spaces — is identical to `ColorInput` and
+documented there.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the wrapper around the trigger.
+
+#### triggerStyles
+
+Customizes the trigger button itself.
+
+#### swatchStyles
+
+Customizes the color swatch.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier      | Type      | Description                          |
+| ------------- | --------- | ------------------------------------ |
+| `placeholder` | `boolean` | No color is selected yet             |
+
+The swatch carries its own `empty` modifier while there is no color to show.
+
+### The value as text
+
+The popover carries a `ColorInput` above the preview, so the exact color can be
+read, copied, pasted and normalized in place rather than only dialed in. It has
+no trigger of its own — a disclosure inside the thing it discloses would be
+meaningless — and clearing it clears the picker.
+
+### A palette under the editor
+
+Pass `swatches` and a [ColorSwatchGroup](./ColorSwatchGroup.md)
+appears below the channels, so a common color is one press away.
+
+```jsx
+<ColorPicker label="Brand color" swatches={palette} swatchColumns={4} />
+```
+
+That group never offers its own custom-color escape hatch, since the escape
+hatch is a `ColorPicker` and would nest popovers without end.
+
+## Examples
+
+### Basic usage
+
+```jsx
+<ColorPicker label="Series color" defaultValue="#7a4dbf" />
+```
+
+### A swatch on its own
+
+Drop the label for a compact button — a toolbar, or a cell in a table.
+
+```jsx
+<ColorPicker aria-label="Series color" value={color} onChange={setColor}>
+  {null}
+</ColorPicker>
+```
+
+Give it an `aria-label` when you do: with no visible text, that is the only
+thing naming the control.
+
+### A label of your own
+
+```jsx
+<ColorPicker value={color} onChange={setColor}>
+  Accent
+</ColorPicker>
+```
+
+### Trigger types
+
+### Inside a form
+
+```jsx
+<Form onSubmit={onSubmit}>
+  <ColorPicker
+    name="accent"
+    label="Accent color"
+    format="oklch"
+    rules={[{ required: true, message: 'Pick an accent color' }]}
+  />
+</Form>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — moves focus to the trigger
+- `Space` / `Enter` — opens the popover
+- `Escape` — closes it
+- `Left` / `Right`, `Home` / `End` on a channel slider — moves that channel
+- `Left` / `Right` on the space switcher — moves between HST, LCH and RGB
+
+### Screen Reader Support
+
+- The trigger announces as a button, named by the field label, `aria-label`, or
+  its own text
+- The popover announces as a dialog named "Color picker"
+- Each channel slider sits in a group named after its axis
+- The swatch is decorative; the color is announced as the trigger's text unless
+  you replace it
+
+### ARIA Properties
+
+- `aria-label` — names the trigger when there is no visible label or text
+- `aria-expanded` — reflects the popover state
+
+## Best Practices
+
+1. **Do**: name a swatch-only picker
+
+   ```jsx
+   <ColorPicker aria-label="Series color">{null}</ColorPicker>
+   ```
+
+2. **Don't**: leave a swatch-only picker unnamed — the swatch says nothing to a
+   screen reader
+
+   ```jsx
+   <ColorPicker>{null}</ColorPicker>
+   ```
+
+3. **Do**: reach for `ColorInput` the moment someone might want to paste a hex
+   value; a picker alone makes that impossible.
+
+## Integration with Forms
+
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string.
+
+## Suggested Improvements
+
+- A row of recent or preset swatches inside the popover
+- An eyedropper that samples a pixel from the page, where
+  [`EyeDropper`](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper) is
+  available
+- Clearing the color back to `null` from the trigger
+
+## Related Components
+
+- [ColorInput](./ColorInput.md) — the same popover behind a text field
+- [Picker](./Picker.md) — the same trigger-plus-popover shape, for lists
+- [HueSlider](./HueSlider.md) — just the hue axis

package/docs/components/fields/ColorSwatchGroup.md

@@ -0,0 +1,206 @@
+# ColorSwatchGroup
+
+A grid of color swatches, one of which can be selected. It is the palette half
+of choosing a color, where [ColorPicker](./ColorPicker.md) is the
+freeform half — and the two compose: pass `swatches` to a `ColorPicker` and the
+palette appears under the editor.
+
+Under the hood it is a radio group, so one tab stop and arrow keys move between
+swatches. The API is shaped after `Picker` rather than `RadioGroup`: colors go in
+as data, not as children.
+
+## When to Use
+
+- A brand or theme palette where freeform color would be wrong
+- Chart series, tag and label colors — a small approved set
+- Inside a `ColorPicker` popover, as a shortcut past the sliders
+
+## Component
+
+---
+
+### Properties
+
+- **`colors`** `Array<string | { color: string; label?: string }>` — The colors to offer
+- **`value`** `string | null` — The selected color (controlled)
+- **`defaultValue`** `string | null` — The selected color (uncontrolled)
+- **`onChange`** `(value: string | null) => void` — Fired with the chosen color, written in `format`
+- **`format`** `'hex' | 'rgb' | 'hsl' | 'okhsl' | 'okhst' | 'oklch'` (default: `hex`) — Notation the value is written in
+- **`columns`** `number` — Pin the swatches to a fixed grid. By default they wrap to fill the available width
+- **`allowCustom`** `boolean` (default: `false`) — Append a `ColorPicker` for colors outside the set
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of each swatch
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the grid.
+
+#### swatchStyles
+
+Customizes an individual swatch.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+
+### Style Props on the group
+
+`ColorSwatchGroup` and `ColorPicker` both take the outer and block style props,
+so `radius`, `border`, `padding` and `shadow` work directly on them.
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier   | Type      | Description                        |
+| ---------- | --------- | ---------------------------------- |
+| `selected` | `boolean` | The swatch is the selected color   |
+| `empty`    | `boolean` | The swatch has no color to show    |
+| `disabled` | `boolean` | The group is disabled              |
+
+## ColorSwatch
+
+The square itself is exported, for the times you need to show a color without a
+control around it — a legend, a table cell, a summary line. It takes direct
+style props, so its shape and size are yours:
+
+```jsx
+<ColorSwatch color="#7a4dbf" radius="round" width="4x" height="4x" />
+```
+
+It is decorative on its own: pair it with the value as text, or with something
+that names it.
+
+## Swatches must be unique
+
+Equivalent colors are collapsed into one swatch, because two entries for the
+same color make selection ambiguous — there would be no way to say which one is
+selected. Matching is done on the canonical hex, so `#ff0000`, `rgb(255 0 0)`
+and `hsl(0 100% 50%)` are one swatch, not three.
+
+The same matching decides which swatch a value selects, so `value` need not be
+written in the same notation as the swatch it refers to.
+
+## Examples
+
+### Basic usage
+
+```jsx
+<ColorSwatchGroup
+  label="Brand color"
+  colors={['#7a4dbf', '#26fcb2', '#ff0000']}
+  value={color}
+  onChange={setColor}
+/>
+```
+
+### Wrapping onto rows
+
+By default the swatches wrap to fill whatever width they are given: a single row
+where there is room, more rows where there is not. `columns` pins them to a
+fixed grid instead, sized to the swatches rather than stretched across the
+container.
+
+```jsx
+<ColorSwatchGroup colors={palette} columns={4} />
+```
+
+### Naming the swatches
+
+A swatch announces its color by default, which is rarely the most useful thing
+to hear. Give the colors names when they have them.
+
+```jsx
+<ColorSwatchGroup
+  colors={[
+    { color: '#7a4dbf', label: 'Primary' },
+    { color: '#26fcb2', label: 'Success' },
+  ]}
+/>
+```
+
+### Allowing a color outside the set
+
+```jsx
+<ColorSwatchGroup colors={palette} allowCustom />
+```
+
+The trailing picker shows the current color whenever that color is not one of
+the swatches, so a custom choice stays visible.
+
+### Inside a ColorPicker
+
+```jsx
+<ColorPicker label="Brand color" swatches={palette} swatchColumns={4} />
+```
+
+`allowCustom` is ignored there, and deliberately so: the escape hatch is itself
+a `ColorPicker`, so offering it inside one would nest popovers without end. The
+group reads a context the popover provides, which means the recursion cannot be
+written even by hand.
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — moves focus into the group, landing on the selected swatch
+- `Left` / `Right`, `Up` / `Down` — move between swatches, selecting as they go
+- `Space` — selects the focused swatch
+
+### Screen Reader Support
+
+- The group announces as a radiogroup, named by its label or `aria-label`
+- Each swatch announces as a radio named by its `label`, or by its color
+- Give the group a name: "radiogroup" alone says nothing about what is chosen
+
+### ARIA Properties
+
+- `aria-label` — names the group when there is no visible label
+
+## Best Practices
+
+1. **Do**: name the colors when they mean something
+
+   ```jsx
+   <ColorSwatchGroup colors={[{ color: '#ff0000', label: 'Danger' }]} />
+   ```
+
+2. **Don't**: pass the same color twice expecting two swatches — one is dropped
+
+   ```jsx
+   <ColorSwatchGroup colors={['#ff0000', 'rgb(255 0 0)']} />
+   ```
+
+3. **Do**: reach for `allowCustom` only where a color outside the palette is
+   genuinely acceptable. A fixed set is the point of this component.
+
+## Integration with Forms
+
+This component supports all
+[Field properties](../../FieldProperties.md) when used
+within a Form. The field value is the color string.
+
+## Suggested Improvements
+
+- Sections with headings, for palettes with more than one group
+- An optional "no color" swatch that clears the value
+- Multi-selection, for palettes that build a series
+
+## Related Components
+
+- [ColorPicker](./ColorPicker.md) — freeform color behind a swatch button
+- [ColorInput](./ColorInput.md) — freeform color as editable text
+- [RadioGroup](./RadioGroup.md) — the selection primitive this is built on