@etus/ui 0.1.0

package/src/components/forms/ColorPicker/README.md

@@ -0,0 +1,809 @@
+# ColorPicker
+
+## Visao Geral
+
+O **ColorPicker** e um componente de formulario do Design System ETUS que permite aos usuarios selecionar cores atraves de uma interface intuitiva com seletor nativo do navegador, campo de entrada hexadecimal e swatches predefinidos.
+
+### Casos de Uso
+
+- Selecao de cores em editores visuais
+- Personalizacao de temas e aparencia
+- Formularios de configuracao de marca/branding
+- Editores de graficos e visualizacoes
+- Customizacao de elementos de UI
+
+### Classificacao
+
+**Categoria:** Molecule (Form Control)
+**Dependencias:** `@radix-ui/react-popover`, `class-variance-authority`, `lucide-react`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Uso geral, formularios padrao | `border-input`, `shadow-xs`, `dark:bg-input/30` |
+| `filled` | Enfase maior, campos destacados | `border-transparent`, `bg-muted` |
+| `flushed` | Estilo minimalista, inline | `border-x-0`, `border-t-0`, `border-b-input`, `rounded-none` |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura | Padding | Swatch Preview | Uso |
+|---------|--------|---------|----------------|-----|
+| `sm` | `h-8` (32px) | `px-2.5 py-1` | `size-4` | Espacos compactos, tabelas |
+| `md` | `h-9` (36px) | `px-3 py-1` | `size-5` | Uso geral |
+| `lg` | `h-10` (40px) | `px-3.5 py-1.5` | `size-6` | CTAs, formularios destacados |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparencia base |
+| Hover | `hover:scale-110` (swatches) | Escala swatches no hover |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Open | `data-state="open"` | Popover visivel |
+| Disabled | `disabled:opacity-50` | 50% opacidade, sem pointer events |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho |
+| Selected | `ring-2 ring-ring ring-offset-2` | Swatch selecionado destacado |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--input             /* Borda do trigger e swatches */
+--ring              /* Focus ring */
+--muted             /* Fundo variant filled */
+--muted-foreground  /* Texto placeholder */
+--destructive       /* Estado invalido */
+
+/* Espacamento */
+gap-2               /* Entre preview e texto */
+p-3                 /* Padding do popover content */
+gap-2               /* Grid de swatches */
+
+/* Tipografia */
+text-sm             /* Texto do trigger (sm) */
+text-base           /* Texto do trigger (md/lg) */
+font-mono           /* Campo hex input */
+
+/* Bordas */
+rounded-md          /* Trigger e swatches */
+rounded-sm          /* Preview swatch */
+
+/* Transicoes */
+transition-all      /* Cores e transformacoes */
+```
+
+### data-slot
+
+```html
+<div data-slot="color-picker">
+  <button data-slot="color-picker-trigger">
+    <span data-slot="color-picker-preview" />
+  </button>
+  <div data-slot="color-picker-content">
+    <input data-slot="color-picker-native" type="color" />
+    <input data-slot="color-picker-input" type="text" />
+    <div data-slot="color-picker-swatches">
+      <button data-slot="color-picker-swatch" />
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `value` | `string` | - | Valor controlado da cor (formato hex como "#ff0000") |
+| `defaultValue` | `string` | - | Valor inicial (modo nao-controlado) |
+| `placeholder` | `string` | `"Select color"` | Texto quando nenhuma cor selecionada |
+| `disabled` | `boolean` | `false` | Desabilita o color picker |
+| `swatches` | `string[]` | `DEFAULT_SWATCHES` | Array de cores preset (formato hex) |
+| `showInput` | `boolean` | `true` | Exibe campo de entrada hexadecimal |
+| `showPreview` | `boolean` | `true` | Exibe preview da cor no trigger |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tamanho visual do trigger |
+| `variant` | `"default" \| "filled" \| "flushed"` | `"default"` | Estilo visual do trigger |
+| `required` | `boolean` | `false` | Campo obrigatorio |
+| `invalid` | `boolean` | `false` | Estado de validacao invalida |
+| `id` | `string` | - | ID para associacao com label |
+| `name` | `string` | - | Name para submissao de formulario |
+| `className` | `string` | - | Classes CSS adicionais |
+
+> Herda todas as props de `React.ComponentProps<"div">` (exceto `onChange`, `value`, `defaultValue`)
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(color: string) => void` | Disparado quando a cor muda |
+| `onOpenChange` | `(open: boolean) => void` | Disparado quando o popover abre/fecha |
+
+### TypeScript
+
+```typescript
+import type {
+  ColorPickerProps,
+  ColorPickerSize,
+  ColorPickerVariant
+} from "@etus/ui"
+
+// ColorPickerProps inclui:
+interface ColorPickerProps {
+  value?: string
+  defaultValue?: string
+  placeholder?: string
+  disabled?: boolean
+  swatches?: string[]
+  showInput?: boolean
+  showPreview?: boolean
+  onChange?: (color: string) => void
+  onOpenChange?: (open: boolean) => void
+  size?: ColorPickerSize
+  variant?: ColorPickerVariant
+  required?: boolean
+  invalid?: boolean
+  id?: string
+  name?: string
+  // ... + props de <div> (exceto conflitos)
+}
+
+// Tipos derivados
+type ColorPickerSize = "sm" | "md" | "lg"
+type ColorPickerVariant = "default" | "filled" | "flushed"
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Ariakit | Fluent | Carbon | PrimeReact | React Color | Radix |
+|---------|:----:|:------:|:---:|:-------:|:----:|:------:|:-------:|:------:|:------:|:----------:|:-----------:|:-----:|
+| **Variantes trigger** | 3 | 2 | 1 | 3 | 2 | 2 | - | 2 | 1 | 2 | - | - |
+| **Tamanhos** | 3 | 3 | 3 | 4 | 3 | 3 | - | 3 | 2 | 3 | - | - |
+| **Swatches/Presets** | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | - |
+| **Native color input** | ✓ | - | - | - | - | - | - | - | - | - | - | - |
+| **Hex input** | ✓ | ✓ | - | ✓ | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | - |
+| **RGB input** | - | ✓ | - | ✓ | ✓ | - | - | ✓ | - | ✓ | ✓ | - |
+| **HSL input** | - | ✓ | - | ✓ | ✓ | - | - | - | - | ✓ | ✓ | - |
+| **Alpha/Opacity** | - | ✓ | - | ✓ | ✓ | - | - | ✓ | - | ✓ | ✓ | - |
+| **Eyedropper** | - | - | - | ✓ | - | - | - | - | - | - | - | - |
+| **Controlled/Uncontrolled** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| **Form integration** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | - | - |
+| **data-slot** | ✓ | - | - | - | - | ✓ | - | - | - | - | - | - |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | Mantine | AntD | PrimeReact | Fluent |
+|------|:----:|:------:|:-------:|:----:|:----------:|:------:|
+| `value` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `defaultValue` | ✓ | `defaultColor` | ✓ | ✓ | - | ✓ |
+| `onChange` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | ✓ |
+| `size` | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| `swatches` | ✓ | `presets` | ✓ | `presets` | `presetColors` | - |
+| `showInput` | ✓ | - | - | `showText` | `inline` | - |
+| `format` | - | - | ✓ | `format` | `format` | - |
+| `alpha` | - | - | ✓ | - | - | ✓ |
+| `eyedropper` | - | - | ✓ | - | - | - |
+
+#### Analise por Categoria
+
+**Completos (muitas features):**
+- **Mantine** - Mais completo: formatos, alpha, eyedropper, swatches
+- **Ant Design** - Enterprise, presets, formatos
+- **PrimeReact** - Inline/overlay, varios formatos
+
+**Minimalistas (foco na simplicidade):**
+- **ETUS** - Focado em hex, native picker, swatches
+- **NextUI** - Simples, popover
+- **Fluent UI** - Basic + alpha
+
+**Especializados:**
+- **React Color** - Standalone lib, multiplos pickers (Sketch, Chrome, etc)
+- **Chakra UI** - Sistema de popover + inputs
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="combobox"` | Trigger atua como combobox |
+| `aria-expanded` | Indica estado aberto/fechado do popover |
+| `aria-haspopup="dialog"` | Indica que abre um dialog |
+| `aria-required` | Quando `required={true}` |
+| `aria-invalid` | Quando `invalid={true}` |
+| `aria-label` | Nos inputs internos e swatches |
+| `aria-pressed` | Nos swatches para indicar selecao |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco entre elementos |
+| `Enter` | Abre popover / Seleciona swatch |
+| `Space` | Abre popover / Seleciona swatch |
+| `Escape` | Fecha popover |
+| `Arrow Keys` | Navegacao nos swatches (via navegacao nativa) |
+
+### Focus Management
+
+```tsx
+// Focus visible apenas para navegacao por teclado
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+
+// Swatches
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-ring
+focus-visible:ring-offset-2
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Trigger text | `--foreground` | `--background` | >= 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
+| Swatch border | `--input` | swatch color | Variavel |
+
+### Screen Readers
+
+- Input de cor nativo possui `aria-label="Choose color"`
+- Input hex possui `aria-label="Hex color value"`
+- Cada swatch possui `aria-label="Select color {hex}"`
+- Container de swatches possui `role="group"` e `aria-label="Color swatches"`
+
+### Reduced Motion
+
+```css
+/* Respeitar preferencia do usuario */
+@media (prefers-reduced-motion: reduce) {
+  .transition-all {
+    transition: none;
+  }
+  .hover\:scale-110:hover {
+    transform: none;
+  }
+}
+```
+
+### Comparativo A11y (Design Systems)
+
+| Feature | ETUS | React Aria | Chakra | MUI | Mantine | AntD | Fluent | Carbon |
+|---------|:----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| **ARIA roles** | ✓ | ✓ | ~ | ~ | ~ | ~ | ✓ | ✓ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **Keyboard nav** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **aria-pressed** | ✓ | ✓ | - | - | - | - | ✓ | - |
+| **aria-invalid** | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ |
+| **Screen reader labels** | ✓ | ✓ | ~ | ~ | ~ | ~ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { ColorPicker } from "@etus/ui"
+
+function Example() {
+  return <ColorPicker />
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+import { ColorPicker } from "@etus/ui"
+
+function ControlledExample() {
+  const [color, setColor] = useState("#3b82f6")
+
+  return (
+    <div>
+      <ColorPicker value={color} onChange={setColor} />
+      <p>Selected: {color}</p>
+    </div>
+  )
+}
+```
+
+### Nao Controlado com Valor Default
+
+```tsx
+<ColorPicker defaultValue="#ef4444" />
+```
+
+### Variantes
+
+```tsx
+<ColorPicker variant="default" placeholder="Default variant" />
+<ColorPicker variant="filled" placeholder="Filled variant" />
+<ColorPicker variant="flushed" placeholder="Flushed variant" />
+```
+
+### Tamanhos
+
+```tsx
+<ColorPicker size="sm" placeholder="Small" />
+<ColorPicker size="md" placeholder="Medium" />
+<ColorPicker size="lg" placeholder="Large" />
+```
+
+### Swatches Customizados
+
+```tsx
+const brandColors = [
+  "#1a1a1a", // Black
+  "#ffffff", // White
+  "#3b82f6", // Brand blue
+  "#10b981", // Success green
+  "#f59e0b", // Warning orange
+  "#ef4444", // Error red
+]
+
+<ColorPicker
+  swatches={brandColors}
+  placeholder="Choose brand color"
+/>
+```
+
+### Sem Swatches
+
+```tsx
+<ColorPicker swatches={[]} placeholder="No presets" />
+```
+
+### Sem Input Hex
+
+```tsx
+<ColorPicker showInput={false} placeholder="Only native picker" />
+```
+
+### Sem Preview no Trigger
+
+```tsx
+<ColorPicker showPreview={false} placeholder="No preview swatch" />
+```
+
+### Estados
+
+```tsx
+// Disabled
+<ColorPicker disabled placeholder="Disabled" />
+
+// Invalid
+<ColorPicker invalid placeholder="Invalid color" />
+
+// Required
+<ColorPicker required placeholder="Required field" />
+```
+
+### Integracao com Formulario
+
+```tsx
+import { useForm } from "react-hook-form"
+import { ColorPicker } from "@etus/ui"
+import { Label } from "@etus/ui"
+
+function FormExample() {
+  const { register, handleSubmit, setValue, watch } = useForm({
+    defaultValues: { themeColor: "#3b82f6" }
+  })
+
+  const themeColor = watch("themeColor")
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <div className="space-y-2">
+        <Label htmlFor="theme-color">Theme Color</Label>
+        <ColorPicker
+          id="theme-color"
+          name="themeColor"
+          value={themeColor}
+          onChange={(color) => setValue("themeColor", color)}
+          required
+        />
+      </div>
+      <Button type="submit">Save</Button>
+    </form>
+  )
+}
+```
+
+### Com Label e Descricao
+
+```tsx
+<div className="space-y-2">
+  <Label htmlFor="accent-color">Accent Color</Label>
+  <ColorPicker
+    id="accent-color"
+    name="accentColor"
+    defaultValue="#8b5cf6"
+  />
+  <p className="text-sm text-muted-foreground">
+    Used for highlights and interactive elements.
+  </p>
+</div>
+```
+
+### Callback onOpenChange
+
+```tsx
+function PopoverTrackingExample() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  return (
+    <div>
+      <ColorPicker
+        onOpenChange={setIsOpen}
+        placeholder="Track popover state"
+      />
+      <p>Popover is {isOpen ? "open" : "closed"}</p>
+    </div>
+  )
+}
+```
+
+### Responsivo
+
+```tsx
+<ColorPicker
+  className="w-full sm:w-64"
+  placeholder="Responsive width"
+/>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// ColorPicker.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { ColorPicker } from "./ColorPicker"
+
+describe("ColorPicker", () => {
+  it("renders with placeholder", () => {
+    render(<ColorPicker placeholder="Pick a color" />)
+    expect(screen.getByRole("combobox")).toHaveTextContent("Pick a color")
+  })
+
+  it("renders with default value", () => {
+    render(<ColorPicker defaultValue="#ff0000" />)
+    expect(screen.getByRole("combobox")).toHaveTextContent("#ff0000")
+  })
+
+  it("shows preview swatch when value is set", () => {
+    render(<ColorPicker defaultValue="#3b82f6" />)
+    const preview = document.querySelector('[data-slot="color-picker-preview"]')
+    expect(preview).toHaveStyle({ backgroundColor: "#3b82f6" })
+  })
+
+  it("applies variant classes", () => {
+    render(<ColorPicker variant="filled" />)
+    expect(screen.getByRole("combobox")).toHaveClass("bg-muted")
+  })
+
+  it("applies size classes", () => {
+    render(<ColorPicker size="lg" />)
+    expect(screen.getByRole("combobox")).toHaveClass("h-10")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<ColorPicker />)
+    expect(document.querySelector('[data-slot="color-picker"]')).toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("ColorPicker interactions", () => {
+  it("opens popover on click", async () => {
+    const user = userEvent.setup()
+    render(<ColorPicker />)
+
+    await user.click(screen.getByRole("combobox"))
+
+    expect(document.querySelector('[data-slot="color-picker-content"]')).toBeInTheDocument()
+  })
+
+  it("calls onChange when swatch is clicked", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<ColorPicker onChange={handleChange} swatches={["#ff0000", "#00ff00"]} />)
+
+    await user.click(screen.getByRole("combobox"))
+    await user.click(screen.getByLabelText("Select color #ff0000"))
+
+    expect(handleChange).toHaveBeenCalledWith("#ff0000")
+  })
+
+  it("calls onChange when hex input changes", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<ColorPicker onChange={handleChange} showInput />)
+
+    await user.click(screen.getByRole("combobox"))
+    const input = screen.getByLabelText("Hex color value")
+    await user.clear(input)
+    await user.type(input, "#abcdef")
+
+    expect(handleChange).toHaveBeenCalledWith("#abcdef")
+  })
+
+  it("calls onOpenChange when popover state changes", async () => {
+    const user = userEvent.setup()
+    const handleOpenChange = vi.fn()
+
+    render(<ColorPicker onOpenChange={handleOpenChange} />)
+
+    await user.click(screen.getByRole("combobox"))
+    expect(handleOpenChange).toHaveBeenCalledWith(true)
+  })
+
+  it("does not open when disabled", async () => {
+    const user = userEvent.setup()
+    render(<ColorPicker disabled />)
+
+    await user.click(screen.getByRole("combobox"))
+
+    expect(document.querySelector('[data-slot="color-picker-content"]')).not.toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("ColorPicker accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<ColorPicker />)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has correct aria attributes on trigger", () => {
+    render(<ColorPicker required invalid />)
+    const trigger = screen.getByRole("combobox")
+
+    expect(trigger).toHaveAttribute("aria-expanded", "false")
+    expect(trigger).toHaveAttribute("aria-haspopup", "dialog")
+    expect(trigger).toHaveAttribute("aria-required", "true")
+    expect(trigger).toHaveAttribute("aria-invalid", "true")
+  })
+
+  it("swatches have correct aria-pressed", async () => {
+    const user = userEvent.setup()
+    render(<ColorPicker defaultValue="#ef4444" swatches={["#ef4444", "#3b82f6"]} />)
+
+    await user.click(screen.getByRole("combobox"))
+
+    expect(screen.getByLabelText("Select color #ef4444")).toHaveAttribute("aria-pressed", "true")
+    expect(screen.getByLabelText("Select color #3b82f6")).toHaveAttribute("aria-pressed", "false")
+  })
+
+  it("is keyboard navigable", async () => {
+    const user = userEvent.setup()
+    render(<ColorPicker />)
+
+    const trigger = screen.getByRole("combobox")
+    trigger.focus()
+    expect(trigger).toHaveFocus()
+
+    await user.keyboard("{Enter}")
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "true")
+  })
+})
+```
+
+### Testes de Validacao Hex
+
+```tsx
+describe("ColorPicker hex validation", () => {
+  it("normalizes 3-digit hex to 6-digit", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<ColorPicker onChange={handleChange} />)
+
+    await user.click(screen.getByRole("combobox"))
+    const input = screen.getByLabelText("Hex color value")
+    await user.type(input, "#abc")
+    await user.tab() // Trigger blur
+
+    expect(handleChange).toHaveBeenCalledWith("#aabbcc")
+  })
+
+  it("auto-prepends # when typing hex without it", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<ColorPicker onChange={handleChange} />)
+
+    await user.click(screen.getByRole("combobox"))
+    const input = screen.getByLabelText("Hex color value")
+    await user.type(input, "ff0000")
+
+    expect(handleChange).toHaveBeenCalledWith("#ff0000")
+  })
+
+  it("resets input to current color on invalid input blur", async () => {
+    const user = userEvent.setup()
+
+    render(<ColorPicker defaultValue="#ff0000" />)
+
+    await user.click(screen.getByRole("combobox"))
+    const input = screen.getByLabelText("Hex color value")
+    await user.clear(input)
+    await user.type(input, "invalid")
+    await user.tab()
+
+    expect(input).toHaveValue("#ff0000")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com design systems de referencia:
+
+### Prioridade Alta
+
+#### Suporte a Alpha/Opacity
+
+Adicionar controle de transparencia.
+
+```tsx
+// Proposta de API
+interface ColorPickerProps {
+  showAlpha?: boolean
+  format?: "hex" | "hexa" | "rgb" | "rgba"
+}
+
+// Uso
+<ColorPicker showAlpha format="hexa" />
+// Valor: #ff000080
+```
+
+**Referencias:** Mantine, Chakra UI, PrimeReact
+
+#### Multiplos Formatos
+
+Suporte a RGB, HSL alem de HEX.
+
+```tsx
+// Proposta de API
+<ColorPicker format="rgb" />
+// onChange retorna: "rgb(255, 0, 0)"
+```
+
+**Referencias:** Mantine (`format`), AntD (`format`), PrimeReact
+
+### Prioridade Media
+
+#### Eyedropper
+
+Picker de cor direto da tela (quando suportado).
+
+```tsx
+// Proposta de API
+<ColorPicker showEyedropper />
+```
+
+**Referencias:** Mantine (usa EyeDropper API do browser)
+
+#### Gradiente/Slider Visual
+
+Adicionar area de gradiente para selecao visual.
+
+**Referencias:** React Color (Chrome/Sketch pickers), Chakra UI
+
+#### Clear Button
+
+Botao para limpar a cor selecionada.
+
+```tsx
+// Proposta de API
+<ColorPicker clearable onClear={() => {}} />
+```
+
+**Referencias:** Mantine, AntD
+
+### Prioridade Baixa
+
+#### Recent Colors
+
+Historico de cores utilizadas recentemente.
+
+```tsx
+// Proposta de API
+<ColorPicker showRecentColors maxRecentColors={5} />
+```
+
+**Referencias:** MS Office color pickers
+
+#### Color Name Display
+
+Exibir nome da cor quando reconhecida.
+
+```tsx
+// Proposta
+<ColorPicker showColorName />
+// Exibe: "Red" para #ff0000
+```
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| Alpha/Opacity | Implementar | Alta demanda para UIs complexas |
+| Formatos RGB/HSL | Implementar | Flexibilidade para diferentes casos |
+| Eyedropper | Avaliar | Depende de suporte do browser |
+| Gradiente visual | Considerar | Aumenta complexidade significativamente |
+| Clear button | Implementar | Simples e util |
+| Recent colors | Opcional | Nice-to-have, armazenamento local |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao ColorPicker | GitHub |
+|---------------|-------------------------|--------|
+| **Chakra UI** | [ColorPicker](https://www.chakra-ui.com/docs/components/color-picker) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Mantine** | [ColorPicker](https://mantine.dev/core/color-picker/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [ColorPicker](https://ant.design/components/color-picker) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **PrimeReact** | [ColorPicker](https://primereact.org/colorpicker/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **Fluent UI** | [ColorPicker](https://react.fluentui.dev/?path=/docs/components-colorpicker--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [ColorPicker](https://carbondesignsystem.com/components/color-picker/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **React Color** | [Docs](https://casesandberg.github.io/react-color/) | [casesandberg/react-color](https://github.com/casesandberg/react-color) |
+| **Radix UI** | [Popover](https://www.radix-ui.com/primitives/docs/components/popover) (base) | [radix-ui/primitives](https://github.com/radix-ui/primitives) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - Color Input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color)
+- [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix Popover](https://www.radix-ui.com/primitives/docs/components/popover)
+- [Lucide Icons](https://lucide.dev/icons/)