@iclips/ui 2.0.3 → 3.0.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iclips/ui",
-  "version": "2.0.3",
+  "version": "3.0.0",
   "description": "Design system da iClips — componentes React sobre Radix UI + Tailwind v4, paleta #7F26BF",
   "author": "iclipsbr",
   "license": "MIT",
@@ -47,7 +47,9 @@
     "scripts/codemod-v2-toast.mjs",
     "README.md",
     "LICENSE",
-    "MIGRATION-v2.md"
+    "MIGRATION-v2.md",
+    "MIGRATION-v3.md",
+    "scripts/check-colors.mjs"
   ],
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -169,7 +171,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 .",

package/scripts/check-colors.mjs

@@ -0,0 +1,208 @@
+// Aponta cor crua — `bg-gray-100`, `text-purple-600`, `bg-zinc-900`, `var(--teal-500)` —
+// e sugere o token semântico da paleta iClips. Não altera nenhum arquivo.
+//
+// Na lib roda no `npm run lint` (sem argumentos varre `src`). Num app que usa a
+// @iclips/ui, depois de subir para a 3.0.0:
+//
+//   node node_modules/@iclips/ui/scripts/check-colors.mjs src
+//
+// Exit: 0 nada encontrado · 1 encontrou cor crua · 2 algum caminho não pôde ser
+// lido (e nada foi encontrado). Uma linha com `check-colors-ignore` é pulada —
+// para documentação que precisa mostrar o que não fazer.
+//
+//   node scripts/check-colors.mjs --self-test   checa as regras e o CLI
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+
+// Paleta padrão do Tailwind v4 — nenhuma gera classe com o preset da 3.0.0.
+const FAMILIAS = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+const PREFIXOS = "bg|text|border(?:-[xytrblse])?|ring(?:-offset)?|outline|fill|stroke|from|via|to|divide|placeholder|caret|accent|decoration|shadow";
+const CLASSE = new RegExp(`(?<![\\w-])((?:[\\w\\[\\]&=.-]+:)*(${PREFIXOS})-(${FAMILIAS})-(\\d{2,3})(?:\\/\\d+)?)(?![\\w-])`, "g");
+// Custom properties que deixaram de existir na 3.0.0.
+const VAR_REMOVIDA = /var\(--((?:pink|blue|teal|orange)-\d+|purple-600|(?:red|green|cyan)-(?:50|100|200|500|700)|yellow-(?:50|100|200|700)|cta(?:-foreground)?)\)/g;
+
+const EXTENSOES = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mdx", ".html", ".vue", ".svelte", ".css"]);
+const PULAR_DIR = new Set(["node_modules", "dist", ".git", "storybook-static", "coverage"]);
+
+const ESTADO = { red: "destructive", green: "success", emerald: "success", yellow: "warning", amber: "warning", cyan: "info", sky: "info", blue: "info" };
+const NEUTRO = new Set(["slate", "gray", "zinc", "neutral", "stone"]);
+
+export function sugerir(classe) {
+  const m = new RegExp(`^(?:.*:)?(${PREFIXOS})-(${FAMILIAS})-(\\d{2,3})`).exec(classe);
+  if (!m) return null;
+  const [, prefixo, familia, degrauTxt] = m;
+  const degrau = Number(degrauTxt);
+  const base = prefixo.replace(/-[xytrblse]$/, "");
+  if (NEUTRO.has(familia)) {
+    if (base === "bg") return degrau <= 50 ? "bg-background ou bg-muted/40" : degrau <= 200 ? "bg-muted" : degrau >= 700 ? "bg-card (superfície escura)" : "bg-muted";
+    if (base === "text") return degrau >= 700 ? "text-foreground" : degrau >= 400 ? "text-muted-foreground" : "text-muted-foreground (400 ou mais claro nunca em texto)";
+    if (base === "border" || base === "divide" || base === "outline") return degrau >= 300 ? `${base}-input` : `${base}-border`;
+    if (base === "ring") return "ring-ring";
+  }
+  if (familia === "purple") {
+    if (base === "bg") return degrau <= 100 ? "bg-secondary (seleção)" : "bg-primary";
+    if (base === "text") return degrau >= 700 ? "text-secondary-foreground" : "text-primary";
+    if (base === "ring") return "ring-ring";
+    if (base === "border" || base === "outline") return `${base}-primary`;
+  }
+  const estado = ESTADO[familia];
+  if (estado) {
+    if (base === "text") return `text-${estado}-emphasis`;
+    if (base === "bg") return degrau <= 100 ? `bg-${estado}/10` : `bg-${estado}`;
+    if (base === "border") return `border-${estado}/20`;
+    return `${base}-${estado}`;
+  }
+  return "sem equivalente — a paleta iClips não tem esta cor; use um token semântico ou var(--chart-N) em dados";
+}
+
+export function varrerTexto(texto) {
+  const achados = [];
+  texto.split(/\r?\n/).forEach((linha, i) => {
+    if (linha.includes("check-colors-ignore")) return;
+    for (const m of linha.matchAll(CLASSE)) achados.push({ linha: i + 1, classe: m[1], sugestao: sugerir(m[1]) });
+    for (const m of linha.matchAll(VAR_REMOVIDA)) achados.push({ linha: i + 1, classe: m[0], sugestao: "removida na 3.0.0 — use o token semântico" });
+  });
+  return achados;
+}
+
+function arquivos(caminho, erros) {
+  let st;
+  try {
+    st = statSync(caminho);
+  } catch {
+    erros.push(caminho);
+    return [];
+  }
+  if (st.isFile()) return [caminho];
+  const out = [];
+  for (const e of readdirSync(caminho, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      if (!PULAR_DIR.has(e.name)) out.push(...arquivos(join(caminho, e.name), erros));
+    } else if (EXTENSOES.has(extname(e.name)) && !/\.test\.[jt]sx?$/.test(e.name)) {
+      out.push(join(caminho, e.name));
+    }
+  }
+  return out;
+}
+
+export function executar(caminhos, { out = console.log, err = console.error } = {}) {
+  const erros = [];
+  let total = 0;
+  for (const alvo of caminhos.length ? caminhos : ["src"]) {
+    for (const f of arquivos(alvo, erros)) {
+      let texto;
+      try {
+        texto = readFileSync(f, "utf8");
+      } catch {
+        erros.push(f);
+        continue;
+      }
+      for (const a of varrerTexto(texto)) {
+        total++;
+        out(`${relative(process.cwd(), f).replace(/\\/g, "/")}:${a.linha}  ${a.classe}  → ${a.sugestao}`);
+      }
+    }
+  }
+  for (const e of erros) err(`check-colors: não foi possível ler ${e}`);
+  if (total) err(`check-colors: ${total} cor(es) crua(s) — a paleta iClips só aceita tokens semânticos.`);
+  return total ? 1 : erros.length ? 2 : 0;
+}
+
+async function selfTest() {
+  const assert = (await import("node:assert/strict")).default;
+  const { mkdtempSync, writeFileSync, statSync: st, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { spawnSync } = await import("node:child_process");
+  const { fileURLToPath } = await import("node:url");
+
+  // detecção: toda família × todo prefixo base, com variante e opacidade
+  // lista literal (não derivada da regex): renomear ou esquecer uma família no FAMILIAS falha aqui
+  const familias = ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"];
+  assert.deepEqual(FAMILIAS.split("|"), familias, "FAMILIAS cobre exatamente a paleta padrão do Tailwind v4");
+  const prefixos = ["bg", "text", "border", ...["x", "y", "t", "r", "b", "l", "s", "e"].map((l) => `border-${l}`), "ring", "ring-offset", "outline", "fill", "stroke", "from", "via", "to", "divide", "placeholder", "caret", "accent", "decoration", "shadow"];
+  assert.equal(familias.length, 22, "22 famílias do Tailwind");
+  for (const f of familias)
+    for (const p of prefixos) {
+      const c = `${p}-${f}-500`;
+      const achados = varrerTexto(`<div className="hover:${c}/40" />`);
+      assert.equal(achados.length, 1, `detecta ${c}`);
+      assert.equal(achados[0].classe, `hover:${c}/40`, `cita a classe inteira: ${c}`);
+    }
+  for (const ok of ["bg-primary", "text-muted-foreground", "bg-black/50", "text-white", "bg-white", "border-border", "text-success-emphasis", "bg-chart-2/15", "bg-[#24292F]", "grayscale", "text-gray", "blue-500", "bg-gray-5000"])
+    assert.equal(varrerTexto(`<div className="${ok}" />`).length, 0, `não acusa ${ok}`);
+  assert.equal(varrerTexto('style={{ color: "var(--teal-500)" }}').length, 1, "var removida");
+  assert.equal(varrerTexto('style={{ color: "var(--cta)" }}').length, 1, "var --cta removida");
+  assert.equal(varrerTexto('style={{ color: "var(--gray-100)" }}').length, 0, "var mantida");
+  assert.equal(varrerTexto('<p className="bg-teal-500" /> {/* check-colors-ignore */}').length, 0, "ignore");
+
+  // sugestões: um caso por ramo de sugerir(); as linhas marcadas (guia) espelham a tabela do MIGRATION-v3.md
+  const tabela = {
+    // neutros
+    "bg-gray-50": "bg-background ou bg-muted/40", /* guia */ "bg-gray-100": "bg-muted", /* guia */ "bg-gray-200": "bg-muted",
+    "bg-gray-400": "bg-muted", "bg-zinc-900": "bg-card (superfície escura)", /* guia */ "bg-gray-700": "bg-card (superfície escura)",
+    "text-gray-800": "text-foreground", /* guia */ "text-gray-900": "text-foreground", "text-gray-500": "text-muted-foreground", /* guia */
+    "text-gray-400": "text-muted-foreground", "text-gray-300": "text-muted-foreground (400 ou mais claro nunca em texto)",
+    "border-gray-200": "border-border", /* guia */ "border-gray-100": "border-border", "border-gray-300": "border-input", /* guia */
+    "divide-gray-200": "divide-border", "outline-slate-300": "outline-input", "ring-gray-300": "ring-ring",
+    // roxo = ação
+    "bg-purple-500": "bg-primary", /* guia */ "bg-purple-600": "bg-primary", "bg-purple-50": "bg-secondary (seleção)", /* guia */ "bg-purple-100": "bg-secondary (seleção)",
+    "text-purple-600": "text-primary", /* guia */ "text-purple-500": "text-primary", "text-purple-700": "text-secondary-foreground", /* guia */
+    "border-purple-500": "border-primary", /* guia */ "ring-purple-500": "ring-ring", /* guia */ "outline-purple-400": "outline-primary",
+    // estado
+    "text-red-600": "text-destructive-emphasis", /* guia */ "text-green-600": "text-success-emphasis", "text-yellow-700": "text-warning-emphasis", "text-blue-600": "text-info-emphasis",
+    "text-amber-700": "text-warning-emphasis", "text-emerald-600": "text-success-emphasis", "text-sky-600": "text-info-emphasis", "text-cyan-600": "text-info-emphasis",
+    "bg-red-600": "bg-destructive", /* guia */ "bg-red-50": "bg-destructive/10", "bg-green-100": "bg-success/10", "bg-blue-500": "bg-info",
+    "border-red-200": "border-destructive/20", /* guia */ "fill-green-600": "fill-success", "hover:bg-gray-100": "bg-muted", "dark:bg-zinc-900": "bg-card (superfície escura)",
+  };
+  for (const [c, esperado] of Object.entries(tabela)) assert.equal(sugerir(c), esperado, c);
+  for (const semEquivalente of ["bg-teal-500", "text-orange-600", "bg-pink-500", "text-indigo-500", "bg-violet-500", "text-violet-600", "border-rose-300", "fill-lime-400", "bg-fuchsia-500"])
+    assert.match(sugerir(semEquivalente), /^sem equivalente/, `${semEquivalente} sem equivalente`);
+
+  // CLI de verdade
+  const script = fileURLToPath(import.meta.url);
+  const run = (args, cwd) => spawnSync(process.execPath, [script, ...args], { cwd, encoding: "utf8" });
+  const dir = mkdtempSync(join(tmpdir(), "check-colors-"));
+  try {
+    const limpo = join(dir, "limpo");
+    const sujo = join(dir, "sujo");
+    for (const d of [limpo, sujo]) spawnSync(process.execPath, ["-e", `require("fs").mkdirSync(${JSON.stringify(d)})`]);
+    writeFileSync(join(limpo, "a.tsx"), '<div className="bg-primary text-white" />\n');
+    const alvo = join(sujo, "b.tsx");
+    writeFileSync(alvo, 'const x = 1;\n<div className="bg-teal-500" />\n<p className="text-gray-600" />\n');
+    writeFileSync(join(sujo, "b.test.tsx"), '<div className="bg-teal-500" />\n');
+    const antes = { txt: readFileSync(alvo, "utf8"), mtime: st(alvo).mtimeMs };
+
+    let r = run([limpo], dir);
+    assert.equal(r.status, 0, "dir limpo → exit 0");
+
+    r = run([sujo], dir);
+    assert.equal(r.status, 1, "dir sujo → exit 1");
+    const linhas = r.stdout.trim().split("\n");
+    assert.equal(linhas.length, 2, "lista todas as ocorrências (e ignora *.test.*)");
+    assert.match(linhas[0], /sujo\/b\.tsx:2 {2}bg-teal-500 {2}→ sem equivalente/, "cita arquivo:linha e a classe");
+    assert.match(linhas[1], /sujo\/b\.tsx:3 {2}text-gray-600 {2}→ text-muted-foreground/, "sugere o token");
+
+    assert.equal(readFileSync(alvo, "utf8"), antes.txt, "não altera o conteúdo");
+    assert.equal(st(alvo).mtimeMs, antes.mtime, "não toca o arquivo");
+
+    r = run([join(dir, "nao-existe")], dir);
+    assert.equal(r.status, 2, "caminho ilegível sem achado → exit 2");
+    assert.match(r.stderr, /não foi possível ler/, "avisa no stderr");
+    r = run([join(dir, "nao-existe"), sujo], dir);
+    assert.equal(r.status, 1, "ilegível + achado → continua e sai 1");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // o lint da lib encadeia o script
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  assert.match(pkg.scripts.lint, /node scripts\/check-colors\.mjs/, "npm run lint roda check-colors");
+
+  console.log("check-colors: self-test ok");
+}
+
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop())) {
+  if (process.argv.includes("--self-test")) await selfTest();
+  else process.exitCode = executar(process.argv.slice(2));
+}