--- name: color-select-usage description: > Use after component-usage-ux when an app needs @techsio/ui-kit ColorSelect for choosing color swatches with supported layout, size, radius, disabled state, selected state, labels, counts, and single/multiple roles. metadata: component_version: "1.3.0" type: "core" library: "@techsio/ui-kit" library_version: "0.3.2" requires: "component-usage-ux app-token-overrides ux-guidelines" resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md" sources: "" contributor_sources: "libs/ui/src/molecules/color-select.tsx libs/ui/src/tokens/components/molecules/_color-select.css libs/ui/stories/molecules/color-select.stories.tsx" audience: "consumer" --- > Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory. # @techsio/ui-kit ColorSelect Usage Use ColorSelect for product color filters or swatch choices. It is not a general Select replacement. ## UX/UI guidelines House rules come from the `ux-guidelines` skill (writing, formatting, states, where actions and feedback live). This section applies them to `ColorSelect`. **Use it when** - Choosing a product colour/variant by swatch, or filtering a catalog by colour. **Use something else when** | Need | Use instead | | --- | --- | | Choosing any other value | Select / RadioGroup | | Brand theme colour in admin settings | a dedicated color input, not a swatch filter | **Do** - Give every swatch an accessible name with the colour's product name (`Navy`), not the hex value. - Show the selected colour's name next to the control. - Mark unavailable colours as unavailable (not just faded) and explain on the product page. **Don't** - Rely on colour alone — the name must be visible or available on focus. - Use more than ~12 swatches without grouping or a More option. **Copy and states** - Label `Colour` (or `Color`, per locale); selected value shown as `Colour: Navy`. **Behaviour (from the UX spec)** - Hover and focus only highlight; activation proposes a colour and the app updates `selected` together with the variant's photo and price. - If loading the chosen variant fails, never present the old photo or price as the new variant. - Light and near-identical swatches keep a visible boundary and distinct names (two greys can't share a name). **Figma → code** | Figma | Code | | --- | --- | | `ColorSwatch` (one swatch) | one entry in `ColorSelect` `colors`; there is no ColorSwatch component | | `state=selected` / `disabled` | `colors[].selected` / `colors[].disabled` | | `state=hover` / `focus` | not props | | no group, mode or read-only axes | `layout`, `selectionMode`, `readOnly`, `label` | Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/ColorSelect → UX guidelines*. ## Setup ```tsx import { ColorSelect } from "@techsio/ui-kit/molecules/color-select" ``` Supported props: ```text colors: { id, color, selected, label, count, disabled }[] layout: list | grid size: sm | md | lg | full radius: sm | md | lg | full selectionMode: single | multiple disabled, readOnly, name, label, helpText, validateStatus, onColorClick ``` ## Core Patterns ### Use only for swatches Use Select or RadioCard when choices are textual. Use ColorSelect when the visual color itself is the primary choice signal. ### Keep selected state in data Update `colors[].selected` from app state. Do not style selected swatches with manual `className`. ### Allow runtime color values here Swatch fill uses inline `backgroundColor` because the data value is the product color, not a component theme token. ## Controlled selection and focus recovery `colors[].selected` is application-owned; `onColorClick(color)` proposes a choice and does not rewrite the collection. Use stable, unique color values (and stable item IDs when provided). For example: ```tsx import { useState } from "react" import { ColorSelect } from "@techsio/ui-kit/molecules/color-select" function ProductColor() { const [selected, setSelected] = useState("#0f172a") return } ``` If the focused swatch is removed or becomes disabled, focus recovers to a surviving enabled neighbour (or the group when none remain), **without** selecting it or firing `onColorClick`. Collection updates while focus is outside the group never steal it. A removed selected swatch does not authorize an implicit replacement selection: the app decides how to reconcile its selection. Single mode uses a roving radio target; multiple mode uses checkbox semantics. `readOnly` keeps the value inspectable and submitted but suppresses mutations; `disabled`, including native disabled-fieldset inheritance, removes interaction. ## Common Mistakes ### HIGH Custom swatch buttons Wrong: ```tsx