Cores Interativas

Escolha de cor por área, controle deslizante, amostra e seletor em célula, usados na personalização da Marca.

Quatro peças formam o conjunto de cores interativas do Admin: ColorArea (saturação e brilho num quadro), ColorSlider (um canal por vez), ColorSwatch (a amostra) e CellColorPicker (a célula que abre o seletor num popover). A página de Marca junta as quatro para a pessoa escolher a cor da loja. As três primeiras vêm do HeroUI v3 e o CellColorPicker do Pro; todas passam pela fachada @rastreio-x/ui, junto com parseColor.

import {
  CellColorPicker,
  ColorArea,
  ColorSlider,
  ColorSwatch,
  parseColor,
} from "@rastreio-x/ui";

Área de cor

ColorArea mapeia dois canais nos eixos X e Y. No modelo hsb, o par usual é saturação e brilho; o matiz vem de um ColorSlider. O onChange entrega um objeto Color; use color.toString("hex") para gravar.

#002FFF

Controle deslizante

ColorSlider ajusta um canal (hue, saturation, brightness e outros). A trilha mostra o degradê do canal e o Thumb a posição. Sempre dê um aria-label com o nome do canal.

Amostra

ColorSwatch mostra uma cor, em cinco tamanhos (xs a xl) e dois formatos (circle e square). aria-label e colorName dão o nome da cor para leitores de tela.

Seletor em célula

CellColorPicker é uma linha com rótulo, valor e amostra que abre um popover. O conteúdo do popover é livre, e quase sempre é uma ColorArea com um ColorSlider. variant="secondary" usa o fundo secundário da superfície.

No Admin

Na página de Marca, o campo de cor é um TextField com o hex e um CellColorPicker com a área e o matiz. Aqui, o seletor completo.

Anatomia

CellColorPicker
├── CellColorPicker.Label
├── CellColorPicker.Popover
├── CellColorPicker.Swatch
├── CellColorPicker.Trigger
└── CellColorPicker.ValueDisplay

Peça	Partes
`ColorArea`	`ColorArea`, `ColorArea.Thumb`
`ColorSlider`	`ColorSlider`, `.Track`, `.Thumb`, `.Output`
`ColorSwatch`	`ColorSwatch`
`CellColorPicker`	`CellColorPicker`, `.Trigger`, `.Label`, `.ValueDisplay`, `.Swatch`, `.Popover`

Propriedades

Área de cor (ColorArea):

ColorArea
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<ColorAreaRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ColorAreaRenderProps>`	`'react-aria-ColorArea'`	Classes CSS aplicadas ao elemento.
`colorSpace`	`ColorSpace`	-	The color space that the color area operates in. The `xChannel` and `yChannel` must be in this color space. If not provided, this defaults to the color space of the `color` or `defaultColor` value.
`defaultValue`	`string \| Color`	-	Valor inicial, para uso não controlado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`onChange`	`((value: Color) => void)`	-	Chamada quando o valor ou a seleção muda.
`onChangeEnd`	`((value: Color) => void)`	-	Chamada quando a pessoa termina de arrastar.
`render`	`DOMRenderFunction<'div', ColorAreaRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`showDots`	`boolean`	-	Mostra pontos de referência sobre a área de cor.
`style`	`StyleOrFunction<ColorAreaRenderProps>`	-	Estilos em linha aplicados ao elemento.
`value`	`string \| Color`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`xChannel`	`ColorChannel`	-	Color channel for the horizontal axis.
`xName`	`string`	-	The name of the x channel input element, used when submitting an HTML form. See MDN.
`yChannel`	`ColorChannel`	-	Color channel for the vertical axis.
`yName`	`string`	-	The name of the y channel input element, used when submitting an HTML form. See MDN.

Controle deslizante (ColorSlider):

ColorSlider
Prop	Tipo	Padrão	Descrição
`channel`*	`'hue' \| 'saturation' \| 'brightness' \| 'lightness' \| 'red' \| 'green' \| 'blue' \|…`	-	Canal de cor que o controle ajusta (por exemplo, `hue`, `saturation` ou `red`).
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`children`	`ChildrenOrFunction<ColorSliderRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ColorSliderRenderProps>`	`'react-aria-ColorSlider'`	Classes CSS aplicadas ao elemento.
`colorSpace`	`ColorSpace`	-	Espaço de cor em que o canal é interpretado.
`defaultValue`	`string \| Color`	-	Valor inicial, para uso não controlado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: Color) => void)`	-	Chamada quando o valor ou a seleção muda.
`onChangeEnd`	`((value: Color) => void)`	-	Chamada quando a pessoa termina de arrastar.
`orientation`	`Orientation`	`'horizontal'`	Orientação do componente: `horizontal` ou `vertical`.
`render`	`DOMRenderFunction<'div', ColorSliderRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<ColorSliderRenderProps>`	-	Estilos em linha aplicados ao elemento.
`value`	`string \| Color`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.

Amostra (ColorSwatch):

ColorSwatch
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`className`	`ClassNameOrFunction<ColorSwatchRenderProps>`	`'react-aria-ColorSwatch'`	Classes CSS aplicadas ao elemento.
`color`	`string \| Color`	-	The color value to display in the swatch.
`colorName`	`string`	-	A localized accessible name for the color. By default, a description is generated from the color value, but this can be overridden if you have a more specific color name (e.g. Pantone colors).
`id`	`string`	-	Identificador único do elemento.
`render`	`DOMRenderFunction<'div', ColorSwatchRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`shape`	`'circle' \| 'square'`	-	Formato da amostra: `circle` ou `square`.
`size`	`'lg' \| 'md' \| 'sm' \| 'xs' \| 'xl'`	-	Tamanho do componente.
`style`	`StyleOrFunction<ColorSwatchRenderProps>`	-	Estilos em linha aplicados ao elemento.

Seletor em célula (CellColorPicker):

CellColorPicker
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`defaultValue`	`string \| Color`	-	Valor inicial, para uso não controlado.
`onChange`	`((value: Color) => void)`	-	Chamada quando o valor ou a seleção muda.
`value`	`string \| Color`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'secondary' \| 'default'`	`"default"`	Variante visual do componente.

Gatilho (CellColorPicker.Trigger):

CellColorPicker.Trigger
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<ButtonRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ButtonRenderProps>`	`'react-aria-Button'`	Classes CSS aplicadas ao elemento.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`formAction`	`string \| ((formData: FormData) => void \| Promise<void>)`	-	URL ou função que processa o envio; sobrescreve a ação do formulário.
`formEncType`	`string`	-	Codificação dos dados enviados pelo formulário.
`formMethod`	`string`	-	Método HTTP do envio do formulário.
`formNoValidate`	`boolean`	-	Desativa a validação nativa do formulário no envio.
`formTarget`	`string`	-	Janela de destino do envio; sobrescreve a do formulário.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isPending`	`boolean`	-	Estado de carregamento: bloqueia novos cliques, mantém o foco e anuncia o estado a leitores de tela.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`preventFocusOnPress`	`boolean`	-	Impede que o foco vá para o elemento ao pressioná-lo. Pode prejudicar a acessibilidade.
`render`	`DOMRenderFunction<'button', ButtonRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<ButtonRenderProps>`	-	Estilos em linha aplicados ao elemento.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	Tipo do elemento; define o comportamento nativo (em botões, `button`, `submit` ou `reset`).
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.

Popover (CellColorPicker.Popover):

CellColorPicker.Popover
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`arrowBoundaryOffset`	`number`	`0`	Distância mínima entre a borda da seta e a borda da camada.
`arrowRef`	`RefObject<Element \| null>`	-	Referência ao elemento da seta.
`boundaryElement`	`Element`	`document.body`	Elemento que serve de limite para o posicionamento.
`className`	`ClassNameOrFunction<PopoverRenderProps>`	`'react-aria-Popover'`	Classes CSS aplicadas ao elemento.
`containerPadding`	`number`	`12`	Espaço mínimo entre a camada e a borda do contêiner.
`crossOffset`	`number`	`0`	Deslocamento adicional no eixo transversal entre a camada e o âncora.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`getTargetRect`	`((target: Element) => DOMRect \| null \| undefined)`	`target.getBoundingClientRect()`	Substitui o retângulo do alvo; útil para posicionar em relação a um ponto.
`isEntering`	`boolean`	-	Indica que a animação de entrada está em andamento.
`isExiting`	`boolean`	-	Indica que a animação de saída está em andamento.
`isKeyboardDismissDisabled`	`boolean`	`false`	Impede que a tecla Esc feche a camada.
`isNonModal`	`boolean`	-	Camada não modal: elementos fora dela continuam acessíveis a tecnologias assistivas.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`maxHeight`	`number`	-	Altura máxima da camada; por padrão ocupa o espaço disponível na janela.
`offset`	`number`	`8`	Deslocamento adicional no eixo principal entre a camada e o âncora.
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`placement`	`Placement`	`'bottom'`	Lado ou posição em que o elemento aparece.
`render`	`DOMRenderFunction<'div', PopoverRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	Referência à região rolável da camada.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	-	Decide se uma interação fora da camada a fecha.
`shouldFlip`	`boolean`	`true`	Inverte o lado quando não há espaço suficiente.
`shouldSkipAnimation`	`boolean`	-	Mostra e esconde sem animação de entrada ou saída.
`shouldUpdatePosition`	`boolean`	`true`	Atualiza a posição automaticamente ao rolar ou redimensionar.
`style`	`StyleOrFunction<PopoverRenderProps>`	-	Estilos em linha aplicados ao elemento.
`trigger`	`string`	-	Nome do componente que abriu a camada (exposto em `data-trigger`).
`triggerRef`	`RefObject<Element \| null>`	-	Referência ao elemento a que a camada se posiciona.
`UNSTABLE_portalContainer`	`Element`	`document.body`	Elemento que recebe o portal da camada. Interface instável.

Animações

CSS
indicativo

O polegar acompanha o ponteiro sem animação própria, e o anel de foco aparece só com o teclado. O popover do CellColorPicker tem transição de entrada e saída herdada do HeroUI. O selo acima é indicativo (análise estática de CSS dos pacotes). A folha global da fachada reduz transições CSS a 0,01 ms com prefers-reduced-motion; o arraste não depende de animação e continua igual.

Acessibilidade

ColorArea e ColorSlider são controles do React Aria: setas movem o polegar, PageUp e PageDown dão passos maiores, Home e End vão aos extremos.
A área de cor expõe dois sliders (um por eixo), cada um com o valor em texto; mantenha aria-label descritivo ("Saturação e brilho").
A cor nunca é a única informação: o CellColorPicker.ValueDisplay mostra o hex, e o campo de texto ao lado aceita o valor digitado.
Verifique o contraste do texto sobre a cor escolhida antes de aplicar: a Marca calcula o contraste por tema e ajusta o tom quando preciso.

Boas práticas

Faça

Oferecer o campo de hex junto do seletor, e mostrar o valor escolhido em texto.

Evite

Um seletor visual sozinho, sem como digitar a cor nem ver o valor.

Una ColorArea (saturação e brilho) a um ColorSlider de matiz: é o conjunto mais familiar.
Dê o nome da cor ao ColorSwatch (aria-label ou colorName).
Use CellColorPicker quando o espaço é de formulário; use ColorArea solta só em telas dedicadas à cor.
Não use cor para representar estado; as cores do seletor são da Marca, não do sistema.

Relacionados

TextField para o campo do hex.
Slider para sliders que não são de cor.
Tooltip para explicar a cor escolhida.