orbital-ds 0.1.0 → 0.2.0

package/dist/ui/toggle-group.js

@@ -0,0 +1,77 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { ToggleGroup as ToggleGroupPrimitive } from "@base-ui/react/toggle-group";
+import { cn } from "../lib/utils";
+import { toggleVariants } from "./toggle";
+const ToggleGroupContext = React.createContext({
+  size: "default",
+  variant: "default",
+  spacing: 2,
+  orientation: "horizontal"
+});
+function ToggleGroup({
+  className,
+  variant,
+  size,
+  spacing = 2,
+  orientation = "horizontal",
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    ToggleGroupPrimitive,
+    {
+      "data-slot": "toggle-group",
+      "data-variant": variant,
+      "data-size": size,
+      "data-spacing": spacing,
+      "data-orientation": orientation,
+      style: { "--gap": spacing },
+      className: cn(
+        "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] data-[spacing=0]:data-[variant=outline]:rounded-control data-vertical:flex-col data-vertical:items-stretch",
+        className
+      ),
+      ...props,
+      children: /* @__PURE__ */ jsx(
+        ToggleGroupContext.Provider,
+        {
+          value: { variant, size, spacing, orientation },
+          children
+        }
+      )
+    }
+  );
+}
+function ToggleGroupItem({
+  className,
+  children,
+  variant = "default",
+  size = "default",
+  ...props
+}) {
+  const context = React.useContext(ToggleGroupContext);
+  return /* @__PURE__ */ jsx(
+    TogglePrimitive,
+    {
+      "data-slot": "toggle-group-item",
+      "data-variant": context.variant || variant,
+      "data-size": context.size || size,
+      "data-spacing": context.spacing,
+      className: cn(
+        "shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-3 group-data-[spacing=0]/toggle-group:shadow-none focus:z-(--ds-z-raised) focus-visible:z-(--ds-z-raised) group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-2.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-2.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-3xl group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-3xl group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-3xl group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-3xl data-[state=on]:bg-muted group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t",
+        toggleVariants({
+          variant: context.variant || variant,
+          size: context.size || size
+        }),
+        className
+      ),
+      ...props,
+      children
+    }
+  );
+}
+export {
+  ToggleGroup,
+  ToggleGroupItem
+};

package/dist/ui/toggle.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { Toggle as Toggle$1 } from '@base-ui/react/toggle';
+import { VariantProps } from 'class-variance-authority';
+
+declare const toggleVariants: (props?: ({
+    variant?: "default" | "outline" | null | undefined;
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+declare function Toggle({ className, variant, size, ...props }: Toggle$1.Props & VariantProps<typeof toggleVariants>): React.JSX.Element;
+
+export { Toggle, toggleVariants };

package/dist/ui/toggle.js

@@ -0,0 +1,43 @@
+import { jsx } from "react/jsx-runtime";
+import { Toggle as TogglePrimitive } from "@base-ui/react/toggle";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/utils";
+const toggleVariants = cva(
+  "group/toggle inline-flex items-center justify-center gap-1 rounded-control text-sm font-medium whitespace-nowrap transition-colors outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-(length:--ds-ring-width) focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline: "border border-input bg-transparent hover:bg-muted"
+      },
+      size: {
+        default: "h-9 min-w-9 px-3 has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5",
+        sm: "h-8 min-w-8 px-3 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        lg: "h-10 min-w-10 px-4 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3"
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default"
+    }
+  }
+);
+function Toggle({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(
+    TogglePrimitive,
+    {
+      "data-slot": "toggle",
+      className: cn(toggleVariants({ variant, size, className })),
+      ...props
+    }
+  );
+}
+export {
+  Toggle,
+  toggleVariants
+};

package/dist/ui/tooltip.js

@@ -36,19 +36,19 @@ function TooltipContent({
       alignOffset,
       side,
       sideOffset,
-      className: "isolate z-(--z-overlay)",
+      className: "isolate z-(--ds-z-overlay)",
       children: /* @__PURE__ */ jsxs(
         TooltipPrimitive.Popup,
         {
           "data-slot": "tooltip-content",
           className: cn(
-            "z-(--z-overlay) inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-2xl bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-(--z-overlay) **:data-[slot=kbd]:rounded-control data-starting-style:animate-in data-starting-style:fade-in-0 data-starting-style:zoom-in-95 data-ending-style:animate-out data-ending-style:fade-out-0 data-ending-style:zoom-out-95",
+            "z-(--ds-z-overlay) inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-2xl bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-(--ds-z-overlay) **:data-[slot=kbd]:rounded-control data-starting-style:animate-in data-starting-style:fade-in-0 data-starting-style:zoom-in-95 data-ending-style:animate-out data-ending-style:fade-out-0 data-ending-style:zoom-out-95",
             className
           ),
           ...props,
           children: [
             children,
-            /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { className: "z-(--z-overlay) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=left]:translate-x-[-1.5px] data-[side=right]:translate-x-[1.5px]" })
+            /* @__PURE__ */ jsx(TooltipPrimitive.Arrow, { className: "z-(--ds-z-overlay) size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=left]:translate-x-[-1.5px] data-[side=right]:translate-x-[1.5px]" })
           ]
         }
       )

package/docs/CONTRACT.md

@@ -0,0 +1,113 @@
+# Contrato de tema de orbital-ds
+
+Un **tema** es un fichero CSS (`themes/<nombre>.css`) que da valores a un conjunto
+cerrado de variables. Los componentes **solo** leen esas variables: ninguno lleva
+colores, medidas, sombras, capas ni duraciones escritos a mano. Por eso cambiar de
+tema cambia todo el aspecto sin tocar un componente.
+
+El contrato vive en [`contract.json`](../contract.json) y lo comprueba
+`pnpm doctor` (que forma parte de `pnpm verify`): si a un tema le falta un token
+obligatorio, el build falla.
+
+## Cómo se usa
+
+```css
+@import 'tailwindcss';
+@import 'tw-animate-css';
+
+@import 'orbital-ds/styles.css';        /* 1. la ESTRUCTURA común */
+@import 'orbital-ds/themes/qratia.css'; /* 2. un TEMA (después, para poder sobrescribir) */
+
+@source '../node_modules/orbital-ds/dist'; /* que Tailwind vea las clases del paquete */
+```
+
+El tema se importa **después** de la estructura: así puede sobrescribir también la
+escala de radios y las sombras, que viven en `@theme`.
+
+Para ajustar un valor sin crear un tema, se sobrescribe la variable al final:
+
+```css
+:root { --primary: oklch(0.55 0.2 260); }
+```
+
+## Tokens obligatorios (todo tema, en `:root`)
+
+| Grupo | Tokens |
+|---|---|
+| Forma | `--radius` |
+| Superficies y texto | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground` |
+| Acción | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
+| Atenuado | `--muted`, `--muted-foreground` |
+| Destructivo | `--destructive`, `--destructive-foreground` |
+| Líneas y foco | `--border`, `--input`, `--ring` |
+| Gráficos | `--chart-1` … `--chart-5` |
+| Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
+| Estados | `--danger`, `--warning`, `--success`, `--info`, `--neutral` y cada uno con su `-soft` |
+| Texto acentuado | `--link`, `--link-hover` |
+| Superficie hundida | `--inset`, `--inset-foreground` |
+| Marca | `--brand`, `--brand-bright` |
+| Tipografía | `--font-sans` (en `:root` o en `@theme`) |
+
+En `.dark` se redefine lo que cambie; `doctor` avisa (no falla) de los tokens
+principales que se hereden de la piel clara.
+
+`--destructive` es el rojo de **acciones** (botón de borrar); `--danger` es el rojo
+de **estado** (etiqueta de nivel crítico). Pueden coincidir, pero son huecos distintos.
+
+## Tokens con valor por defecto (el tema los puede cambiar)
+
+Los define la estructura con un valor neutro; un tema los sobrescribe si quiere.
+
+| Hueco | Variables |
+|---|---|
+| Radios semánticos | `--radius-control`, `--radius-overlay` (y la rampa `--radius-sm … 2xl`, derivada de `--radius`) |
+| Sombras | `--shadow-card`, `--shadow-card-hover`, `--shadow-control`, `--shadow-raised`, `--shadow-overlay`, `--shadow-popover` |
+| Altura de controles | `--ds-control-h-sm`, `-md`, `-lg` |
+| Espaciado interno | `--ds-card-spacing`, `--ds-card-spacing-sm`, `--ds-field-px`, `--ds-cell-p`, `--ds-overlay-p`, `--ds-overlay-gap`, `--ds-popover-p`, `--ds-menu-p`, `--ds-menu-item-px`, `--ds-menu-item-py`, `--ds-button-px-sm/md/lg`, `--ds-badge-px` |
+| Capas | `--ds-z-raised`, `--ds-z-sticky`, `--ds-z-overlay` |
+| Movimiento | `--ds-motion-fast`, `--ds-motion-base`, `--ds-motion-slow`, `--ds-motion-blink` |
+| Foco | `--ds-ring-width` |
+| Velo | `--color-scrim` |
+| **Materiales** | `--ds-card-backdrop`, `--ds-overlay-backdrop`, `--ds-field-backdrop`, `--ds-sidebar-backdrop` (un `backdrop-filter` completo; por defecto `none`) y `--ds-page-backdrop` (un `background-image` para el fondo de la página; por defecto `none`) |
+
+Los **materiales** son lo que hace posible un tema de cristal como `zyro`: con valores
+neutros no hay efecto ni coste; con `blur(28px) saturate(180%)` las superficies se
+vuelven translúcidas.
+
+## Reglas de nombres
+
+- Todo en **inglés**: tokens, props y valores de variantes.
+- Los nombres que Tailwind convierte en utilidades (`--color-*`, `--radius-*`,
+  `--shadow-*`) siguen su convención y **no llevan prefijo**. El resto de variables
+  propias llevan el prefijo **`--ds-`** para no chocar con las de una app.
+- Un componente que necesite un hueco nuevo **añade el token** con un valor que deje
+  el aspecto como estaba; nunca escribe el valor en el componente.
+
+## Qué comprueba `pnpm doctor`
+
+1. **Contrato**: cada tema define todos los tokens obligatorios.
+2. **Repetidos**: ninguna variable se define dos veces en el mismo bloque.
+3. **Valores fijos** en `src/ui/*.tsx`: colores literales (hex, `rgb()`, `oklch()`
+   salvo derivados de un token), `z-<n>`, `duration-<n>`, `bg-black`/`bg-white`,
+   sombras de la escala de Tailwind, `text-[<n>px]`, radios fuera de la rampa y
+   colores de la paleta de Tailwind.
+
+También se puede pasar el CSS de una app: `orbital-ds-doctor --css src/styles.css`
+(detecta variables repetidas).
+
+## Crear un tema nuevo
+
+1. Copia `themes/qratia.css` (o `zyro.css`) a `themes/<nombre>.css`.
+2. Cambia los valores; no quites ninguno.
+3. `pnpm doctor`: te dice qué falta.
+4. Opcional: usa los materiales para dar cristal, relieve o un fondo propio.
+
+Se puede partir de un tema de shadcn (por ejemplo exportado desde tweakcn): usa los
+mismos nombres estándar (`--background`, `--primary`…). Habrá que añadir los tokens
+propios (`danger`, `warning`, `success`, `info`, `neutral`, `link`, `inset`, `brand`).
+
+## Cosas que un tema NO puede cambiar
+
+La **anatomía** de un componente (otro diseño de sidebar o de tarjeta) no es un valor,
+es estructura: se resuelve con variantes del componente. Un fondo animado (como la
+malla WebGL de zyro) es código, no una variable: se ofrece como componente opcional.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orbital-ds",
-  "version": "0.1.0",
-  "description": "Sistema de diseño genérico: estructura común (tokens semánticos, capa base) + temas intercambiables + primitivos sobre Base UI y Tailwind v4.",
+  "version": "0.2.0",
+  "description": "Sistema de diseño genérico: estructura común + temas intercambiables (qratia, zyro) + ~60 componentes sobre Base UI y Tailwind v4, con contrato de tema verificable.",
   "keywords": [
     "design-system",
     "design-tokens",
@@ -18,6 +18,9 @@
   ],
   "files": [
     "dist",
+    "scripts/doctor.mjs",
+    "contract.json",
+    "docs",
     "README.md",
     "LICENSE"
   ],
@@ -36,16 +39,18 @@
       "types": "./dist/hooks/*.d.ts",
       "import": "./dist/hooks/*.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./contract.json": "./contract.json"
   },
   "scripts": {
     "build": "tsup && node scripts/copy-css.mjs",
     "dev": "tsup --watch --onSuccess \"node scripts/copy-css.mjs\"",
     "typecheck": "tsc --noEmit",
-    "verify": "pnpm typecheck && pnpm build"
+    "verify": "pnpm doctor && pnpm typecheck && pnpm build",
+    "doctor": "node scripts/doctor.mjs"
   },
   "peerDependencies": {
-    "@base-ui/react": ">=1.7",
+    "@base-ui/react": ">=1.9",
     "class-variance-authority": ">=0.7",
     "clsx": ">=2",
     "lucide-react": ">=0.400",
@@ -56,7 +61,14 @@
     "tw-animate-css": ">=1.3",
     "next-themes": ">=0.4",
     "recharts": ">=3",
-    "sonner": ">=2"
+    "sonner": ">=2",
+    "@shadcn/react": ">=0.3",
+    "cmdk": ">=1.1",
+    "date-fns": ">=4",
+    "embla-carousel-react": ">=8.6",
+    "input-otp": ">=1.5",
+    "react-day-picker": ">=10",
+    "react-resizable-panels": ">=4"
   },
   "peerDependenciesMeta": {
     "next-themes": {
@@ -67,10 +79,31 @@
     },
     "sonner": {
       "optional": true
+    },
+    "@shadcn/react": {
+      "optional": true
+    },
+    "cmdk": {
+      "optional": true
+    },
+    "date-fns": {
+      "optional": true
+    },
+    "embla-carousel-react": {
+      "optional": true
+    },
+    "input-otp": {
+      "optional": true
+    },
+    "react-day-picker": {
+      "optional": true
+    },
+    "react-resizable-panels": {
+      "optional": true
     }
   },
   "devDependencies": {
-    "@base-ui/react": "^1.7.0",
+    "@base-ui/react": "^1.9.0",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "class-variance-authority": "^0.7.1",
@@ -85,11 +118,16 @@
     "tailwindcss": "^4.1.18",
     "tsup": "^8.5.0",
     "tw-animate-css": "^1.3.6",
-    "typescript": "^5.9.0"
+    "typescript": "^5.9.0",
+    "@shadcn/react": "^0.3.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
+    "embla-carousel-react": "^8.6.0",
+    "input-otp": "^1.5.0",
+    "react-day-picker": "^10.0.2",
+    "react-resizable-panels": "^4.14.4"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
+  "bin": {
+    "orbital-ds-doctor": "./scripts/doctor.mjs"
   }
 }

package/scripts/doctor.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * orbital-ds doctor — comprueba que el sistema se cumple.
+ *
+ *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
+ *      contract.json (y la fuente `--font-sans`). En .dark solo avisa.
+ *   2. REPETIDOS: ninguna variable CSS se define dos veces en el mismo bloque.
+ *   3. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
+ *      duraciones ni sombras a mano; todo sale de tokens.
+ *
+ * Uso:
+ *   node scripts/doctor.mjs                 # temas y componentes del paquete
+ *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (contrato + repetidos)
+ *
+ * Sale con código 1 si hay errores (los avisos no fallan).
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
+
+const errors = [];
+const warnings = [];
+const read = (p) => readFileSync(p, 'utf8');
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** Devuelve el cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
+function blocks(css, selectorRe) {
+  const out = [];
+  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    const start = i;
+    while (i < css.length && depth > 0) {
+      if (css[i] === '{') depth++;
+      else if (css[i] === '}') depth--;
+      i++;
+    }
+    out.push(css.slice(start, i - 1));
+    re.lastIndex = i;
+  }
+  return out;
+}
+
+const definedVars = (body) => [...body.matchAll(/(^|[;{\s])(--[a-z0-9-]+)\s*:/gi)].map((m) => m[2]);
+
+function checkTheme(file, label) {
+  const css = stripComments(read(file));
+  const roots = blocks(css, /(?:^|[\s}])\:root/);
+  const darks = blocks(css, /(?:^|[\s}])\.dark/);
+  const themeBlocks = blocks(css, /@theme\s+inline/);
+
+  const rootVars = new Set(roots.flatMap(definedVars));
+  const themeVars = new Set(themeBlocks.flatMap(definedVars));
+  const darkVars = new Set(darks.flatMap(definedVars));
+
+  for (const t of contract.root) {
+    if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
+  }
+  for (const f of contract.fonts) {
+    if (!rootVars.has(`--${f}`) && !themeVars.has(`--${f}`)) {
+      errors.push(`${label}: falta la fuente --${f} (en :root o @theme)`);
+    }
+  }
+  if (darks.length) {
+    for (const t of contract.dark.avisar_si_falta) {
+      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
+    }
+  } else {
+    warnings.push(`${label}: no define piel .dark`);
+  }
+
+  // Repetidos dentro de un mismo bloque
+  for (const [name, list] of [['@theme', themeBlocks], [':root', roots], ['.dark', darks]]) {
+    list.forEach((body, idx) => {
+      const seen = new Map();
+      for (const v of definedVars(body)) seen.set(v, (seen.get(v) ?? 0) + 1);
+      for (const [v, n] of seen) {
+        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${name} (#${idx + 1})`);
+      }
+    });
+  }
+}
+
+// 1+2) temas del paquete
+const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
+for (const f of readdirSync(themesDir).filter((n) => n.endsWith('.css'))) {
+  checkTheme(join(themesDir, f), `tema ${f}`);
+}
+
+// CSS de una app (opcional)
+const cssArgIdx = process.argv.indexOf('--css');
+if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
+  const f = resolve(process.argv[cssArgIdx + 1]);
+  const css = stripComments(read(f));
+  const roots = blocks(css, /(?:^|[\s}])\:root/);
+  roots.forEach((body, idx) => {
+    const seen = new Map();
+    for (const v of definedVars(body)) seen.set(v, (seen.get(v) ?? 0) + 1);
+    for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
+  });
+}
+
+// 3) valores fijos en componentes
+const NO_HARDCODE = [
+  { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
+  { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
+  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
+  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
+  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
+  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
+  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
+  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
+  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
+];
+
+const uiDir = join(ROOT, 'src/ui');
+if (existsSync(uiDir)) {
+  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
+    const lines = read(join(uiDir, f)).split(/\r?\n/);
+    lines.forEach((line, i) => {
+      const code = line.replace(/\/\/.*$/, '');
+      for (const rule of NO_HARDCODE) {
+        if (rule.skip?.includes(f)) continue;
+        const hits = code.match(rule.re);
+        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
+      }
+    });
+  }
+}
+
+for (const w of warnings) console.log(`AVISO  ${w}`);
+for (const e of errors) console.log(`ERROR  ${e}`);
+if (errors.length) {
+  console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
+  process.exit(1);
+}
+console.log(`doctor: contrato, repetidos y valores fijos correctos (${warnings.length} aviso(s)).`);