@iclips/ui 2.0.3 → 3.1.0

package/DESIGN.md

@@ -0,0 +1,246 @@
+---
+version: 3.0.0
+name: iClips Design Language
+description: The visual language of @iclips/ui 3.0.0 — one purple for action, a lot of grey for structure, and colour only where it means something, set in Inter.
+source: "@iclips/ui 3.0.0 — tokens/*.json, src/styles/tokens.css and the components under src/components/ui"
+scope: Colour, type, radius, buttons and surfaces. Spacing lives in tokens/spacing.json; elevation and motion live in the component styles.
+
+colors:
+  # semantic tokens — light theme value (dark theme value in the comment)
+  background: "#FFFFFF" # dark #1A1F26
+  foreground: "#1A1F26" # dark #F2F6FA
+  card: "#FFFFFF" # dark #2F3640
+  muted: "#E9EEF5" # dark #464E59
+  muted-foreground: "#464E59" # dark #C5CDD9
+  accent: "#E9EEF5" # hover — dark #464E59
+  border: "#DAE1EB" # dark #464E59
+  input: "#DAE1EB" # dark #464E59
+  primary: "#7F26BF" # dark #DAA6FF (purple-100: passa AA sobre card/popover gray-700)
+  primary-foreground: "#FFFFFF" # dark #000000
+  secondary: "#F6E9FF" # selection — dark #420F66
+  secondary-foreground: "#420F66" # dark #DAA6FF
+  ring: "#7F26BF" # dark #BB6DF2
+  destructive: "#AB4A43"
+  success: "#427748"
+  warning: "#E4BB78" # dark #CFA066
+  info: "#315687"
+
+typography:
+  body:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: 400
+  caption:
+    fontFamily: Inter
+    fontSize: 12px
+    fontWeight: 400
+  label:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: 500
+  button:
+    fontFamily: Inter
+    fontSize: 14px
+    fontWeight: 600
+  title:
+    fontFamily: Inter
+    fontWeight: 600
+    lineHeight: 1.2
+
+rounded:
+  sm: 6px
+  md: 8px
+  lg: 10px
+  xl: 14px
+  full: 9999px
+
+components:
+  button-default:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-secondary:
+    backgroundColor: "{colors.secondary}"
+    textColor: "{colors.secondary-foreground}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-outline:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    borderColor: "{colors.border}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-ghost:
+    textColor: "{colors.foreground}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-link:
+    textColor: "{colors.primary}"
+    typography: "{typography.button}"
+  button-destructive:
+    backgroundColor: "color-mix({colors.destructive} 10%)"
+    textColor: "{colors.destructive-emphasis}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  button-success:
+    backgroundColor: "color-mix({colors.success} 10%)"
+    textColor: "{colors.success-emphasis}"
+    typography: "{typography.button}"
+    rounded: "{rounded.md}"
+  card:
+    backgroundColor: "{colors.card}"
+    borderColor: "{colors.border}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.xl}"
+---
+
+> **Precedência.** Este documento resume o que a `@iclips/ui` 3.0.0 entrega. A
+> fonte de verdade são `tokens/*.json` (e o `src/styles/tokens.css` gerado) e o
+> código dos componentes; se algo aqui divergir deles, o código vence e este
+> arquivo está desatualizado. Os nomes em `colors.*`, `rounded.*` e
+> `components.*` acima correspondem aos tokens semânticos e às variantes reais —
+> no código, escreva `bg-primary`, `rounded-md`, `<Button variant="outline">`.
+> A página Storybook `Fundamentos/Cores` mostra cada par com o contraste medido.
+
+## Overview
+
+**Um roxo, muito cinza, e cor só onde ela significa algo.** Roxo é ação — botão
+primário, link, seleção, foco. Cinza é estrutura — fundo, card, borda, texto, onde
+fica a maior parte da tela. Vermelho, verde, amarelo e azul são estado — feedback,
+nunca decoração. Nenhuma outra cor existe na lib: só tokens semânticos viram
+classe, e o `npm run lint` reprova cor crua.
+
+**Key characteristics**
+
+- Quatro camadas de cor com permissão fechada: estrutura (cinza), ação (roxo),
+  estado (feedback), categoria (só em gráfico)
+- Uma cor de ação; a hierarquia entre ações vem do preenchimento
+- Hover é cinza; lavanda significa selecionado
+- Peso 600 marca ação e título; o corpo fica em 400
+- Raios de 6 a 10px no que se clica e no que flutua; 14px nos contêineres
+
+## Colours
+
+Só existem tokens semânticos como classe. Os primitivos por trás deles — gray
+50–900, purple 50–500 e 700, e o preenchimento de cada estado — são custom
+properties de fiação, sem classe. Os valores estão no cabeçalho deste arquivo,
+claro e escuro.
+
+### Estrutura — neutros
+
+| Token | Uso |
+| --- | --- |
+| `background` / `foreground` | canvas e texto padrão |
+| `card`, `popover` | superfícies elevadas |
+| `muted` / `muted-foreground` | fundo sutil e texto de apoio |
+| `accent` | hover e realce de item de menu — cinza, sem peso |
+| `border`, `input` | divisória e borda de campo |
+
+### Ação — roxo, exclusivo
+
+| Token | Uso |
+| --- | --- |
+| `primary` / `primary-foreground` | botão primário, link, foco, progresso |
+| `secondary` / `secondary-foreground` | item selecionado, ação secundária |
+| `ring` | anel de foco |
+| `sidebar-selected` | item ativo da sidebar |
+
+Selecionado > focado > sob o cursor: seleção em `secondary` (matiz, tinta e peso
+500), foco em anel, hover em `accent` cinza. Fundo lavanda decorativo só em tela
+sem lista, tabela, menu ou calendário — onde há o que selecionar, ele se lê como
+seleção.
+
+### Estado — feedback, nunca decoração
+
+Estado é sempre suave: o token cru (`destructive`, `success`, `warning`,
+`info`) nunca é fundo. A receita única é
+`bg-<status>/10 text-<status>-emphasis border-<status>/20`, em Button e Badge de
+estado, Alert e selo. A cor cheia fica só no ícone e na borda de campo inválido.
+Status nunca é roxo e sempre vem com ícone ou rótulo.
+
+### Categoria — só dados
+
+`chart-1..8` alternam roxo e cinza em luminância, começando pelo roxo. Nunca em
+botão, link, ícone de navegação ou fundo de seção.
+
+## Typography
+
+A lib não embarca fonte: o app instala **Inter**, e o `body` usa
+`var(--font-sans)`. A lib não estiliza elementos soltos (`h1`…`h6`, `p`, `label`)
+— só o `body` e os próprios componentes.
+
+| Papel | Tamanho | Peso | Onde |
+| --- | --- | --- | --- |
+| `{typography.body}` | 14px (`text-sm`) | 400 | texto de componente, campos, menus |
+| `{typography.caption}` | 12px (`text-xs`) | 400 | badge, ajuda, metadado |
+| `{typography.label}` | 14px | 500 | rótulo, item selecionado |
+| `{typography.button}` | 14px | 600 | todas as variantes do `Button` |
+| `{typography.title}` | — | 600 | `CardTitle` e títulos de seção |
+
+**Peso 600 significa ação ou título.** Negrito no corpo do texto não tem papel.
+
+## Shape
+
+Tudo deriva de `--radius` (10px).
+
+| Token | Valor | Uso |
+| --- | --- | --- |
+| `{rounded.sm}` | 6px | item de menu, chips, tags |
+| `{rounded.md}` | 8px | botão, input, popover, menu, tooltip |
+| `{rounded.lg}` | 10px | dialog |
+| `{rounded.xl}` | 14px | contêiner — `Card` e painéis grandes |
+| `{rounded.full}` | 9999px | avatar, badge, indicadores |
+
+Quanto maior a superfície, maior o raio; não há botão em pílula.
+
+## Buttons
+
+Sete variantes, todas em `{typography.button}` e `{rounded.md}`, com altura de
+32 (`sm`), 36 (`default`) ou 40px (`lg`); `icon` é 36×36.
+
+- **`default`** — roxo cheio. A ação principal da tela; uma por tela.
+- **`secondary`** — lavanda com texto roxo. Ação secundária.
+- **`outline`** — fundo neutro com borda; hover cinza.
+- **`ghost`** — sem fundo; hover cinza. Barras de ferramenta e ações densas.
+- **`link`** — texto roxo sublinhado no hover.
+- **`destructive`** — suave: tinta vermelha a 10%, texto `destructive-emphasis`,
+  borda leve. Excluir, ação irreversível.
+- **`success`** — suave, mesma receita em verde. Confirmar um estado positivo.
+
+Clique: no `default` o preenchimento vai a 90% (hover) e 80% (pressionado); no
+`destructive`/`success` a tinta sobe de 10% para 15% (hover) e 20% (pressionado).
+O foco é um anel de 3px em `ring`.
+
+## Surfaces
+
+**`card`** — `bg-card` com borda `border` e `{rounded.xl}`. O contêiner padrão;
+a definição vem da borda, não de sombra.
+
+Popover, menus e dialog usam `popover` e sombra; o `Tooltip` é neutro invertido
+(`bg-foreground text-background`).
+
+## Do and don't
+
+**Do**
+
+- Use roxo para a ação principal, links, seleção e foco — e só para isso.
+- Use `text-<status>-emphasis` para texto de estado, sempre com ícone ou rótulo.
+- Use no máximo dois fundos por tela: `muted` e `background`; o terceiro, quando
+  existir, é `secondary`.
+- Mantenha um botão `default` por tela; o segundo vira `secondary` ou `outline`.
+
+**Don't**
+
+- Não escreva cor crua (`bg-gray-100`, `text-purple-600`): ela não gera CSS e o
+  lint reprova. Use o token semântico.
+- Não pinte fundo de seção com cor de estado — o badge carrega o estado, não o card.
+- Não use cor de gráfico (`chart-N`) fora de dados.
+- Não use negrito para dar ênfase no corpo do texto.
+
+## Scope and limits
+
+Este arquivo cobre **cor, tipo, raio, botões e superfícies** da lib. Espaçamento
+está em `tokens/spacing.json`; elevação e movimento, nos estilos dos
+componentes. A régua de cada componente (anatomia, variantes, acessibilidade)
+está em `src/components/ui/AGENTS.md`.

package/MIGRATION-v3.md

@@ -0,0 +1,244 @@
+# Migração para @iclips/ui v3
+
+`3.0.0` reduz a paleta à **paleta iClips** — "um roxo, muito cinza, e cor só onde
+ela significa algo" — e junta as mudanças visuais que iam sair na 2.1. Nenhum
+import nem componente foi renomeado; o que quebra é **cor crua** no seu código e
+dois valores de prop (seção 1).
+
+**Comece por aqui**, na raiz do app, depois de instalar a 3.0.0:
+
+```bash
+node node_modules/@iclips/ui/scripts/check-colors.mjs src
+```
+
+Ele lista cada cor crua (`arquivo:linha  classe  → sugestão`) e não altera nada.
+Exit 0 = nada a migrar.
+
+## 1. Paleta iClips enxuta (BREAKING)
+
+### O que existe agora
+
+Só tokens semânticos viram classe: `bg-background`, `bg-card`, `bg-muted`,
+`text-foreground`, `text-muted-foreground`, `border-border`, `border-input`,
+`bg-primary`, `bg-secondary`, `bg-accent`, `bg-destructive`/`success`/`warning`/`info`,
+`text-<status>-emphasis`, `bg-chart-1..8`, `bg-sidebar-*` e afins — mais
+`white`, `black`, `transparent` e `current`.
+
+Os primitivos que sobraram (gray 50–900; purple 50–500 e 700, com 300 e 400
+novos; red/green/cyan 600; yellow 500/600) existem só como custom property
+(`var(--gray-100)`), para alimentar os semânticos. **Não geram classe.**
+
+### O que saiu
+
+- As famílias `pink`, `blue`, `teal` e `orange` inteiras, e os degraus sem
+  consumidor das demais (`purple-600`, `red-50`, `green-200`, `cyan-500`…).
+- Toda classe de cor crua: `bg-gray-100`, `text-purple-600`, `border-red-200`…
+- A **paleta padrão do Tailwind** para quem usa o preset (modo B): o `@theme`
+  da lib começa com `--color-*: initial`, então `bg-zinc-900`, `text-sky-500`
+  etc. deixam de gerar CSS. Classe que não gera CSS não dá erro — ela só não
+  pinta. Por isso rode o `check-colors.mjs`.
+- `var(--pink-*)`, `var(--blue-*)`, `var(--teal-*)`, `var(--orange-*)` e os
+  degraus removidos.
+
+> **Tem cores próprias no `@theme` do app?** Declare-as **depois** do
+> `@import "@iclips/ui/preset.css"` — o `--color-*: initial` da lib zera o que
+> vier antes.
+
+### Tabela de equivalência
+
+| Antes | Depois |
+| --- | --- |
+| `bg-gray-50` | `bg-background` ou `bg-muted/40` |
+| `bg-gray-100`, `bg-gray-200` | `bg-muted` |
+| `bg-gray-700`…`bg-zinc-900` (superfície escura) | `bg-card` |
+| `border-gray-100`, `border-gray-200` | `border-border` |
+| `border-gray-300` | `border-input` |
+| `text-gray-400`…`text-gray-600` | `text-muted-foreground` |
+| `text-gray-700`…`text-gray-900` | `text-foreground` |
+| `bg-purple-500`, `bg-purple-600` | `bg-primary` |
+| `bg-purple-50`, `bg-purple-100` | `bg-secondary` (seleção) |
+| `text-purple-500`, `text-purple-600` | `text-primary` |
+| `text-purple-700` | `text-secondary-foreground` |
+| `border-purple-*`, `ring-purple-*` | `border-primary`, `ring-ring` |
+| `text-red-600`, `text-green-600`, `text-yellow-700`, `text-blue-600` | `text-destructive-emphasis`, `text-success-emphasis`, `text-warning-emphasis`, `text-info-emphasis` |
+| `bg-red-600` / `bg-red-50` (idem green, yellow, blue) | `bg-destructive` / `bg-destructive/10` |
+| `border-red-200` (idem) | `border-destructive/20` |
+| `teal`, `orange`, `pink`, `indigo`, `violet`… | sem equivalente: a paleta não tem essas cores. Em dados, `var(--chart-N)`; fora disso, um token semântico |
+
+### Componentes
+
+- **`Avatar`** — `colorVariant` aceita só `"gray"` e `"purple"` (roxo =
+  `bg-secondary text-secondary-foreground`). `pink`, `blue`, `cyan`, `teal`,
+  `green`, `yellow`, `orange` e `red` não compilam mais no TypeScript: troque por
+  `purple` ou `gray`. `getColorFromString` passa a devolver um dos dois.
+- **`DonutChart`** — fatia sem `color` usa `var(--chart-N)`, não mais 10 hex
+  da paleta padrão do Tailwind.
+- **`<Button variant="cta">`** e `--cta` — não existem (anunciados para a 2.1,
+  que não chegou a sair). Use `variant="default"` para a ação principal.
+
+### Gráficos
+
+`--chart-1..8` passam a roxo e cinza alternando claro e escuro, começando pelo
+roxo. Quem usa `var(--chart-N)` vê o gráfico mudar de cor. Categoria é só para
+dados — nunca botão, link ou fundo de seção.
+
+## 2. Hover deixa de ser lavanda; lavanda passa a significar "selecionado"
+
+`--accent` e `--secondary` tinham o mesmo valor. Como `--accent` é a cor de
+hover e de item realçado em todo o sistema, e `--secondary` é a de item
+selecionado, **selecionado e sob o cursor pintavam o mesmo pixel**: numa lista
+não havia como distinguir a linha escolhida da linha sob o mouse.
+
+Hover foi quem cedeu — dura 200ms, não existe em tela de toque e não diz nada
+sobre o dado.
+
+| Token                       | Claro, antes → depois               | Escuro, antes → depois            |
+| --------------------------- | ----------------------------------- | --------------------------------- |
+| `--accent`                  | `purple.50` → `gray.100`            | `purple.700` → `gray.600`         |
+| `--accent-foreground`       | `purple.600` → `--foreground`       | `purple.100` → `gray.50`          |
+| `--secondary`               | sem mudança (`purple.50`)           | `gray.700` → `purple.700`         |
+| `--secondary-foreground`    | sem mudança (`purple.700`)          | `gray.50` → `purple.100`          |
+| `--sidebar-accent`          | `purple.50` → `gray.100`            | sem mudança (`gray.700`)          |
+| `--sidebar-accent-foreground` | `purple.700` → `--sidebar-foreground` | `purple.100` → `gray.50`        |
+
+No escuro o defeito era o inverso: `--secondary` tinha a mesma cor de `--card`
+e `--popover`, então item selecionado dentro de popover era invisível.
+
+### O que você vai ver mudar
+
+| Onde                                                    | Antes   | Depois                      |
+| ------------------------------------------------------- | ------- | --------------------------- |
+| `Button` `outline` e `ghost`, sob o cursor              | lavanda | cinza                       |
+| Item realçado em menus, `Select` e `Command`            | lavanda | cinza                       |
+| Dia de hoje e dia sob o cursor no `Calendar`            | lavanda | cinza                       |
+| Item de sidebar sob o cursor                            | lavanda | cinza                       |
+| Item **selecionado** em `Combobox`, `MultiSelect`, faixa do `Calendar` | lavanda (ou só ✓) | lavanda + texto roxo + peso 500 |
+| Item **ativo** na sidebar e no `NavigationMenu`         | lavanda | lavanda, sem mudança        |
+| `Toggle` ligado, status "aprovação", reação ativa, menção | lavanda | lavanda, sem mudança      |
+| `Button`/`Badge` `secondary` **no tema escuro**         | cinza   | roxo escuro                 |
+
+Foco por teclado nas listas passou a ser um anel, não um fundo, para
+sobreviver sobre qualquer um dos dois.
+
+Efeito colateral bem-vindo: passar o mouse por uma barra de ferramentas deixa
+de pintar a tela de roxo da marca.
+
+### Se você usou `bg-accent` para decoração
+
+`bg-accent` agora renderiza cinza. Se a intenção era o tom da marca, troque por
+`bg-secondary` — **só em tela sem lista, tabela, menu ou calendário**, onde
+lavanda passou a significar "isto está selecionado".
+
+### Se você sobrescreveu `--accent`
+
+Nada muda para você. Vale reavaliar: o papel do token mudou de "realce da
+marca" para "hover neutro".
+
+## 3. Novo token: `--sidebar-selected`
+
+- `--sidebar-selected` / `--sidebar-selected-foreground` — item ativo da
+  sidebar (os valores que `--sidebar-accent` tinha).
+
+Adição; nada existente mudou por causa dela.
+
+## 4. Botões um degrau mais pesados
+
+`Button` e `SocialButton` passaram de `font-medium` (500) para `font-semibold`
+(600). Peso 600 agora significa uma coisa só no sistema: ação.
+
+Botão com rótulo longo em espaço apertado: confira — 600 ocupa um pouco mais de
+largura.
+
+## 5. Tooltip neutro
+
+`Tooltip` era roxo da marca; agora é cinza-escuro no claro e claro no escuro.
+Sobreposição informativa não compete mais com os botões primários.
+
+## 6. Contraste de status (sem ação necessária)
+
+- Texto e ícone de status passaram de `text-<status>` para
+  `text-<status>-emphasis` (`Form`, `EmptyState`, menus, anexos, validação).
+- No escuro, `--*-emphasis` passou a misturar 45% do status (era 80%, que
+  ficava entre 2,4 e 4,2:1 sobre `card`/`popover`) e é redeclarado em `.dark`.
+  Se o seu app aplica `.dark` numa seção em vez do `<html>`, o `-emphasis`
+  agora acompanha o tema — antes herdava a mistura do claro.
+- As iniciais do `Avatar` e os chips do `EditorialCalendar` misturam o token
+  com `--foreground` para passar AA. Se você usa `text-chart-N` em texto,
+  faça o mesmo: os tokens de gráfico são cor de preenchimento.
+
+## 6b. Roxo de ação mais claro no escuro
+
+No tema escuro, `--primary` passou de purple-200 (`#BB6DF2`) para purple-100
+(`#DAA6FF`). O antigo dava 3,8:1 como texto sobre `card`/`popover` (gray-700),
+abaixo de AA; o novo dá ~6,4:1. Botões `default`, checkbox marcado e slider
+ficam lavanda-claro no escuro, com o mesmo texto quase preto. `ring` e
+`chart-1` continuam em purple-200. Se você fixou `#BB6DF2` como "roxo da marca
+no escuro" no seu app, troque por `var(--primary)`.
+
+## 6c. Estado suave: nada de vermelho, verde, amarelo ou azul cheio
+
+Cor de estado não é mais fundo sólido em lugar nenhum. `Button`
+`variant="destructive"` e `"success"`, `Badge variant="destructive"` e os
+`Alert` de estado usam a receita suave: fundo `bg-<status>/10`, texto e ícone
+`text-<status>-emphasis`, borda `border-<status>/20` (Alert: tinta de 10%, era
+22%). Os nomes de variante não mudam.
+
+- Se você passou `className="text-white"` (ou similar) para um Button/Badge de
+  estado presumindo fundo cheio, remova: o texto agora é escuro no claro e
+  claro no escuro.
+- Não escreva `bg-destructive`/`bg-success`/`bg-warning`/`bg-info` sem
+  opacidade no seu app; use a receita acima.
+
+## 6d. Tons de estado mais calmos (sem ação necessária)
+
+Os primitivos de estado perderam cerca de 40% da saturação, com a mesma
+luminosidade (o contraste não muda):
+
+| Primitivo | Antes | Agora |
+| --- | --- | --- |
+| `red-600` (`destructive`) | `#CC0A1A` | `#AB4A43` |
+| `green-600` (`success`) | `#007F2A` | `#427748` |
+| `cyan-600` (`info`) | `#0053A6` | `#315687` |
+| `yellow-500` (`warning` claro) | `#FAB325` | `#E4BB78` |
+| `yellow-600` (`warning` escuro) | `#E6960B` | `#CFA066` |
+
+Quem usa os tokens acompanha sozinho. Se o seu app fixou algum desses hex,
+troque pelo token.
+
+## 7. Alvos de toque (sem ação necessária)
+
+Quatro botões de ícone de 24px (`CommentSystem` reagir/excluir,
+`EditorialCalendar` agendar/recolher backlog) mantêm o tamanho visual e ganham
+área de toque de 32–36px.
+
+## 8. Toast: superfície neutra e durações por tipo
+
+O visual muda sem mudar a API: `toast`, `toast.success/error/warning/info`,
+`toast.promise` e `<Toaster />` continuam iguais.
+
+- **Visual:** o toast não é mais um retângulo colorido. Fundo `card`, título
+  `foreground`, descrição `muted-foreground`; a cor de estado fica só no ícone,
+  dentro de um disco. O toast de processando (`toast.loading` /
+  `toast.promise`) é o único roxo. `toast(msg, { action })` **sem tipo** vem em
+  superfície invertida (escura no tema claro): é o padrão para "Desfazer".
+- **Durações padrão** (quando você não passa `duration`): sucesso 4s, aviso 6s,
+  informação 5s, sem tipo com `action` 8s. **`toast.error` não some mais
+  sozinho**: fica até o usuário fechar, com botão de fechar. Se algum fluxo
+  depende do erro sumir, passe `duration` explicitamente.
+- Se você estilizava `.toast-variant-*`, essas classes saíram; o estilo agora
+  vive em `[data-sonner-toast].toast[data-type=…]`.
+
+---
+
+## Resumo do que conferir
+
+0. **`check-colors.mjs` sem achados** — seção 1. É o único passo que quebra
+   em silêncio.
+1. Telas com **lista, tabela ou calendário selecionável** — seção 2, para
+   melhor.
+2. Uso de `bg-accent` **decorativo** no seu código.
+3. `Button`/`Badge` `secondary` no tema escuro.
+4. Botões com rótulo longo (seção 4).
+5. Fluxos que contam com `toast.error` sumindo sozinho (seção 8).
+
+O resto é repintura sem risco.

package/README.md

@@ -17,6 +17,10 @@ import { Button, Dialog } from "@iclips/ui";
 import { DocumentEditor } from "@iclips/ui/editor";
 ```
 
+**Para agentes de IA (e para quem monta tela):** o guia de uso — qual componente
+em cada situação, com código pronto — vem no pacote, na versão instalada, em
+`node_modules/@iclips/ui/docs/`. Comece por `docs/README.md`.
+
 O JS já é tree-shakeable (um módulo por componente). Falta só o CSS — dois modos:
 
 ### Modo A — CSS pré-compilado (qualquer stack, sem Tailwind)

package/dist/alert-theme.css

@@ -1,94 +1,35 @@
 /*
- * Alert Variant Theme Styles
- * Uses CSS variables for automatic dark/light mode adaptation.
- * These classes are referenced by alert.tsx CVA variants.
- *
- * Variables used (defined in globals.css, change between modes):
- *   --info        → cyan-500 (light) / cyan-600 (dark)
- *   --success     → green-500 (light) / green-600 (dark)
- *   --warning     → yellow-500 (light) / yellow-600 (dark)
- *   --destructive → red-500 (light) / red-600 (dark)
- *   --foreground  → gray-800 (light) / gray-50 (dark)
- *   --card        → white (light) / gray-700 (dark)
- *   --border      → gray-200 (light) / gray-600 (dark)
+ * Alert de estado — mesma receita suave do resto da lib: tinta de 10% da cor
+ * de estado sobre o card, borda levemente tingida, texto e ícone na camada
+ * -emphasis (que passa AA nos dois temas). Estado nunca é fundo sólido nem
+ * tinta forte: a cor identifica, a superfície não grita.
  */
 
-/* ── Info ─────────────────────────────────────────────────── */
 [data-slot="alert"].alert-variant-info {
-  color: color-mix(in oklab, var(--info) 80%, var(--foreground));
-  background-color: color-mix(in oklab, var(--info) 22%, var(--card));
-  border-color: color-mix(in oklab, var(--info) 50%, var(--border));
+  --alert-state: var(--info);
+  --alert-text: var(--info-emphasis);
 }
-
-[data-slot="alert"].alert-variant-info > svg {
-  color: var(--info);
-}
-
-[data-slot="alert"].alert-variant-info *[data-slot="alert-description"] {
-  color: color-mix(in oklab, var(--info) 65%, var(--foreground));
-}
-
-[data-slot="alert"].alert-variant-info *[data-slot="alert-title"] {
-  color: color-mix(in oklab, var(--info) 80%, var(--foreground));
-}
-
-/* ── Success ──────────────────────────────────────────────── */
 [data-slot="alert"].alert-variant-success {
-  color: color-mix(in oklab, var(--success) 80%, var(--foreground));
-  background-color: color-mix(in oklab, var(--success) 22%, var(--card));
-  border-color: color-mix(in oklab, var(--success) 50%, var(--border));
-}
-
-[data-slot="alert"].alert-variant-success > svg {
-  color: var(--success);
+  --alert-state: var(--success);
+  --alert-text: var(--success-emphasis);
 }
-
-[data-slot="alert"].alert-variant-success *[data-slot="alert-description"] {
-  color: color-mix(in oklab, var(--success) 65%, var(--foreground));
-}
-
-[data-slot="alert"].alert-variant-success *[data-slot="alert-title"] {
-  color: color-mix(in oklab, var(--success) 80%, var(--foreground));
-}
-
-/* ── Warning ──────────────────────────────────────────────── */
-/* --warning é o único token de status "claro" (yellow-500). Derivar texto
-   com o mesmo 80/65% dos outros deixaria ~2,4:1 sobre o fundo pálido — abaixo
-   de AA. O texto do warning mistura muito mais --foreground (fica âmbar
-   escuro); o ícone continua no amarelo cheio. */
 [data-slot="alert"].alert-variant-warning {
-  color: color-mix(in oklab, var(--warning) 32%, var(--foreground));
-  background-color: color-mix(in oklab, var(--warning) 22%, var(--card));
-  border-color: color-mix(in oklab, var(--warning) 50%, var(--border));
-}
-
-[data-slot="alert"].alert-variant-warning > svg {
-  color: color-mix(in oklab, var(--warning) 80%, var(--foreground));
-}
-
-[data-slot="alert"].alert-variant-warning *[data-slot="alert-description"] {
-  color: color-mix(in oklab, var(--warning) 26%, var(--foreground));
+  --alert-state: var(--warning);
+  --alert-text: var(--warning-emphasis);
 }
-
-[data-slot="alert"].alert-variant-warning *[data-slot="alert-title"] {
-  color: color-mix(in oklab, var(--warning) 32%, var(--foreground));
-}
-
-/* ── Destructive ──────────────────────────────────────────── */
 [data-slot="alert"].alert-variant-destructive {
-  color: color-mix(in oklab, var(--destructive) 80%, var(--foreground));
-  background-color: color-mix(in oklab, var(--destructive) 22%, var(--card));
-  border-color: color-mix(in oklab, var(--destructive) 50%, var(--border));
-}
-
-[data-slot="alert"].alert-variant-destructive > svg {
-  color: var(--destructive);
+  --alert-state: var(--destructive);
+  --alert-text: var(--destructive-emphasis);
 }
 
-[data-slot="alert"].alert-variant-destructive *[data-slot="alert-description"] {
-  color: color-mix(in oklab, var(--destructive) 65%, var(--foreground));
+[data-slot="alert"][class*="alert-variant-"] {
+  color: var(--alert-text);
+  background-color: color-mix(in oklab, var(--alert-state) 10%, var(--card));
+  border-color: color-mix(in oklab, var(--alert-state) 20%, var(--border));
 }
 
-[data-slot="alert"].alert-variant-destructive *[data-slot="alert-title"] {
-  color: color-mix(in oklab, var(--destructive) 80%, var(--foreground));
+[data-slot="alert"][class*="alert-variant-"] > svg,
+[data-slot="alert"][class*="alert-variant-"] *[data-slot="alert-title"],
+[data-slot="alert"][class*="alert-variant-"] *[data-slot="alert-description"] {
+  color: var(--alert-text);
 }

package/dist/components/ui/charts/donut-chart.cjs

@@ -1,2 +1,2 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react/jsx-runtime"),w=require("react"),h=require("recharts"),p=require("../utils.cjs");function z(n){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(n){for(const s in n)if(s!=="default"){const l=Object.getOwnPropertyDescriptor(n,s);Object.defineProperty(t,s,l.get?l:{enumerable:!0,get:()=>n[s]})}}return t.default=n,Object.freeze(t)}const b=z(w),v=["#3b82f6","#10b981","#f59e0b","#ef4444","#8b5cf6","#06b6d4","#f97316","#14b8a6","#ec4899","#6366f1"];function D(n){return new Intl.NumberFormat("pt-BR",{style:"currency",currency:"BRL"}).format(n)}function M({layout:n,chartSize:t}){const s=[1,2,3].map(l=>e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsx("div",{className:"w-2.5 h-2.5 rounded-full bg-muted shrink-0"}),e.jsx("div",{className:"h-3 bg-muted rounded flex-1"})]},l));return n==="horizontal"?e.jsxs("div",{className:"flex items-center gap-6 w-full animate-pulse",children:[e.jsx("div",{className:"rounded-full bg-muted shrink-0",style:{width:t,height:t}}),e.jsx("div",{className:"flex flex-col gap-2 flex-1",children:s})]}):e.jsxs("div",{className:"flex flex-col items-center justify-center w-full animate-pulse gap-4",children:[e.jsx("div",{className:"rounded-full bg-muted",style:{width:140,height:140}}),e.jsx("div",{className:"flex flex-col gap-2 w-full max-w-50",children:s})]})}function R(){return e.jsxs("div",{className:"flex flex-col items-center justify-center w-full h-full text-muted-foreground gap-2",children:[e.jsx("div",{className:"rounded-full border-4 border-dashed border-muted",style:{width:100,height:100}}),e.jsx("span",{className:"text-sm",children:"Sem dados para exibir"})]})}function k({active:n,payload:t,formatValue:s,total:l}){if(!n||!(t!=null&&t.length))return null;const c=t[0],r=l>0?(c.value/l*100).toFixed(1):"0.0";return e.jsxs("div",{className:"bg-popover border border-border rounded shadow-lg p-2 text-xs min-w-35",children:[e.jsx("div",{className:"font-medium mb-1",children:c.name}),e.jsxs("div",{className:"flex justify-between gap-4",children:[e.jsx("span",{className:"text-muted-foreground",children:"Valor"}),e.jsx("span",{className:"font-mono",children:s(c.value)})]}),e.jsxs("div",{className:"flex justify-between gap-4",children:[e.jsx("span",{className:"text-muted-foreground",children:"%"}),e.jsxs("span",{className:"font-mono",children:[r,"%"]})]})]})}function A({viewBox:n,activeIndex:t,chartData:s,formatValue:l,total:c}){const r=(n==null?void 0:n.cx)??0,i=(n==null?void 0:n.cy)??0,o=t!==null&&t>=0?s[t]:null;if(o){const a=c>0?(o.value/c*100).toFixed(1):"0.0",d=13,j=o.name.length>d?o.name.substring(0,d-1)+"…":o.name;return e.jsxs("g",{children:[e.jsx("text",{x:r,y:i-14,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:10,fill:"var(--muted-foreground)"},children:j}),e.jsx("text",{x:r,y:i+2,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:11,fontWeight:700,fill:o.color},children:l(o.value)}),e.jsxs("text",{x:r,y:i+18,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:11,fill:"var(--muted-foreground)"},children:[a,"%"]})]})}return e.jsxs("g",{children:[e.jsx("text",{x:r,y:i-8,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:10,fill:"var(--muted-foreground)"},children:"Total"}),e.jsx("text",{x:r,y:i+8,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:13,fontWeight:700,fill:"currentColor"},children:l(c)})]})}function C({chartData:n,total:t,formatValue:s,activeIndex:l,onHover:c}){return e.jsxs("div",{className:"flex flex-col gap-1.5",children:[n.map((r,i)=>{const o=t>0?(r.value/t*100).toFixed(1):"0.0",a=l===i,d=l!==null&&!a;return e.jsxs("div",{className:"flex items-center gap-2 text-xs cursor-default rounded px-1 py-0.5 transition-opacity",style:{opacity:d?.4:1},onMouseEnter:()=>c(i),onMouseLeave:()=>c(null),children:[e.jsx("span",{className:"inline-block w-2.5 h-2.5 rounded-full shrink-0 transition-transform",style:{background:r.color,transform:a?"scale(1.3)":"scale(1)"}}),e.jsx("span",{className:"flex-1 truncate text-muted-foreground",children:r.name}),e.jsx("span",{className:"font-mono text-foreground",children:s(r.value)}),e.jsxs("span",{className:"text-muted-foreground w-10.5 text-right",children:[o,"%"]})]},i)}),e.jsxs("div",{className:"flex items-center gap-2 text-xs border-t border-border pt-1.5 mt-0.5",children:[e.jsx("span",{className:"flex-1 font-medium",children:"Total"}),e.jsx("span",{className:"font-mono font-semibold",children:s(t)})]})]})}function L({data:n,title:t,formatValue:s=D,className:l,isLoading:c=!1,layout:r="vertical",activeLabel:i=!1,chartSize:o}){const[a,d]=b.useState(null),j=b.useMemo(()=>n.reduce((u,m)=>u+m.value,0),[n]),g=b.useMemo(()=>n.map((u,m)=>({name:u.label,value:u.value,color:u.color??v[m%v.length]})),[n]),x=r==="horizontal",f=o??(x?140:220),y=x?Math.round(f*.34):55,S=x?Math.round(f*.51):85;return e.jsxs("div",{className:p.cn("flex flex-col gap-4 w-full",l),children:[t&&e.jsx("div",{className:"text-sm font-semibold text-foreground",children:t}),c?e.jsx(M,{layout:r,chartSize:f}):n.length===0?e.jsx(R,{}):e.jsxs("div",{className:p.cn(x?"flex items-center gap-4":"flex flex-col gap-4"),children:[e.jsx("div",{className:"shrink-0",style:x?{width:f,height:f}:{width:"100%",height:f},children:e.jsx(h.ResponsiveContainer,{width:"100%",height:"100%",children:e.jsxs(h.PieChart,{children:[e.jsx(h.Pie,{data:g,cx:"50%",cy:"50%",innerRadius:y,outerRadius:S,paddingAngle:2,dataKey:"value",nameKey:"name",onMouseEnter:(u,m)=>d(m),onMouseLeave:()=>d(null),shape:(u,m)=>{var N;return e.jsx(h.Sector,{...u,fill:(N=g[m])==null?void 0:N.color,stroke:"transparent",opacity:a!==null&&a!==m?.4:1})},children:i&&e.jsx(h.Label,{content:e.jsx(A,{activeIndex:a,chartData:g,formatValue:s,total:j})})}),!i&&e.jsx(h.Tooltip,{content:e.jsx(k,{formatValue:s,total:j})})]})})}),e.jsx("div",{className:p.cn(x?"flex-1 min-w-0":""),children:e.jsx(C,{chartData:g,total:j,formatValue:s,activeIndex:a,onHover:d})})]})]})}exports.DonutChart=L;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react/jsx-runtime"),w=require("react"),h=require("recharts"),p=require("../utils.cjs");function z(n){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(n){for(const s in n)if(s!=="default"){const l=Object.getOwnPropertyDescriptor(n,s);Object.defineProperty(t,s,l.get?l:{enumerable:!0,get:()=>n[s]})}}return t.default=n,Object.freeze(t)}const N=z(w),b=Array.from({length:8},(n,t)=>`var(--chart-${t+1})`);function A(n){return new Intl.NumberFormat("pt-BR",{style:"currency",currency:"BRL"}).format(n)}function D({layout:n,chartSize:t}){const s=[1,2,3].map(l=>e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsx("div",{className:"w-2.5 h-2.5 rounded-full bg-muted shrink-0"}),e.jsx("div",{className:"h-3 bg-muted rounded flex-1"})]},l));return n==="horizontal"?e.jsxs("div",{className:"flex items-center gap-6 w-full animate-pulse",children:[e.jsx("div",{className:"rounded-full bg-muted shrink-0",style:{width:t,height:t}}),e.jsx("div",{className:"flex flex-col gap-2 flex-1",children:s})]}):e.jsxs("div",{className:"flex flex-col items-center justify-center w-full animate-pulse gap-4",children:[e.jsx("div",{className:"rounded-full bg-muted",style:{width:140,height:140}}),e.jsx("div",{className:"flex flex-col gap-2 w-full max-w-50",children:s})]})}function M(){return e.jsxs("div",{className:"flex flex-col items-center justify-center w-full h-full text-muted-foreground gap-2",children:[e.jsx("div",{className:"rounded-full border-4 border-dashed border-muted",style:{width:100,height:100}}),e.jsx("span",{className:"text-sm",children:"Sem dados para exibir"})]})}function R({active:n,payload:t,formatValue:s,total:l}){if(!n||!(t!=null&&t.length))return null;const c=t[0],r=l>0?(c.value/l*100).toFixed(1):"0.0";return e.jsxs("div",{className:"bg-popover border border-border rounded shadow-lg p-2 text-xs min-w-35",children:[e.jsx("div",{className:"font-medium mb-1",children:c.name}),e.jsxs("div",{className:"flex justify-between gap-4",children:[e.jsx("span",{className:"text-muted-foreground",children:"Valor"}),e.jsx("span",{className:"font-mono",children:s(c.value)})]}),e.jsxs("div",{className:"flex justify-between gap-4",children:[e.jsx("span",{className:"text-muted-foreground",children:"%"}),e.jsxs("span",{className:"font-mono",children:[r,"%"]})]})]})}function k({viewBox:n,activeIndex:t,chartData:s,formatValue:l,total:c}){const r=(n==null?void 0:n.cx)??0,i=(n==null?void 0:n.cy)??0,o=t!==null&&t>=0?s[t]:null;if(o){const a=c>0?(o.value/c*100).toFixed(1):"0.0",d=13,j=o.name.length>d?o.name.substring(0,d-1)+"…":o.name;return e.jsxs("g",{children:[e.jsx("text",{x:r,y:i-14,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:10,fill:"var(--muted-foreground)"},children:j}),e.jsx("text",{x:r,y:i+2,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:11,fontWeight:700,fill:o.color},children:l(o.value)}),e.jsxs("text",{x:r,y:i+18,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:11,fill:"var(--muted-foreground)"},children:[a,"%"]})]})}return e.jsxs("g",{children:[e.jsx("text",{x:r,y:i-8,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:10,fill:"var(--muted-foreground)"},children:"Total"}),e.jsx("text",{x:r,y:i+8,textAnchor:"middle",dominantBaseline:"middle",style:{fontSize:13,fontWeight:700,fill:"currentColor"},children:l(c)})]})}function C({chartData:n,total:t,formatValue:s,activeIndex:l,onHover:c}){return e.jsxs("div",{className:"flex flex-col gap-1.5",children:[n.map((r,i)=>{const o=t>0?(r.value/t*100).toFixed(1):"0.0",a=l===i,d=l!==null&&!a;return e.jsxs("div",{className:"flex items-center gap-2 text-xs cursor-default rounded px-1 py-0.5 transition-opacity",style:{opacity:d?.4:1},onMouseEnter:()=>c(i),onMouseLeave:()=>c(null),children:[e.jsx("span",{className:"inline-block w-2.5 h-2.5 rounded-full shrink-0 transition-transform",style:{background:r.color,transform:a?"scale(1.3)":"scale(1)"}}),e.jsx("span",{className:"flex-1 truncate text-muted-foreground",children:r.name}),e.jsx("span",{className:"font-mono text-foreground",children:s(r.value)}),e.jsxs("span",{className:"text-muted-foreground w-10.5 text-right",children:[o,"%"]})]},i)}),e.jsxs("div",{className:"flex items-center gap-2 text-xs border-t border-border pt-1.5 mt-0.5",children:[e.jsx("span",{className:"flex-1 font-medium",children:"Total"}),e.jsx("span",{className:"font-mono font-semibold",children:s(t)})]})]})}function L({data:n,title:t,formatValue:s=A,className:l,isLoading:c=!1,layout:r="vertical",activeLabel:i=!1,chartSize:o}){const[a,d]=N.useState(null),j=N.useMemo(()=>n.reduce((u,m)=>u+m.value,0),[n]),g=N.useMemo(()=>n.map((u,m)=>({name:u.label,value:u.value,color:u.color??b[m%b.length]})),[n]),x=r==="horizontal",f=o??(x?140:220),y=x?Math.round(f*.34):55,S=x?Math.round(f*.51):85;return e.jsxs("div",{className:p.cn("flex flex-col gap-4 w-full",l),children:[t&&e.jsx("div",{className:"text-sm font-semibold text-foreground",children:t}),c?e.jsx(D,{layout:r,chartSize:f}):n.length===0?e.jsx(M,{}):e.jsxs("div",{className:p.cn(x?"flex items-center gap-4":"flex flex-col gap-4"),children:[e.jsx("div",{className:"shrink-0",style:x?{width:f,height:f}:{width:"100%",height:f},children:e.jsx(h.ResponsiveContainer,{width:"100%",height:"100%",children:e.jsxs(h.PieChart,{children:[e.jsx(h.Pie,{data:g,cx:"50%",cy:"50%",innerRadius:y,outerRadius:S,paddingAngle:2,dataKey:"value",nameKey:"name",onMouseEnter:(u,m)=>d(m),onMouseLeave:()=>d(null),shape:(u,m)=>{var v;return e.jsx(h.Sector,{...u,fill:(v=g[m])==null?void 0:v.color,stroke:"transparent",opacity:a!==null&&a!==m?.4:1})},children:i&&e.jsx(h.Label,{content:e.jsx(k,{activeIndex:a,chartData:g,formatValue:s,total:j})})}),!i&&e.jsx(h.Tooltip,{content:e.jsx(R,{formatValue:s,total:j})})]})})}),e.jsx("div",{className:p.cn(x?"flex-1 min-w-0":""),children:e.jsx(C,{chartData:g,total:j,formatValue:s,activeIndex:a,onHover:d})})]})]})}exports.DonutChart=L;
 //# sourceMappingURL=donut-chart.cjs.map