# OpenSpec Change: enterprise-react-color-picker

- **Change ID**: enterprise-react-color-picker
- **Package**: `@suaveplan/react-color-picker`
- **Category**: react
- **Target path**: `react/forms/react-color-picker`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-color-picker.md`

---

## Summary

Deliver `@suaveplan/react-color-picker` on genesis from scratch at enterprise quality. A React color-picking UI kit: composed `ColorPicker` (hue slider + saturation/value panel + swatch + text input), lower-level components (`HueSlider`, `SaturationPanel`, `ColorSwatch`, `ColorInput`), `useColorPicker` hook, and conversion utilities (hex/RGB/HSL/HSV round-trip). Genesis splits the over-long `color.types.ts` (312 lines → type file + utils file), adds Storybook stories, Playwright E2E, and 100% coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `ColorPickerError` |
| `@suaveplan/react-translate` (`workspace:^`) | i18n for labels |
| `zod` (`catalog:forms`) | Color value schemas |

External: `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
// Components
ColorPicker, HueSlider, SaturationPanel, ColorSwatch, ColorInput

// Hook
useColorPicker (+ UseColorPickerOptions, UseColorPickerReturn)

// Types
ColorFormat, HslColor, HsvColor, RgbColor, ColorPickerProps,
ColorInputProps, ColorSwatchProps, HueSliderProps, SaturationPanelProps

// Utils (≤60 lines each, split from types file)
hexToRgb, rgbToHex, rgbToHsl, hslToRgb, rgbToHsv, hsvToRgb,
isValidHex, parseColor, formatColor
```

---

## New additions for genesis

1. **File size fix** — `color.types.ts` split: types in `color.types.ts` (≤150 lines) + conversions in `color-utils.ts` (≤150 lines).
2. **`ColorPickerError`** — codes: `COLOR_INVALID_HEX`, `COLOR_INVALID_FORMAT`.
3. **Zod `ColorValueSchema`** — validates hex/rgb/hsl strings at the `useColorPicker` boundary.
4. **Alpha channel support** — `ColorFormat` gains `'hexa' | 'rgba' | 'hsla'`; all conversion utils handle alpha.
5. **Stories** — `ColorPicker` (default, compact, alpha, RTL), `HueSlider`, `SaturationPanel`, `ColorSwatch`, `ColorInput`, `useColorPicker` playground.
6. **Playwright E2E** — open picker, drag hue slider, verify output hex.

---

## File layout

```text
react/forms/react-color-picker/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      color-picker/ (tsx + types + md + test + stories + index)
      hue-slider/ (tsx + types + md + test + stories + index)
      saturation-panel/ (tsx + types + md + test + stories + index)
      color-swatch/ (tsx + types + md + test + stories + index)
      color-input/ (tsx + types + md + test + stories + index)
    hooks/
      use-color-picker/ (ts + types + md + test + stories + index)
    types/
      color.types.ts (≤150 lines)
    utils/
      color-utils/ (ts + md + test + index)
  e2e/
    color-picker.spec.ts
```