@iclips/ui 2.0.3 → 3.1.0

package/dist/tokens.css

@@ -11,8 +11,9 @@
 :root {
   --font-size: 16px;
   
-  /* Custom Color Palette - Base Colors */
-  /* Grays */
+  /* Paleta iClips — só o que algum token semântico usa. Primitivos não viram
+     classe (o @theme só mapeia semânticos): escreva bg-primary, nunca bg-purple-500 (check-colors-ignore). */
+  /* Neutros — estrutura */
   --gray-50: #F2F6FA;
   --gray-100: #E9EEF5;
   --gray-200: #DAE1EB;
@@ -24,79 +25,23 @@
   --gray-800: #1A1F26;
   --gray-900: #000000;
   --white: #FFFFFF;
-  
-  /* Purple (Primary Brand Color) */
+
+  /* Roxo — ação (exclusivo) */
   --purple-50: #F6E9FF;
   --purple-100: #DAA6FF;
   --purple-200: #BB6DF2;
+  --purple-300: #A855E0;
+  --purple-400: #913DD0;
   --purple-500: #7F26BF;
-  --purple-600: #5B158C;
   --purple-700: #420F66;
-  
-  /* Blue */
-  --blue-50: #E2E9FF;
-  --blue-100: #AABCF2;
-  --blue-200: #667FCC;
-  --blue-500: #1C2F8C;
-  --blue-600: #0F1E66;
-  --blue-700: #061040;
-  
-  /* Cyan */
-  --cyan-50: #D8EFFF;
-  --cyan-100: #8CCFFF;
-  --cyan-200: #3DA7F2;
-  --cyan-500: #0086E6;
-  --cyan-600: #0053A6;
-  --cyan-700: #003066;
-  
-  /* Teal */
-  --teal-50: #D4F5F5;
-  --teal-100: #9DF2F2;
-  --teal-200: #5CE6E6;
-  --teal-500: #14CCCC;
-  --teal-600: #00A7A7;
-  --teal-700: #045659;
-  
-  /* Green */
-  --green-50: #D3FBDD;
-  --green-100: #91F2AA;
-  --green-200: #57D977;
-  --green-500: #24B347;
-  --green-600: #007F2A;
-  --green-700: #004D19;
-  
-  /* Yellow */
-  --yellow-50: #FFF7CC;
-  --yellow-100: #FFDD99;
-  --yellow-200: #FFC859;
-  --yellow-500: #FAB325;
-  --yellow-600: #E6960B;
-  --yellow-700: #CC7C04;
-  
-  /* Orange */
-  --orange-50: #FFECE1;
-  --orange-100: #FFB68C;
-  --orange-200: #FF8E4C;
-  --orange-500: #F26924;
-  --orange-600: #E64D0B;
-  --orange-700: #BF3000;
-  
-  /* Red */
-  --red-50: #FFE9EC;
-  --red-100: #FFB2B9;
-  --red-200: #FF5967;
-  --red-500: #F22435;
-  --red-600: #CC0A1A;
-  --red-700: #99000D;
-  
-  /* Pink */
-  --pink-50: #FFECF9;
-  --pink-100: #FFB2E8;
-  --pink-200: #FF66CC;
-  --pink-500: #E62EA8;
-  --pink-600: #BF0A89;
-  --pink-700: #99086D;
-  
+
+  /* Estado — feedback, nunca decoração */
+  --red-600: #AB4A43;
+  --green-600: #427748;
+  --yellow-500: #E4BB78;
+  --yellow-600: #CFA066;
+  --cyan-600: #315687;
+
   /* Semantic Colors - Light Mode */
   --background: var(--white);
   --foreground: var(--gray-800);
@@ -112,8 +57,8 @@
   /* gray-600 (não gray-500): passa AA também sobre `bg-muted`/`bg-accent`
      (gray-500 dava ~4:1 sobre gray-100). No dark segue gray-300. */
   --muted-foreground: var(--gray-600);
-  --accent: var(--purple-50);
-  --accent-foreground: var(--purple-600);
+  --accent: var(--gray-100);
+  --accent-foreground: var(--foreground);
   --destructive: var(--red-600);
   --destructive-foreground: var(--white);
   --success: var(--green-600);
@@ -156,13 +101,13 @@
   
   /* Charts - Acessibilidade melhorada com Balanceamento Óptico */
   --chart-1: var(--purple-500); /* Brand Color (Vibrante) */
-  --chart-2: var(--cyan-600);   /* Darkened for contrast */
-  --chart-3: var(--green-600);  /* Darkened for contrast */
-  --chart-4: var(--orange-600); /* Darkened for contrast */
-  --chart-5: var(--pink-600);   /* Darkened for contrast */
-  --chart-6: var(--blue-600);   /* Darkened for contrast */
-  --chart-7: var(--teal-600);   /* Darkened for contrast */
-  --chart-8: var(--yellow-600); /* Darkened for contrast */
+  --chart-2: var(--gray-400);   /* 500: separa de chart-1 em luminância */
+  --chart-3: var(--purple-700);  /* Darkened for contrast */
+  --chart-4: var(--purple-200); /* Darkened for contrast */
+  --chart-5: var(--gray-600);   /* Darkened for contrast */
+  --chart-6: var(--purple-100);   /* 200: separa de chart-2 (eram dois azul-marinho) */
+  --chart-7: var(--gray-700);   /* Darkened for contrast */
+  --chart-8: var(--purple-300); /* Darkened for contrast */
 
   /* Border Radius */
   --radius: 0.625rem;
@@ -172,8 +117,10 @@
   --sidebar-foreground: var(--gray-800);
   --sidebar-primary: var(--purple-500);
   --sidebar-primary-foreground: var(--white);
-  --sidebar-accent: var(--purple-50);
-  --sidebar-accent-foreground: var(--purple-700);
+  --sidebar-accent: var(--gray-100);
+  --sidebar-accent-foreground: var(--sidebar-foreground);
+  --sidebar-selected: var(--purple-50);
+  --sidebar-selected-foreground: var(--purple-700);
   --sidebar-border: var(--gray-200);
   --sidebar-ring: var(--purple-500);
 
@@ -229,14 +176,14 @@
   --card-foreground: var(--gray-50);
   --popover: var(--gray-700);
   --popover-foreground: var(--gray-50);
-  --primary: var(--purple-200);
+  --primary: var(--purple-100);
   --primary-foreground: var(--gray-900);
-  --secondary: var(--gray-700);
-  --secondary-foreground: var(--gray-50);
+  --secondary: var(--purple-700);
+  --secondary-foreground: var(--purple-100);
   --muted: var(--gray-600);
   --muted-foreground: var(--gray-300);
-  --accent: var(--purple-700);
-  --accent-foreground: var(--purple-100);
+  --accent: var(--gray-600);
+  --accent-foreground: var(--gray-50);
   --destructive: var(--red-600);
   --destructive-foreground: var(--white);
   --success: var(--green-600);
@@ -245,6 +192,15 @@
   --warning-foreground: var(--gray-800);
   --info: var(--cyan-600);
   --info-foreground: var(--white);
+  /* Redeclarados aqui porque var() dentro de custom property resolve onde é
+     declarada: sem isso, um .dark que não esteja no <html> herda a mistura do
+     :root, feita com o --foreground claro. 80% também não passa AA sobre
+     popover/card escuros; 45% passa até sobre o tint de foco (bg-<token>/20).
+     warning mantém 32%, que já passa. */
+  --success-emphasis:     color-mix(in oklab, var(--success) 45%, var(--foreground));
+  --info-emphasis:        color-mix(in oklab, var(--info) 45%, var(--foreground));
+  --destructive-emphasis: color-mix(in oklab, var(--destructive) 45%, var(--foreground));
+  --warning-emphasis:     color-mix(in oklab, var(--warning) 32%, var(--foreground));
   --border: var(--gray-600);
   --input: var(--gray-600);
   --input-background: var(--gray-700);
@@ -253,13 +209,13 @@
   
   /* Charts - Dark Mode */
   --chart-1: var(--purple-200);
-  --chart-2: var(--cyan-200);
-  --chart-3: var(--green-200);
-  --chart-4: var(--orange-200);
-  --chart-5: var(--pink-200);
-  --chart-6: var(--blue-200);
-  --chart-7: var(--teal-200);
-  --chart-8: var(--yellow-200);
+  --chart-2: var(--gray-50);
+  --chart-3: var(--purple-300);
+  --chart-4: var(--purple-50);
+  --chart-5: var(--purple-400);
+  --chart-6: var(--gray-100);
+  --chart-7: var(--gray-500);
+  --chart-8: var(--gray-200);
 
   /* Sidebar - Dark Mode */
   --sidebar: var(--gray-800);
@@ -267,7 +223,9 @@
   --sidebar-primary: var(--purple-200);
   --sidebar-primary-foreground: var(--gray-900);
   --sidebar-accent: var(--gray-700);
-  --sidebar-accent-foreground: var(--purple-100);
+  --sidebar-accent-foreground: var(--gray-50);
+  --sidebar-selected: var(--purple-700);
+  --sidebar-selected-foreground: var(--purple-100);
   --sidebar-border: var(--gray-600);
   --sidebar-ring: var(--purple-200);
 }
@@ -299,6 +257,11 @@
 }
 
 @theme inline {
+  --color-*: initial;
+  /* ↑ só tokens semânticos viram classe: zera a paleta padrão do Tailwind. */
+  --color-white: #FFFFFF;
+  --color-black: #000000;
+
   /* Typography */
   --font-sans: var(--font-sans);
 
@@ -358,6 +321,8 @@
   --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
   --color-sidebar-accent: var(--sidebar-accent);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-selected: var(--sidebar-selected);
+  --color-sidebar-selected-foreground: var(--sidebar-selected-foreground);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-ring: var(--sidebar-ring);
 
@@ -403,69 +368,4 @@
   --spacing-inline-sm:  var(--space-inline-sm);
   --spacing-inline-md:  var(--space-inline-md);
   --spacing-inline-lg:  var(--space-inline-lg);
-
-  /* Raw Color Palette */
-  --color-gray-50: var(--gray-50);
-  --color-gray-100: var(--gray-100);
-  --color-gray-200: var(--gray-200);
-  --color-gray-300: var(--gray-300);
-  --color-gray-400: var(--gray-400);
-  --color-gray-500: var(--gray-500);
-  --color-gray-600: var(--gray-600);
-  --color-gray-700: var(--gray-700);
-  --color-gray-800: var(--gray-800);
-  --color-purple-50: var(--purple-50);
-  --color-purple-100: var(--purple-100);
-  --color-purple-200: var(--purple-200);
-  --color-purple-500: var(--purple-500);
-  --color-purple-600: var(--purple-600);
-  --color-purple-700: var(--purple-700);
-  --color-blue-50: var(--blue-50);
-  --color-blue-100: var(--blue-100);
-  --color-blue-200: var(--blue-200);
-  --color-blue-500: var(--blue-500);
-  --color-blue-600: var(--blue-600);
-  --color-blue-700: var(--blue-700);
-  --color-cyan-50: var(--cyan-50);
-  --color-cyan-100: var(--cyan-100);
-  --color-cyan-200: var(--cyan-200);
-  --color-cyan-500: var(--cyan-500);
-  --color-cyan-600: var(--cyan-600);
-  --color-cyan-700: var(--cyan-700);
-  --color-teal-50: var(--teal-50);
-  --color-teal-100: var(--teal-100);
-  --color-teal-200: var(--teal-200);
-  --color-teal-500: var(--teal-500);
-  --color-teal-600: var(--teal-600);
-  --color-teal-700: var(--teal-700);
-  --color-green-50: var(--green-50);
-  --color-green-100: var(--green-100);
-  --color-green-200: var(--green-200);
-  --color-green-500: var(--green-500);
-  --color-green-600: var(--green-600);
-  --color-green-700: var(--green-700);
-  --color-yellow-50: var(--yellow-50);
-  --color-yellow-100: var(--yellow-100);
-  --color-yellow-200: var(--yellow-200);
-  --color-yellow-500: var(--yellow-500);
-  --color-yellow-600: var(--yellow-600);
-  --color-yellow-700: var(--yellow-700);
-  --color-orange-50: var(--orange-50);
-  --color-orange-100: var(--orange-100);
-  --color-orange-200: var(--orange-200);
-  --color-orange-500: var(--orange-500);
-  --color-orange-600: var(--orange-600);
-  --color-orange-700: var(--orange-700);
-  --color-red-50: var(--red-50);
-  --color-red-100: var(--red-100);
-  --color-red-200: var(--red-200);
-  --color-red-500: var(--red-500);
-  --color-red-600: var(--red-600);
-  --color-red-700: var(--red-700);
-  --color-pink-50: var(--pink-50);
-  --color-pink-100: var(--pink-100);
-  --color-pink-200: var(--pink-200);
-  --color-pink-500: var(--pink-500);
-  --color-pink-600: var(--pink-600);
-  --color-pink-700: var(--pink-700);
 }

package/docs/README.md

@@ -0,0 +1,44 @@
+# @iclips/ui — como usar
+
+Leia isto antes de montar uma tela com a `@iclips/ui`. Os guias abaixo dizem **qual componente usar em cada situação** e trazem código pronto para copiar. Eles vêm no pacote, então descrevem exatamente a versão instalada.
+
+Todo import vem do barrel: `import { Button } from "@iclips/ui"`. Os componentes de edição rica (`DocumentEditor`, `CommentSystem`, `EditorialCalendar`, `MentionList`) vêm de `@iclips/ui/editor`. Importe `@iclips/ui/styles.css` uma vez na raiz do app.
+
+## Guias
+
+- [Ações e navegação](acoes.md) — botão, link ou ícone; hierarquia de variantes.
+- [Escolha em lista](escolha.md) — Select, Combobox, RadioGroup, Checkbox, Switch, ToggleGroup.
+- [Formulários](formularios.md) — anatomia do campo, validação, layout, react-hook-form.
+- [Mensagens ao usuário](mensagens.md) — erro de campo, Alert, Toast, AlertDialog.
+- [Overlays](overlays.md) — Tooltip, HoverCard, Popover, Dialog, AlertDialog, Sheet, Drawer.
+- [Status](status.md) — badge de status, valor positivo/negativo.
+- [Linguagem visual](../DESIGN.md) — as quatro camadas de cor, tipografia, raio, botões e superfícies.
+
+## Troque isto por aquilo
+
+As classes cruas da paleta do Tailwind **não geram CSS** na `@iclips/ui` 3.x: o elemento fica sem cor, em silêncio. Use o token semântico ou o componente.
+
+| Em vez de | Use |
+| --- | --- |
+| `text-gray-500` | `text-muted-foreground` |
+| `text-gray-600` | `text-muted-foreground` |
+| `text-gray-900` | `text-foreground` |
+| `border-gray-200` | `border-border` |
+| `border-gray-300` | `border-input` |
+| `text-red-500` | `text-destructive-emphasis` |
+| `text-green-500` | `text-success-emphasis` |
+| `bg-green-50` | `Badge` ou `Alert` com `variant="success"` — ver [Status](status.md) |
+| `bg-orange-100` | `Badge` ou `Alert` com `variant="warning"` — ver [Status](status.md) |
+| `<button>` | `Button` — ver [Ações](acoes.md) |
+| `<input>` | `Input` (ou `NumberInput`, `CurrencyInput`, `DatePicker`, `PasswordInput`) |
+| `<select>` | `Select` (ou `Combobox` para lista longa) — ver [Escolha](escolha.md) |
+
+Para achar cor crua no app: `node node_modules/@iclips/ui/scripts/check-colors.mjs src`.
+
+## Quando não houver guia
+
+1. Procure o componente no barrel antes de montar um na mão. Elemento HTML cru (`<button>`, `<input>`, `<select>`, `<div onClick>`) quase sempre tem equivalente.
+2. Cor sempre por token semântico: `bg-background`, `bg-card`, `bg-muted`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`. Nunca cor crua da paleta.
+3. Espaçamento e tamanho pela escala (`gap-4`, `p-6`, `max-w-sm`). Nunca valor arbitrário (`p-[13px]`) nem `style={{}}` com valor literal.
+4. Ícones de `lucide-react`.
+5. Estado (erro, sucesso, aviso, informação) segue a receita suave: `bg-<status>/10 text-<status>-emphasis border-<status>/20` — de preferência pelo componente que já a aplica (`Badge`, `Alert`, `Button`).

package/docs/acoes.md

@@ -0,0 +1,103 @@
+# Botão, link ou ícone
+
+A regra de ouro: **link leva a algum lugar** (muda a URL), **botão faz alguma coisa** (dispara uma ação na página). Escolher errado quebra abrir-em-nova-aba, o botão voltar e o leitor de tela.
+
+## Elemento certo
+
+| Elemento | Escolha quando | Evite quando |
+| --- | --- | --- |
+| `<a>` / `<Link>` | o clique navega para outra rota, âncora ou recurso externo. Suporta Ctrl+clique, botão do meio, "copiar link". | o clique só muda estado na tela (abrir modal, submeter, alternar) → `<button>`. |
+| `Button` | dispara uma ação: salvar, abrir overlay, adicionar item, filtrar. É o padrão para quase tudo que não é navegação. | o destino é uma URL → renderize um link (use `asChild`). |
+| `Button variant="link"` | uma ação secundária que precisa parecer texto ("Esqueci a senha", "ver todos") dentro de um parágrafo ou rodapé. | é a ação principal do bloco → `default`/`secondary`. É navegação de verdade → `<a>` estilizado. |
+| `Button size="icon"` | ação repetida numa linha/toolbar onde o texto polui (excluir linha, favoritar). Sempre com `aria-label`. | a ação é rara ou ambígua — aí o texto ajuda. Ou é a ação primária de um formulário. |
+| `SocialButton` | login/conexão com provedor (Google, Facebook…) — já traz ícone e rótulo do provedor. | qualquer outra ação. |
+
+## Hierarquia de variantes
+
+Uma ação primária por bloco. O resto desce na escala.
+
+### Ordem de ênfase
+
+Rótulo em peso 600 (semibold) — no sistema, 600 significa ação. Hover de `outline` e `ghost` é cinza; lavanda fica para selecionado.
+
+```tsx
+import { Button } from "@iclips/ui";
+
+<Button>Primária — salvar, confirmar, criar</Button>
+<Button variant="secondary">Secundária — ação alternativa</Button>
+<Button variant="outline">Terciária — cancelar, voltar</Button>
+<Button variant="ghost">Discreta — em toolbars, dentro de cards</Button>
+<Button variant="link">Link — ação textual inline</Button>
+```
+
+### Semânticas
+
+`destructive` só para remoção/irreversível. `success` é raro — normalmente o `default` basta.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { Trash2 } from "lucide-react";
+
+<Button variant="destructive"><Trash2 /> Excluir</Button>
+<Button variant="success">Aprovar</Button>
+```
+
+### Com ícone
+
+Ícone à esquerda reforça o verbo; à direita sugere avanço/navegação.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { ArrowRight, Download, Plus } from "lucide-react";
+
+<Button><Plus /> Nova campanha</Button>
+<Button variant="outline">Exportar <Download /></Button>
+<Button variant="link">Ver relatório <ArrowRight /></Button>
+```
+
+## Trilha rápida
+
+1. **O clique muda a URL / abre outra página?** Sim: é um link. Renderize `<a>` (ou `<Link>` do router) — via `Button asChild` se quiser o visual de botão. Não: continue.
+2. **É a ação principal deste bloco/formulário?** Sim: `Button variant="default"`. Não: continue.
+3. **Remove ou desfaz algo de forma difícil de reverter?** Sim: `variant="destructive"` + confirmação (ver [Overlays](overlays.md)). Não: continue.
+4. **Está numa linha de tabela / toolbar densa e o verbo é óbvio pelo ícone?** Sim: `size="icon"` + `aria-label`. Não: variant `secondary` / `outline` / `ghost` conforme a ênfase.
+
+## Link com aparência de botão
+
+Quando o destino é uma URL mas o design pede um botão, use `asChild` — o elemento vira `<a>`, o estilo continua.
+
+### asChild
+
+Renderiza `<a href>` com as classes do `Button`. Mantém Ctrl+clique e menu de contexto.
+
+```tsx
+import { Button } from "@iclips/ui";
+import { ArrowRight } from "lucide-react";
+
+<Button asChild>
+  <a href="/projetos/42">Abrir projeto</a>
+</Button>
+<Button asChild variant="outline">
+  <a href="https://iclips.com.br" target="_blank" rel="noreferrer">
+    Site da iClips <ArrowRight />
+  </a>
+</Button>
+```
+
+## Faça / evite
+
+#### Faça
+
+- Comece o rótulo com um verbo: "Salvar alterações", não "OK".
+- Toda ação só-ícone leva `aria-label` com o mesmo verbo que um Tooltip mostraria.
+- Use `isLoading` para travar o botão durante a requisição — ele já seta `aria-busy` e bloqueia o clique.
+- Um `<a>` para navegação mesmo que estilizado como botão — o usuário espera Ctrl+clique.
+
+#### Evite
+
+- `onClick={() => navigate("/rota")}` num `<button>` — quebra abrir em nova aba e o histórico.
+- Dois botões primários lado a lado — o olho não sabe qual é o caminho feliz.
+- `<div onClick>` — sem foco, sem Enter/Espaço, invisível para leitor de tela.
+- `variant="link"` para a ação principal de um formulário.
+
+**Acessibilidade:** o `Button` já traz anel de foco visível, `active:scale` e trata `disabled`. Um link precisa de `href` real para ser focável e anunciado como link — `role="button"` num `<a>` ou vice-versa confunde a tecnologia assistiva. Ícone sem texto *sempre* com `aria-label`.

package/docs/escolha.md

@@ -0,0 +1,171 @@
+# Como o usuário escolhe de uma lista
+
+Duas perguntas resolvem quase tudo: **uma opção ou várias?** e **quantas opções existem** — porque abaixo de ~7 vale mostrar todas, e acima disso é preciso busca.
+
+## Uma única escolha
+
+| Componente | Escolha quando | Evite quando |
+| --- | --- | --- |
+| RadioGroup | 2 a 5 opções que valem ser vistas todas de uma vez, e a escolha é importante (plano, forma de pagamento). | mais de ~6 opções, ou espaço vertical apertado → `Select`. |
+| Select | 6 a ~25 opções conhecidas e curtas (estado, categoria, status). Economiza espaço. | a lista é longa ou o usuário sabe o nome do que quer → `Combobox`. |
+| Combobox | lista longa (>25) ou dinâmica: cidade, cliente, produto. Filtra enquanto digita. | são poucas opções fixas — o campo de busca vira fricção → `Select` ou Radio. |
+| ToggleGroup (single) | 2 a 4 opções mutuamente exclusivas que mudam a visão na hora: alinhamento, período (dia/semana/mês), modo de exibição. | é um dado do formulário a ser submetido, não uma alternância de UI → Radio. |
+
+## Várias escolhas (ou liga/desliga)
+
+| Componente | Escolha quando | Evite quando |
+| --- | --- | --- |
+| Checkbox (grupo) | 2 a ~8 opções independentes visíveis de uma vez: permissões, dias da semana, filtros marcáveis. | a lista é longa → `MultiSelect`. É uma única opção booleana isolada → Checkbox sozinho ou `Switch`. |
+| MultiSelect | escolher vários de uma lista longa: responsáveis, tags, canais. Mostra chips do que foi escolhido + busca. | poucas opções fixas → grupo de Checkbox mostra tudo sem cliques extras. |
+| ToggleGroup (multiple) | conjunto pequeno de formatações/filtros que ligam e desligam juntos: negrito/itálico, tipos de mídia. | opções com rótulos longos, ou muitas → Checkbox. |
+| Checkbox (isolado) | uma afirmação que o usuário aceita ou não: "Aceito os termos", "Lembrar de mim". Faz parte de um envio. | liga um comportamento imediatamente, sem submit → `Switch`. |
+| Switch | liga/desliga uma configuração com efeito imediato: notificações, modo escuro, tema. | o efeito só acontece ao salvar o formulário → Checkbox. |
+
+## Trilha rápida
+
+1. **O usuário pode escolher mais de uma opção?** Sim: poucas e fixas → grupo de `Checkbox`; muitas/dinâmicas → `MultiSelect`. Não: continue.
+2. **É um liga/desliga com efeito imediato (sem salvar)?** Sim: `Switch`. Não: continue.
+3. **A escolha muda a visão da tela na hora (período, layout)?** Sim: `ToggleGroup type="single"`. Não: continue.
+4. **Quantas opções?** Até 5 e importantes → `RadioGroup` · 6 a 25 → `Select` · mais que isso ou dinâmica → `Combobox`.
+
+## Exemplos
+
+Os exemplos usam esta lista:
+
+```tsx
+const canais = [
+  { value: "ig", label: "Instagram" },
+  { value: "fb", label: "Facebook" },
+  { value: "li", label: "LinkedIn" },
+  { value: "tt", label: "TikTok" },
+  { value: "yt", label: "YouTube" },
+];
+```
+
+### RadioGroup — poucas, todas visíveis
+
+```tsx
+import { Label, RadioGroup, RadioGroupItem } from "@iclips/ui";
+
+<RadioGroup defaultValue="anual" className="gap-2">
+  {["mensal", "anual", "vitalício"].map((v) => (
+    <div key={v} className="flex items-center gap-2">
+      <RadioGroupItem value={v} id={`plano-${v}`} />
+      <Label htmlFor={`plano-${v}`} className="capitalize">{v}</Label>
+    </div>
+  ))}
+</RadioGroup>
+```
+
+### Select — lista média conhecida
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@iclips/ui";
+
+<Select>
+  <SelectTrigger className="w-56" aria-label="Canal"><SelectValue placeholder="Selecione o canal" /></SelectTrigger>
+  <SelectContent>
+    {canais.map((c) => (
+      <SelectItem key={c.value} value={c.value}>{c.label}</SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+### Combobox — busca em lista longa
+
+```tsx
+import { Combobox } from "@iclips/ui";
+
+const [canal, setCanal] = React.useState("");
+
+<Combobox options={canais} value={canal} onValueChange={setCanal} placeholder="Buscar canal" aria-label="Canal" />
+```
+
+### MultiSelect — vários, com chips
+
+```tsx
+import { MultiSelect } from "@iclips/ui";
+
+const [selecionados, setSelecionados] = React.useState<string[]>(["ig"]);
+
+<MultiSelect
+  options={canais}
+  value={selecionados}
+  onValueChange={setSelecionados}
+  placeholder="Canais da campanha"
+  aria-label="Canais da campanha"
+/>
+```
+
+### Checkbox (grupo) — independentes, visíveis
+
+```tsx
+import { Checkbox } from "@iclips/ui";
+
+<div className="space-y-2">
+  {["Ler", "Escrever", "Excluir"].map((p) => (
+    <label key={p} className="flex items-center gap-2 text-sm">
+      <Checkbox defaultChecked={p === "Ler"} /> {p}
+    </label>
+  ))}
+</div>
+```
+
+### Switch — efeito imediato
+
+Muda algo agora. Checkbox seria para um valor a ser salvo.
+
+```tsx
+import { Switch } from "@iclips/ui";
+
+<label className="flex items-center gap-2 text-sm">
+  <Switch defaultChecked /> Notificações por e-mail
+</label>
+```
+
+### ToggleGroup — troca de visão
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@iclips/ui";
+
+<ToggleGroup type="single" defaultValue="semana">
+  <ToggleGroupItem value="dia">Dia</ToggleGroupItem>
+  <ToggleGroupItem value="semana">Semana</ToggleGroupItem>
+  <ToggleGroupItem value="mes">Mês</ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Estados do item: selecionado > focado > sob o cursor
+
+Os três podem coexistir no mesmo item e cada um usa um sinal diferente, para continuarem legíveis empilhados. `Combobox` e `MultiSelect` já seguem essa regra; siga-a em listas próprias.
+
+| Estado | Como se pinta | Por quê |
+| --- | --- | --- |
+| Selecionado | `bg-secondary text-secondary-foreground font-medium` | matiz + tinta + peso: três sinais, sobrevive ao hover por cima. |
+| Focado por teclado | `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset` | anel, não fundo — sobrevive sobre qualquer fundo. |
+| Sob o cursor | `hover:bg-accent` | cinza, transitório, sem peso. |
+
+Hover e seleção são ambos `bg-*`: quem vence é a ordem do CSS gerado, não a do `className`. Guarde o hover pelo estado (`not-aria-selected:hover:bg-accent`) ou inclua `hover:bg-secondary` na classe de selecionado, para o `cn` descartar o hover conflitante.
+
+### Ilustração estática — os três estados na mesma lista
+
+Numa mesma lista, o item selecionado fica lavanda com peso maior, o focado ganha só o anel e o que está sob o cursor fica cinza — nunca lavanda, que significa selecionado.
+
+## Faça / evite
+
+#### Faça
+
+- Todo controle com `<Label htmlFor>` — clicar no texto ativa o controle.
+- `Combobox` e `MultiSelect` quando a lista vem da API ou passa de ~25 itens.
+- `RadioGroup` com um default sensato já selecionado (evita estado "nada escolhido").
+- `Switch` só para o que aplica na hora; se tem botão "Salvar", é `Checkbox`.
+
+#### Evite
+
+- `Select` com 3 opções — `RadioGroup` mostra as 3 sem um clique a mais.
+- Grupo de `Checkbox` com 40 itens — vira uma parede; use `MultiSelect`.
+- Radio e Checkbox trocados: Radio = uma; Checkbox = zero ou mais.
+- `Combobox` para sim/não.
+
+**Acessibilidade:** `Select`, `Combobox`, `RadioGroup`, `Checkbox` e `Switch` já trazem navegação por seta, Home/End, digitar-para-focar e os papéis ARIA. O `MultiSelect` é custom: ele já trata teclado, mas confirme o `aria-label` quando não houver rótulo visível.