@devground/ui-conventions 0.1.0 → 0.3.0

package/README.md

@@ -35,10 +35,16 @@ explicitly.
 
 1. It always loads the universal base layer (`references/base.md`): rules that hold across
    any stack or design system.
-2. It looks for a project-specific overlay at `docs/ui-conventions.md` in the repo you're
+2. It always loads the universal design fundamentals (`references/design-fundamentals.md`):
+   principles, not a style — tokens over raw values (and a **SYSTEM GAP** instead of an invented
+   value), one primary action and one emphasis region per context, numbers with their
+   composition and timestamp, purposeful space, people-first copy, and how a product family
+   shares one grammar with different voices.
+3. It looks for a project-specific overlay at `docs/ui-conventions.md` in the repo you're
    working in. If one exists, it loads it, and on conflict the overlay wins over the base
-   — concrete tokens, own components, and helpers replace the generic rule.
-3. If no overlay exists yet, it offers to mine one from your actual code (never without
+   — concrete tokens, own components, and helpers replace the generic rule. The overlay is the
+   only door for a brand or design system, so one project's look never leaks into another.
+4. If no overlay exists yet, it offers to mine one from your actual code (never without
    asking) using `references/mining-prompt.md`, producing a `docs/ui-conventions.md` in the
    format of `references/overlay-template.md`.
 

package/lib/copy-guarded.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Copies a directory tree, never overwriting a file that already exists at the
+ * destination.
+ *
+ * This guard is the package's core promise: re-running the installer after an
+ * upgrade pulls in new files without clobbering local edits to a skill. It lives
+ * in its own module (rather than inline in `setup.js`) so it can be tested —
+ * `setup.js` runs its work at import time, so anything defined there is
+ * untestable without executing the installer.
+ *
+ * @param {string} src Source directory.
+ * @param {string} dst Destination directory (created if missing).
+ * @returns {{ written: number, skipped: number }} Files copied vs. left alone.
+ */
+function copyDirGuarded(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  let written = 0;
+  let skipped = 0;
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+
+    if (entry.isDirectory()) {
+      const sub = copyDirGuarded(srcPath, dstPath);
+      written += sub.written;
+      skipped += sub.skipped;
+    } else if (entry.isFile()) {
+      if (fs.existsSync(dstPath)) {
+        skipped++;
+      } else {
+        fs.copyFileSync(srcPath, dstPath);
+        written++;
+      }
+    }
+  }
+
+  return { written, skipped };
+}
+
+module.exports = { copyDirGuarded };

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@devground/ui-conventions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "UI convention skill for Claude Code — loads a project's frontend conventions (own components vs browser primitives, es-CL input formatting for RUT/phone/currency, accessibility and focus, error/loading states, microinteractions) as context BEFORE generating or editing UI, with an optional per-project overlay.",
   "bin": {
     "devground-ui-conventions": "./setup.js"
   },
   "files": [
     "setup.js",
-    "skills/"
+    "skills/",
+    "lib/",
+    "!lib/*.test.js"
   ],
   "keywords": [
     "ui",
@@ -37,5 +39,19 @@
   "bugs": {
     "url": "https://github.com/elkisdm/devground/issues"
   },
-  "scripts": {}
+  "devground": {
+    "status": "supported",
+    "graduatedBy": "ADR-0032",
+    "graduatedAt": "2026-09-07"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0",
+    "@vitest/coverage-v8": "^2.1.0",
+    "@devground/vitest-config": "0.3.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }

package/setup.js

@@ -26,29 +26,7 @@ function info(msg) {
   console.log(`  \x1b[36m→\x1b[0m ${msg}`);
 }
 
-/** Copies a tree, skipping files that already exist at the destination. */
-function copyDirGuarded(src, dst) {
-  fs.mkdirSync(dst, { recursive: true });
-  let written = 0;
-  let skipped = 0;
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const dstPath = path.join(dst, entry.name);
-    if (entry.isDirectory()) {
-      const sub = copyDirGuarded(srcPath, dstPath);
-      written += sub.written;
-      skipped += sub.skipped;
-    } else if (entry.isFile()) {
-      if (fs.existsSync(dstPath)) {
-        skipped++;
-      } else {
-        fs.copyFileSync(srcPath, dstPath);
-        written++;
-      }
-    }
-  }
-  return { written, skipped };
-}
+const { copyDirGuarded } = require('./lib/copy-guarded.js');
 
 const global = process.argv.includes('--global');
 const baseDir = global ? os.homedir() : process.cwd();

package/skills/ui-conventions/SKILL.md

@@ -20,9 +20,15 @@ skill by name.
 
 1. **Always** load `references/base.md` first. It is the universal layer: rules that apply
    to any project regardless of stack or design system.
-2. **Look for a project overlay** at `docs/ui-conventions.md` in the repo you are working in.
+2. **Always** load `references/design-fundamentals.md` too. It is the universal design layer:
+   principles (tokens over raw values, one decision per context, data with its context,
+   purposeful space, people-first copy) — never a concrete style. When a token or rule you
+   need is missing, declare a **SYSTEM GAP** instead of inventing a value.
+3. **Look for a project overlay** at `docs/ui-conventions.md` in the repo you are working in.
    - If it exists, load it. On conflict, **the overlay wins over base.md** — its concrete
-     tokens, own components, and helpers replace the generic rule.
+     tokens, own components, and helpers replace the generic rule. The overlay is also the
+     only place a brand or design system enters: never carry one project's look (colors,
+     fonts, radii) into another project that does not declare it.
    - If it does **not** exist, continue with the base layer alone and **offer** to mine one,
      pointing at `references/mining-prompt.md`. Do not mine it unless the user asks for it.
 

package/skills/ui-conventions/references/design-fundamentals.md

@@ -0,0 +1,113 @@
+# Fundamentos de diseño de producto — capa universal
+
+## 0. Cómo usar este documento
+
+`base.md` cuida que la UI sea **correcta** (semántica, foco, errores). Este documento cuida que
+sea **intencional**: que cada decisión visual tenga un trabajo y que el producto se lea como un
+sistema y no como una suma de pantallas.
+
+Son principios y reglas, **no una estética**. No fijan colores, tipografías ni radios concretos:
+esos valores los pone el sistema de diseño del proyecto, declarado en su overlay
+(`docs/ui-conventions.md`). Un proyecto sin overlay aplica estos fundamentos con los tokens que ya
+tenga, sin importar un estilo de otro proyecto.
+
+Precedencia: los **valores** del overlay siempre ganan. Un **principio** de este documento solo se
+deja de aplicar si el overlay lo declara como excepción explícita, con su motivo.
+
+## 1. El sistema antes que la pantalla
+
+La IA aprende de lo que encuentra: si encuentra cinco formas de resolver lo mismo, replica la
+inconsistencia; si encuentra un sistema, lo escala. Por eso:
+
+- **Consume nombres de token y componentes aprobados; no decidas valores.** Nunca escribas un hex,
+  un tamaño, un radio o un espaciado suelto si existe un token. Si no existe, no lo inventes:
+  declara un **SYSTEM GAP** en tu respuesta (qué faltó y qué valor provisorio usaste) para que un
+  humano lo resuelva en el sistema.
+- **Un valor existe una sola vez y se nombra por su uso**, no por su apariencia: `decide`,
+  `señala`, `superficie`, en vez de `blue-600` o `gray-light`. Dos valores que se ven iguales y
+  son distintos en el código son dos valores para el sistema: unifícalos.
+- **Ninguna distancia a ojo.** El espaciado sale de una escala (típicamente múltiplos de 4) y los
+  radios, de un conjunto corto. Un `13px` o un `mt-[7px]` es una decisión no tomada.
+- **Diagnostica antes de rediseñar.** Para ordenar UI existente, primero cuenta lo que hay
+  (colores, espaciados, radios y tamaños de texto distintos; patrones repetidos; fricciones) y
+  clasifica cada patrón en **conservar / adaptar / dejar**, con evidencia y no por gusto. Un patrón
+  pasa a ser regla común cuando lo confirman dos contextos de tipo distinto.
+
+## 2. Cada recurso tiene un trabajo
+
+- **Nada es decorativo ni está por defecto.** Si un color, un gradiente, una sombra, un borde o una
+  métrica no ayuda a comprender, decidir o actuar, no va.
+- **El color se asigna por rol**, y cada rol tiene un solo significado en todo el producto. El
+  color de la acción que decide no se reutiliza para decorar.
+- **La marca vive en su zona**: entrada, portadas y zona de marca. Los gradientes y luces de marca
+  **nunca van detrás de un dato ni comunican un estado.**
+- **Estado = indicador + palabra, nunca solo color** («● Sin respuesta», no un punto naranja
+  solo).
+
+## 3. Jerarquía: una decisión por contexto
+
+- **Una sola acción primaria por contexto**: la que cambia algo. Crear, exportar, cancelar y
+  navegar no deciden; van en el estilo secundario o neutro.
+- **Una sola región de énfasis máximo por vista**: el bloque que concentra lo que requiere
+  decisión ahora (p. ej. «42 requieren tu decisión» con su acción). Si hay dos, ninguna lo es.
+- **La profundidad la dan el tono y el material, no la acumulación de efectos.** Lo que requiere
+  atención se acerca (más contraste, superficie de trabajo); lo que acompaña se aleja (capa más
+  tenue). Evita apilar sombras, bordes y cápsulas para separar cosas.
+- **La selección es un tono, no un objeto.** Reposo: nada compite. Hover: sube el tono. Selección:
+  tono, peso y trazo. Foco: un anillo, solo con teclado (`focus-visible`). No agregues iconos,
+  barras ni badges extra para marcar lo activo; un filtro activo se marca con tono.
+
+## 4. Precisión en los datos
+
+- **Ninguna cifra suelta.** Toda métrica dice de qué está hecha y cuándo se midió: «477 asignados ·
+  59 % de respuesta · meta 70 % · medido 09:14».
+- **Declara lo que muestras.** Entorno, fuente, período y filtros activos se ven siempre (un
+  selector que dice «producción» sobre datos de sandbox es un defecto). Un estado que no dice
+  cuándo se midió no es un estado.
+- **Las cifras se alinean.** Usa numerales tabulares (`font-variant-numeric: tabular-nums`) y
+  alinea por columna horas, IDs, montos y estados.
+- **El valor que decide va junto a la lista**, no escondido en un detalle. Usa maestro-detalle
+  (lista + panel) para no perder contexto al abrir un registro.
+- **No repitas enlaces genéricos.** Un «Ver detalle» en cada fila es ruido: la fila entera es el
+  destino, o el enlace dice a dónde lleva.
+
+## 5. Espacio con propósito
+
+- **El espacio agrupa.** Separa lo que decide de lo que acompaña y de lo que pasa en segundo plano;
+  la cercanía comunica relación.
+- **Lo que nombra es grande y liviano; lo operativo es denso.** Títulos y cifras protagonistas con
+  tamaño grande y peso bajo; tablas y listas compactas.
+- **Aire, no vacío.** Simplificar no es dejar huecos porque sí. Tampoco cargar la vista: con más de
+  tres filtros, el panel nace plegado y deja a la vista los frecuentes.
+
+## 6. La interfaz habla con personas
+
+- **Voz directa, precisa y cercana, sin ser blanda.** Habla a la persona, no a la base de datos.
+  Mal: «revisar last_error en inbound_events». Bien: «Este lead no llegó al CRM; reintentamos a las
+  10:30».
+- **Las personas aparecen con nombre y cara** (avatar o iniciales), no con un ID.
+- **Estado vacío = causa + paso siguiente** («Aún no hay reservas este mes · Crear reserva»).
+- **El aviso confirma y deja deshacer** en las acciones reversibles («Proyecto reasignado a A. Soto
+  · Deshacer»), en vez de pedir confirmación previa.
+
+## 7. Familias de productos: misma gramática, distintas voces
+
+Cuando varios productos conviven en una suite, no deben verse iguales, pero quien cambia de
+producto no debe aprender otro idioma:
+
+- **Comparten la gramática**: la misma estructura de navegación, el mismo selector de producto en
+  el mismo lugar, la misma búsqueda global, los mismos estados de interacción y las mismas piezas
+  (pastillas, filtros, avisos).
+- **Varía la voz**, y solo a través de tokens: densidad, tonalidad y forma propias de cada
+  producto, nunca reglas distintas para lo mismo.
+
+## 8. Antipatrones (el look genérico de la IA)
+
+- Bordes, cápsulas, sombras y radios grandes en todo, para «separar» lo que el espacio y el tono ya
+  separan.
+- Botones en píldora y varias acciones de color primario compitiendo en la misma vista.
+- La «tecnología que grita»: fondos negros con neones y azul eléctrico; o el extremo opuesto,
+  minimalismo vacío que esconde la información.
+- Tarjetas de KPI con cifras sin contexto ni fecha, puestas porque «se ven bien».
+- Gradientes sin función, sobre todo detrás de datos.
+- Mensajes de sistema en lenguaje técnico y personas identificadas por ID.

package/skills/ui-conventions/references/overlay-template.md

@@ -45,8 +45,20 @@ librería o CSS puro, ninguna]
 
 > Helper preferente si el repo no tiene uno propio: @devground/chile-formats.
 
+## 7. Sistema de diseño (valores)
+
+> Solo si el proyecto adopta un sistema de diseño. Aquí entran los valores que
+> `design-fundamentals.md` deja abiertos; un proyecto sin esta sección no hereda el estilo de
+> otro.
+
+- **Fuente:** [ruta o URL del sistema de diseño]
+- **Tokens por rol:** [nombre de uso → token del código, p. ej. `decide` → `--color-decide`]
+- **Tipografías, escala de espaciado, radios:** [valores]
+- **Excepciones a los fundamentos:** [principio → motivo, o «ninguna»]
+- **SYSTEM GAP abiertos:** [lo que el sistema todavía no define]
+
 ## Deuda conocida
 
-| Deuda | Ubicación | Patrón correcto |
-| --- | --- | --- |
+| Deuda         | Ubicación                   | Patrón correcto                  |
+| ------------- | --------------------------- | -------------------------------- |
 | [descripción] | `ruta/al/archivo.ext:línea` | [qué debería usarse en su lugar] |