@iclips/ui 2.0.3 → 3.1.0

package/docs/formularios.md

@@ -0,0 +1,137 @@
+# Montando um formulário
+
+Um formulário bom é **previsível**: label sempre acima do campo, erro sempre logo abaixo, ação primária sempre no mesmo canto. As decisões abaixo são o que muda de tela pra tela.
+
+## Anatomia de um campo
+
+A ordem é sempre esta, de cima para baixo:
+
+1. **Label** acima, sempre visível (nunca só placeholder).
+2. **Campo**.
+3. **Ajuda** (opcional), ligada por `aria-describedby`.
+4. **Erro** no lugar da ajuda quando houver, com `aria-invalid` no campo.
+
+### Campo completo
+
+```tsx
+import { Input, Label } from "@iclips/ui";
+
+<div className="grid w-full max-w-xs gap-1.5">
+  <Label htmlFor="site">
+    Site <span className="text-muted-foreground">(opcional)</span>
+  </Label>
+  <Input id="site" placeholder="https://" aria-describedby="site-ajuda" />
+  <p id="site-ajuda" className="text-sm text-muted-foreground">
+    Aparece no rodapé das propostas.
+  </p>
+</div>
+```
+
+### Com erro
+
+```tsx
+import { Input, Label } from "@iclips/ui";
+
+<div className="grid w-full max-w-xs gap-1.5">
+  <Label htmlFor="email">E-mail</Label>
+  <Input id="email" defaultValue="ana@" aria-invalid aria-describedby="email-erro" />
+  <p id="email-erro" className="text-sm text-destructive-emphasis">Informe um e-mail válido.</p>
+</div>
+```
+
+## Obrigatório ou opcional?
+
+Marque a minoria. Nunca os dois.
+
+| Caso | Escolha | Evite |
+| --- | --- | --- |
+| maioria obrigatória | marque só os opcionais com "(opcional)" em texto ao lado do label. | asterisco em quase todos os campos — vira ruído e ninguém lê. |
+| maioria opcional | marque os obrigatórios com "*" (ou "obrigatório") e explique o "*" uma vez no topo. | marcar "(opcional)" em 15 campos. |
+
+## Quando é validação inline vs no envio
+
+1. **O erro só pode ser sabido pelo servidor (e-mail já existe, saldo insuficiente)?** Sim: valide no envio (ou no blur com debounce, se a API aguentar). Mostre no campo. Não: continue.
+2. **É formato/obrigatoriedade que dá pra checar no cliente?** Sim: valide no blur (`mode: "onTouched"`) — erra cedo, sem incomodar quem ainda está digitando. Não: continue.
+3. **O formulário é curto (1–3 campos, ex: login)?** Sim: pode validar só no envio — o usuário vê tudo de uma vez. Não: blur + um resumo no topo (`Alert`) ao tentar enviar com erros. Foque o primeiro campo inválido.
+
+## Layout
+
+| Layout | Escolha quando | Evite quando |
+| --- | --- | --- |
+| uma coluna | o padrão. Fluxo de leitura vertical, funciona em qualquer largura, não confunde a ordem de tab. | quase nunca — só saia disso com motivo. |
+| duas colunas | pares que andam juntos e são curtos: cidade/UF, início/fim, DDD/telefone. Agrupe visualmente. | campos longos ou não relacionados lado a lado — a leitura zigue-zagueia. |
+| seções (fieldset) | formulário longo com blocos temáticos: Dados da conta / Endereço / Preferências. Título por bloco. | wizard de várias telas quando tudo cabe numa página com rolagem. |
+
+## Botões de ação
+
+#### Faça
+
+- Ação primária à direita (ou sozinha, largura total no mobile). Uma só.
+- Rótulo com o verbo da ação: "Criar projeto", "Salvar alterações" — não "Enviar" / "OK".
+- Cancelar/Voltar como variante `outline` ou `ghost`, à esquerda da primária.
+- Durante o envio: `isLoading` no botão (trava e mostra spinner) — não um overlay na tela toda.
+
+#### Evite
+
+- Dois botões com o mesmo peso visual (dois primários).
+- "Limpar" ao lado de "Salvar" — o acidente é caro; se precisar, deixe longe e peça confirmação.
+- Desabilitar o botão de envio enquanto há erro — o usuário não descobre o que falta. Deixe habilitado e valide no clique.
+
+## react-hook-form + os componentes
+
+Use `FormField` para amarrar tudo pelos ids certos automaticamente.
+
+### FormField
+
+`FormControl` injeta `id`/`aria-invalid`/`aria-describedby`; `FormMessage` some quando não há erro.
+
+```tsx
+import { useForm } from "react-hook-form";
+import {
+  Button, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, Textarea,
+} from "@iclips/ui";
+
+type Campos = { nome: string; obs: string };
+
+function NovoProjeto() {
+  const form = useForm<Campos>({ mode: "onTouched", defaultValues: { nome: "", obs: "" } });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(salvar)} className="grid w-full max-w-sm gap-4" noValidate>
+        <FormField
+          control={form.control}
+          name="nome"
+          rules={{ required: "Informe o nome." }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Nome do projeto</FormLabel>
+              <FormControl><Input placeholder="Rebranding Aurora" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="obs"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Observações <span className="text-muted-foreground">(opcional)</span></FormLabel>
+              <FormControl><Textarea rows={3} {...field} /></FormControl>
+              <FormDescription>Visível só para a equipe.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <div className="flex justify-end gap-2">
+          <Button type="button" variant="outline">Cancelar</Button>
+          <Button type="submit">Criar projeto</Button>
+        </div>
+      </form>
+    </Form>
+  );
+}
+```
+
+**Qual input para cada dado?** Está em [Escolha em lista](escolha.md) (Select vs Combobox vs Radio…). Para valores: `NumberInput`/`CurrencyInput` para números, `DatePicker`/`DateRangePicker` para datas, `PasswordInput` para senha, `InputOTP` para código, `InputGroup` quando o campo tem prefixo/sufixo (R$, .com, botão).
+
+**Acessibilidade:** todo campo com `Label htmlFor` apontando pro `id` — clicar no texto foca o campo e o leitor de tela anuncia o rótulo. `aria-describedby` liga ajuda e erro. Ao enviar com erros, mova o foco para o resumo ou para o primeiro campo inválido.

package/docs/mensagens.md

@@ -0,0 +1,114 @@
+# Onde a mensagem aparece
+
+Três eixos decidem: **é resposta a uma ação** ou uma condição persistente? **Precisa de confirmação** ou só informa? **É sobre um campo** ou sobre a tela toda?
+
+## Tabela de decisão
+
+| Mensagem | Escolha quando | Evite quando |
+| --- | --- | --- |
+| Erro de campo | a mensagem é sobre um input específico: formato inválido, obrigatório, indisponível. Fica abaixo do campo, com `aria-invalid`. | o problema é do formulário inteiro (ex: "falha de conexão ao salvar") → `Alert` no topo do form. |
+| Alert (inline) | uma condição que permanece enquanto o usuário olha a tela: aviso de plano expirando, banner de modo somente-leitura, resumo de erros de validação. | é reação efêmera a um clique que acabou de acontecer → `Toast`. |
+| Toast | confirmação passageira de uma ação: "Salvo", "E-mail enviado", "Falha ao publicar". Some sozinho. Pode ter ação "Desfazer". | a informação é importante e não pode passar batida, ou exige decisão → `Alert` ou `AlertDialog`. |
+| AlertDialog | a ação é destrutiva e você precisa que o usuário pare e confirme antes. Trava a tela. (Ver [Overlays](overlays.md).) | a ação é desfazível → execute e ofereça "Desfazer" num `Toast`. |
+
+## Trilha rápida
+
+1. **A mensagem é sobre um campo específico do formulário?** Sim: erro de campo abaixo do input + `aria-invalid` no input. Não: continue.
+2. **Você precisa bloquear a tela até o usuário decidir?** Sim: `AlertDialog`. Não: continue.
+3. **É reação imediata a um clique e pode desaparecer em segundos?** Sim: Toast (`toast.success` / `toast.error` / …). Se a ação for reversível, inclua "Desfazer". Não: continue.
+4. **A condição continua verdadeira enquanto a tela estiver aberta?** Sim: `Alert` inline, ancorado onde a condição importa. Não: provavelmente não precisa de mensagem — reavalie.
+
+## Exemplos
+
+### Toast — confirmação efêmera
+
+Dispare no callback da ação. Prefira `toast.success`/`toast.error` a texto neutro. Monte um único `<Toaster />` na raiz do app.
+
+```tsx
+import { Button, toast } from "@iclips/ui";
+
+<Button variant="outline" onClick={() => toast.success("Campanha salva")}>Salvar</Button>
+<Button
+  variant="outline"
+  onClick={() =>
+    toast("Item removido", {
+      action: { label: "Desfazer", onClick: () => toast("Restaurado") },
+    })
+  }
+>
+  Remover (com desfazer)
+</Button>
+```
+
+### Alert — condição persistente
+
+Fica na tela. Título curto + o que fazer a respeito.
+
+```tsx
+import { Alert, AlertDescription, AlertTitle } from "@iclips/ui";
+import { TriangleAlert } from "lucide-react";
+
+<Alert variant="warning" className="max-w-sm">
+  <TriangleAlert />
+  <AlertTitle>Plano expira em 3 dias</AlertTitle>
+  <AlertDescription>Renove para não perder o acesso às automações.</AlertDescription>
+</Alert>
+```
+
+### Erro de campo
+
+A mensagem vive com o input, não no topo da tela. Em formulário com react-hook-form, `FormMessage` faz isso sozinho (ver [Formulários](formularios.md)).
+
+```tsx
+import { Input, Label } from "@iclips/ui";
+
+<div className="grid w-full max-w-xs gap-1.5">
+  <Label htmlFor="email">E-mail</Label>
+  <Input id="email" defaultValue="ana@" aria-invalid aria-describedby="email-erro" />
+  <p id="email-erro" className="text-sm text-destructive-emphasis">
+    Informe um e-mail válido.
+  </p>
+</div>
+```
+
+### Alert — resumo de validação
+
+Erros do formulário inteiro sobem para um `Alert` no topo, com foco.
+
+```tsx
+import { Alert, AlertDescription, AlertTitle } from "@iclips/ui";
+import { Info } from "lucide-react";
+
+<Alert variant="destructive" className="max-w-sm" role="alert">
+  <Info />
+  <AlertTitle>Não foi possível salvar</AlertTitle>
+  <AlertDescription>Revise os 2 campos destacados abaixo.</AlertDescription>
+</Alert>
+```
+
+## Faça / evite
+
+#### Faça
+
+- Monte um único `<Toaster />` na raiz do app. Chame `toast(...)` de qualquer lugar.
+- Toast de erro: diga o que falhou e o próximo passo ("Falha ao publicar — verifique a conexão").
+- Ação reversível → execute já e ofereça "Desfazer" no toast, em vez de um `AlertDialog` antes.
+- Toast de erro fica até o usuário fechar (padrão do `toast.error`); sucesso some em 4s, aviso em 6s, informação em 5s.
+- Escuro = ação com prazo: `toast(msg, { action })` sem tipo vem em superfície invertida e dura 8s. Use só para Desfazer.
+- Progresso: `toast.promise` — o toast de processando se transforma em sucesso ou erro, em vez de somar outro na pilha.
+- Ação em lote gera um toast agregado ("12 jobs atualizados"), não doze.
+- Erro de campo: ligue input e mensagem com `aria-describedby` + `aria-invalid`.
+- Aviso: `text-warning-emphasis`, nunca `text-warning`, e sempre com ícone — amarelo sozinho não identifica um aviso.
+
+#### Evite
+
+- Toast para algo que o usuário precisa ler com atenção — ele some antes.
+- Alert de sucesso permanente que nunca some e vira ruído visual.
+- `AlertDialog` "Salvo com sucesso! [OK]" — é o caso clássico de Toast.
+- Empilhar 5 toasts de uma vez; agrupe ou resuma.
+
+**Toast:** `toast` (sonner) é a única API — `toast.success` / `toast.error` / `toast.promise`, `action`, `duration`, `toast.dismiss`. Monte um `<Toaster />` na raiz do app. Superfície neutra sempre, cor só no ícone; o único toast roxo é o de processando.
+
+**Cor de status em texto:** texto e ícone sobre superfície neutra usam a camada `-emphasis` (`text-destructive-emphasis`, `text-success-emphasis`…), que passa AA nos dois temas. Nunca `text-destructive` cru para texto. Idioma: `bg-warning/10 text-warning-emphasis border-warning/20`.
+
+**Acessibilidade:** o `Toaster` já anuncia via `aria-live`. Para um `Alert` que *aparece* em resposta a uma ação (resumo de validação), adicione `role="alert"` e mova o foco para ele.

package/docs/overlays.md

@@ -0,0 +1,192 @@
+# Qual overlay usar
+
+Todos flutuam acima da página, mas resolvem problemas diferentes. A pergunta que separa é: **o conteúdo exige uma ação do usuário** (então prende o foco) ou **só complementa** (então some ao clicar fora)?
+
+## Tabela de decisão
+
+| Overlay | Escolha quando | Evite quando |
+| --- | --- | --- |
+| Tooltip | rótulo curto para um ícone ou controle sem texto — aparece no hover/foco, some sozinho. | o conteúdo tem link, botão ou texto que o usuário precise ler com calma → `Popover`. |
+| HoverCard | prévia rica e não-essencial de algo já visível (card de usuário, resumo de projeto). | a informação é necessária para a tarefa, ou o gatilho é em mobile (não há hover) → `Popover`. |
+| Popover | um pequeno painel ancorado a um botão: filtro, seletor de cor, mini-formulário, menu de ações. | há mais de ~6 campos ou o fluxo tem etapas → `Dialog` ou `Sheet`. |
+| Dialog | uma tarefa focada que interrompe o fluxo: editar um registro, confirmar com contexto, wizard curto. | é só um aviso de sim/não destrutivo → `AlertDialog`. Formulário longo → `Sheet`. |
+| AlertDialog | confirmação de ação destrutiva ou irreversível (excluir, cancelar assinatura). Trava até o usuário decidir. | a ação não é perigosa e é desfazível → use um Toast com "Desfazer". |
+| Sheet | painel lateral para formulário longo, detalhes ou configurações sem perder o contexto da lista atrás. | a tarefa é curta e centrada → `Dialog`. Navegação primária do app → não é overlay. |
+| Drawer | o mesmo papel do Sheet, mas puxado de baixo — padrão em telas de toque/mobile. | desktop com espaço de sobra → `Sheet` lateral. |
+
+## Trilha rápida
+
+Responda de cima para baixo e pare na primeira que servir.
+
+1. **A ação é destrutiva/irreversível e precisa de confirmação?** Sim: `AlertDialog`. Não: continue.
+2. **É só um rótulo de texto para um ícone?** Sim: `Tooltip`. Não: continue.
+3. **É uma prévia opcional de algo que já está na tela?** Sim: `HoverCard` (desktop) — mas garanta um caminho por clique no mobile. Não: continue.
+4. **Cabe em um painelzinho de até ~6 campos ancorado ao gatilho?** Sim: `Popover`. Não: continue.
+5. **O usuário precisa ver a lista/tela de trás enquanto preenche?** Sim: `Sheet` (desktop) ou `Drawer` (toque). Não: `Dialog`.
+
+## Exemplos
+
+### Tooltip — rótulo de ícone
+
+Some ao tirar o mouse ou o foco. Sem conteúdo interativo dentro. Balão neutro invertido: é informação, não ação. Precisa de um `TooltipProvider` acima (uma vez, na raiz).
+
+```tsx
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from "@iclips/ui";
+import { Archive } from "lucide-react";
+
+<Tooltip>
+  <TooltipTrigger asChild>
+    <Button variant="outline" size="icon" aria-label="Arquivar">
+      <Archive className="size-4" />
+    </Button>
+  </TooltipTrigger>
+  <TooltipContent>Arquivar</TooltipContent>
+</Tooltip>
+```
+
+### Popover — mini-formulário
+
+Fecha ao clicar fora. Bom para 1–6 campos.
+
+```tsx
+import { Button, Input, Label, Popover, PopoverContent, PopoverTrigger } from "@iclips/ui";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Renomear</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-64 space-y-2">
+    <Label htmlFor="novo-nome">Novo nome</Label>
+    <Input id="novo-nome" defaultValue="Campanha Q3" />
+  </PopoverContent>
+</Popover>
+```
+
+### Dialog — tarefa focada
+
+Prende o foco. Título + descrição + ações.
+
+```tsx
+import {
+  Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle,
+  DialogTrigger, Input, Label,
+} from "@iclips/ui";
+
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Editar perfil</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Editar perfil</DialogTitle>
+      <DialogDescription>As alterações são salvas ao confirmar.</DialogDescription>
+    </DialogHeader>
+    <div className="grid gap-1.5 py-2">
+      <Label htmlFor="nome">Nome</Label>
+      <Input id="nome" defaultValue="Ana Souza" />
+    </div>
+    <DialogFooter>
+      <DialogClose asChild><Button variant="outline">Cancelar</Button></DialogClose>
+      <Button>Salvar</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### AlertDialog — confirmação destrutiva
+
+Sem clicar-fora-para-fechar. Uma escolha explícita.
+
+```tsx
+import {
+  AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription,
+  AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, Button,
+} from "@iclips/ui";
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button variant="destructive">Excluir projeto</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Excluir “Campanha Q3”?</AlertDialogTitle>
+      <AlertDialogDescription>
+        Esta ação não pode ser desfeita. Todos os itens do projeto serão removidos.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancelar</AlertDialogCancel>
+      <AlertDialogAction>Excluir</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Sheet — formulário longo
+
+A lista de trás continua visível como contexto.
+
+```tsx
+import {
+  Button, Input, Label, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle,
+  SheetTrigger,
+} from "@iclips/ui";
+
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Nova tarefa</Button>
+  </SheetTrigger>
+  <SheetContent className="w-full sm:max-w-md">
+    <SheetHeader>
+      <SheetTitle>Nova tarefa</SheetTitle>
+      <SheetDescription>Preencha os campos e salve.</SheetDescription>
+    </SheetHeader>
+    <div className="grid gap-3 px-4">
+      <div className="grid gap-1.5"><Label htmlFor="titulo">Título</Label><Input id="titulo" /></div>
+      <div className="grid gap-1.5"><Label htmlFor="responsavel">Responsável</Label><Input id="responsavel" /></div>
+      <div className="grid gap-1.5"><Label htmlFor="prazo">Prazo</Label><Input id="prazo" type="date" /></div>
+    </div>
+    <SheetFooter>
+      <Button>Criar tarefa</Button>
+      <SheetClose asChild><Button variant="outline">Cancelar</Button></SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### HoverCard — prévia opcional
+
+Só complementa. Nunca coloque aqui algo que a tarefa exige.
+
+```tsx
+import { Button, HoverCard, HoverCardContent, HoverCardTrigger } from "@iclips/ui";
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">@ana.souza</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="text-sm">
+    <p className="font-medium">Ana Souza</p>
+    <p className="text-muted-foreground">Designer · entrou em 2023</p>
+  </HoverCardContent>
+</HoverCard>
+```
+
+## Faça / evite
+
+#### Faça
+
+- Dê a todo `Dialog`/`Sheet`/`AlertDialog` um título — é o rótulo que o leitor de tela anuncia.
+- Reserve o `AlertDialog` para o que dói desfazer; para o resto, aja e ofereça "Desfazer" num Toast.
+- No mobile, troque `Sheet` lateral por `Drawer` e `HoverCard` por `Popover` (toque não tem hover).
+- Empilhe no máximo um overlay. Se precisar de outro, provavelmente o fluxo deveria ser uma página.
+
+#### Evite
+
+- Colocar um formulário de 15 campos num `Popover`.
+- Usar `Tooltip` para conteúdo que tem link ou botão — o usuário não consegue alcançar.
+- Pintar o `Tooltip` com a cor da marca (`bg-primary`) — overlay informativo não se veste de ação.
+- Abrir um `Dialog` dentro de outro `Dialog`.
+- Trocar toast de sucesso por `Dialog` "OK" — interrompe sem motivo.
+
+**Acessibilidade:** `Dialog`, `AlertDialog`, `Sheet` e `Popover` vêm do Radix — prendem o foco, fecham no Esc e devolvem o foco ao gatilho de graça. O que você precisa garantir: um `Title` em todo painel modal, e `aria-label` em gatilhos que são só ícone.

package/docs/status.md

@@ -0,0 +1,71 @@
+# Status
+
+Status é **estado**: feedback, nunca decoração. Vermelho, verde, amarelo e azul só aparecem para dizer algo sobre um item. Status nunca é roxo (roxo é ação) e sempre vem com ícone ou rótulo — cor sozinha não identifica nada.
+
+A receita é sempre suave: `bg-<status>/10 text-<status>-emphasis border-<status>/20`. Os componentes já a aplicam — use o componente em vez de montar as classes.
+
+| Status | `variant` | Quando |
+| --- | --- | --- |
+| Sucesso | `success` | aprovado, pago, concluído, ativo |
+| Aviso | `warning` | pendente, aguardando, vence em breve |
+| Informação | `info` | em análise, rascunho enviado, novidade |
+| Erro | `destructive` | recusado, vencido, falhou, cancelado |
+
+## Status de um item
+
+Use `Badge` com a variante do status e um ícone ou rótulo claro.
+
+```tsx
+import { Badge } from "@iclips/ui";
+import { Check, CircleAlert, Clock, Info } from "lucide-react";
+
+<Badge variant="success"><Check /> Aprovado</Badge>
+<Badge variant="warning"><Clock /> Aguardando</Badge>
+<Badge variant="info"><Info /> Em análise</Badge>
+<Badge variant="destructive"><CircleAlert /> Recusado</Badge>
+```
+
+Status que vem da API vira um mapa, não um `if` por status:
+
+```tsx
+import { Badge } from "@iclips/ui";
+
+const STATUS = {
+  pago: { variant: "success", rotulo: "Pago" },
+  pendente: { variant: "warning", rotulo: "Pendente" },
+  vencido: { variant: "destructive", rotulo: "Vencido" },
+} as const;
+
+function StatusParcela({ status }: { status: keyof typeof STATUS }) {
+  const { variant, rotulo } = STATUS[status];
+  return <Badge variant={variant}>{rotulo}</Badge>;
+}
+```
+
+Status neutro (sem juízo de bom ou ruim, como "Arquivado" ou "Inativo") usa `variant="muted"` ou `variant="outline"`, não uma cor de estado.
+
+## Valor positivo ou negativo
+
+Número que sobe ou desce (variação, saldo, meta) usa o texto `-emphasis` do status, com sinal ou ícone — nunca só a cor.
+
+```tsx
+import { TrendingDown, TrendingUp } from "lucide-react";
+
+<span className="inline-flex items-center gap-1 text-success-emphasis">
+  <TrendingUp className="size-4" aria-hidden="true" /> +12,4%
+</span>
+<span className="inline-flex items-center gap-1 text-destructive-emphasis">
+  <TrendingDown className="size-4" aria-hidden="true" /> −3,1%
+</span>
+```
+
+## Condição que vale para a tela toda
+
+Se o status é da página e não de um item (plano expirando, modo somente-leitura), é um `Alert` — ver [Mensagens](mensagens.md).
+
+## Regras
+
+- Status **nunca é roxo** e nunca é `text-<status>` cru em texto: use `text-<status>-emphasis`, que passa contraste AA nos dois temas.
+- Não pinte **fundo de seção** ou card com cor de estado — o badge carrega o estado, não o card.
+- Nunca fundo sólido de estado (`bg-success` sem `/10`): a cor cheia fica só no ícone e na borda de campo inválido.
+- Mais regras de cor em [Linguagem visual](../DESIGN.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iclips/ui",
-  "version": "2.0.3",
+  "version": "3.1.0",
   "description": "Design system da iClips — componentes React sobre Radix UI + Tailwind v4, paleta #7F26BF",
   "author": "iclipsbr",
   "license": "MIT",
@@ -47,7 +47,11 @@
     "scripts/codemod-v2-toast.mjs",
     "README.md",
     "LICENSE",
-    "MIGRATION-v2.md"
+    "MIGRATION-v2.md",
+    "MIGRATION-v3.md",
+    "DESIGN.md",
+    "docs",
+    "scripts/check-colors.mjs"
   ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -169,7 +173,7 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit -p src/tsconfig.json",
-    "lint": "eslint . --suppressions-location=eslint-suppressions.json && node scripts/check-forwardref.mjs",
+    "lint": "eslint . --suppressions-location=eslint-suppressions.json && node scripts/check-forwardref.mjs && node scripts/check-colors.mjs",
     "lint:fix": "eslint . --fix --suppressions-location=eslint-suppressions.json",
     "lint:prune-suppressions": "eslint . --prune-suppressions --suppressions-location=eslint-suppressions.json",
     "format": "prettier --write .",