@devground/ui-conventions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devground contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @devground/ui-conventions
+
+**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, instead of relying on a design audit to catch inconsistencies
+after the fact.
+
+## Install
+
+Into the current project:
+
+```bash
+npx @devground/ui-conventions
+# -> .claude/skills/ui-conventions
+```
+
+For all your projects (user-level):
+
+```bash
+npx @devground/ui-conventions --global
+# -> ~/.claude/skills/ui-conventions
+```
+
+Existing files are never overwritten — re-run after an upgrade to pull in new reference
+files while keeping your local edits.
+
+## How it triggers
+
+The skill fires before you generate or modify any frontend UI — forms, inputs, modals,
+buttons, pages, React/Next.js/Tailwind components — even if you don't name the skill
+explicitly.
+
+## Base → overlay → mining
+
+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
+   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
+   asking) using `references/mining-prompt.md`, producing a `docs/ui-conventions.md` in the
+   format of `references/overlay-template.md`.
+
+## Relationship with design-taste / design-audit
+
+`@devground/design-taste` owns aesthetics — layout, typography, motion, spacing taste.
+`ui-conventions` is a different layer: correctness and consistency (input semantics,
+focus management, error states) applied while the code is being written. A later
+design-audit remains a safety net, but with this skill loaded up front there should be
+little left for it to catch.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@devground/ui-conventions",
+  "version": "0.1.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/"
+  ],
+  "keywords": [
+    "ui",
+    "conventions",
+    "frontend",
+    "accessibility",
+    "chile",
+    "es-cl",
+    "rut",
+    "claude-code",
+    "skill",
+    "devground"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elkisdm/devground.git",
+    "directory": "packages/ui-conventions"
+  },
+  "homepage": "https://github.com/elkisdm/devground/tree/main/packages/ui-conventions#readme",
+  "bugs": {
+    "url": "https://github.com/elkisdm/devground/issues"
+  },
+  "scripts": {}
+}

package/setup.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * Installs the ui-conventions skill into a Claude Code skills directory.
+ *
+ *   npx @devground/ui-conventions            -> <cwd>/.claude/skills/  (this project)
+ *   npx @devground/ui-conventions --global   -> ~/.claude/skills/      (all projects)
+ *
+ * Each skill lands in its own directory (matching its frontmatter `name`).
+ * Existing files are never overwritten — your local edits to a skill are
+ * preserved, only missing files are added (re-run after upgrading to pull in
+ * new skills or reference files).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+function log(msg) {
+  console.log(`  \x1b[32m✓\x1b[0m ${msg}`);
+}
+function warn(msg) {
+  console.log(`  \x1b[33m!\x1b[0m ${msg}`);
+}
+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 global = process.argv.includes('--global');
+const baseDir = global ? os.homedir() : process.cwd();
+const src = path.join(__dirname, 'skills');
+const dstRoot = path.join(baseDir, '.claude', 'skills');
+
+if (!fs.existsSync(src)) {
+  console.error('\x1b[31m✗\x1b[0m skills/ not found in package. Aborting.');
+  process.exit(1);
+}
+
+// Only directories under skills/ are actual skills; loose files
+// would be packaging metadata, not skills.
+const skillDirs = fs
+  .readdirSync(src, { withFileTypes: true })
+  .filter((e) => e.isDirectory())
+  .map((e) => e.name);
+
+let written = 0;
+let skipped = 0;
+const installed = [];
+for (const name of skillDirs) {
+  const res = copyDirGuarded(path.join(src, name), path.join(dstRoot, name));
+  written += res.written;
+  skipped += res.skipped;
+  if (res.written > 0) installed.push(name);
+}
+
+const scope = global ? 'global (~/.claude/skills)' : 'project (.claude/skills)';
+if (written > 0) {
+  log(`ui-conventions installed — ${scope} — ${written} file(s)`);
+  info(`skills: ${installed.join(', ')}`);
+}
+if (skipped > 0) warn(`${skipped} file(s) already existed (kept your version)`);
+if (written === 0 && skipped > 0) info('Already up to date.');
+
+info('Loads before you generate UI: universal conventions + your project overlay if');
+info('docs/ui-conventions.md exists.');

package/skills/ui-conventions/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ui-conventions
+description: Fires BEFORE generating or modifying any frontend UI — forms, inputs, modals, buttons, pages, React/Next.js/Tailwind components — even if the user does not name the skill; loads the project's UI conventions so code is correct and consistent on the first pass instead of fixed by a later audit; especially for Chilean (es-CL) apps: RUT, phone +56, currency/UF formatting.
+---
+
+# UI Conventions
+
+## 1. Purpose / when this fires
+
+This skill acts **before** UI code is written, not after. It is a correctness/consistency
+layer: own components vs. browser primitives, input formatting, accessibility and focus,
+error/loading states, and microinteractions — plus region-specific rules for Chile (es-CL)
+such as RUT, phone, and currency formatting.
+
+Trigger it whenever you are about to generate or edit a form, input, modal, button, page,
+or any React/Next.js/Tailwind component — even if the user's request does not mention this
+skill by name.
+
+## 2. Load order (mandatory)
+
+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.
+   - If it exists, load it. On conflict, **the overlay wins over base.md** — its concrete
+     tokens, own components, and helpers replace the generic rule.
+   - 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.
+
+## 3. Apply during generation, not after
+
+Apply these conventions while writing the code — the first draft should already follow
+them. This skill is not a linter that runs afterward; it is context loaded up front so the
+correction pass a design-audit would otherwise require becomes unnecessary.
+
+## 4. Relationship with other skills
+
+`design-taste` / `frontend-design` own aesthetics — layout, typography, motion, spacing
+taste. This skill is a different layer: correctness and consistency (does the input have
+the right `type`/`inputMode`, does the modal trap focus, is the RUT validated). A later
+design-audit still acts as a safety net, but with this skill loaded up front there should
+be little left for it to catch.
+
+## 5. Maintain the overlay
+
+When you generate UI and establish a new pattern the overlay does not yet capture, pay down a
+row from its "Deuda conocida" table, or discover that `docs/ui-conventions.md` contradicts the
+real code, update the overlay in the **same** change — do not leave it stale. Same principle as
+spec-flow's codemap: whoever uses the overlay maintains it. If the repo has no overlay yet and
+you just wrote UI worth codifying, offer to mine one (`references/mining-prompt.md`); never
+rewrite the overlay silently — surface the diff so the human can confirm it.

package/skills/ui-conventions/references/base.md

@@ -0,0 +1,118 @@
+# Convenciones de UI — capa base
+
+## 0. Cómo usar este documento
+
+Esta es la capa universal: reglas válidas para cualquier proyecto, independientemente del
+stack o sistema de diseño. Si el proyecto tiene un overlay (`docs/ui-conventions.md`), ese
+overlay tiene precedencia sobre lo que dice aquí.
+
+## 1. Componentes propios vs. primitivas del navegador
+
+- Usa siempre el componente propio del proyecto (botón, input, modal) en vez de HTML nativo
+  estilizado a mano. Un `<button>` o `<input>` nativo con clases sueltas reimplementa algo
+  que el sistema de componentes ya resuelve, y diverge con el tiempo.
+- Combina clases con el helper de composición de clases del proyecto (equivalente a
+  `cn`/`twMerge`), nunca concatenando template strings. Antipatrón: `` `btn ${variant} ${size}` ``
+  en vez de `cn('btn', variant, size)`.
+- No introduzcas una librería nueva (toaster, motion, date-picker) sin una decisión
+  explícita (ADR o equivalente). Si el proyecto no tiene toaster, usa feedback inline; si
+  no tiene motion, usa transiciones CSS.
+- Reutiliza el modal/dialog del proyecto para overlays — ya resuelve el trap de foco, el
+  cierre con Escape y el bloqueo de scroll. No reimplementes esa lógica con un portal
+  ad-hoc por componente.
+
+## 2. Formateo de inputs (semántica universal)
+
+- Usa `type`, `inputMode` y `autoComplete` semánticos según el campo:
+  - Email → `type="email"` `inputMode="email"` `autoComplete="email"` `spellCheck={false}`
+    `autoCapitalize="none"`.
+  - Teléfono → `type="tel"` `inputMode="tel"` `autoComplete="tel"`.
+  - Montos o identificadores numéricos de texto libre → `inputMode="numeric"`, sin
+    `type="number"` (que introduce spinners y bloquea el formateo visual).
+- Para campos con formato visual (RUT, teléfono, montos), aplica la máscara en el
+  `onChange` pero persiste siempre el valor limpio o normalizado, no el string
+  formateado. Ejemplo genérico:
+
+  ```tsx
+  function handleChange(raw: string) {
+    const formatted = formatForDisplay(raw);
+    setDisplayValue(formatted);
+    setCleanValue(clean(raw));
+  }
+  ```
+
+- Valida en el boundary con un schema (p. ej. zod), no con lógica inline dentro del
+  componente. El componente muestra el error; no decide si el valor es válido.
+
+## 3. Accesibilidad y estados de foco
+
+- Todo botón icon-only lleva `aria-label` (dinámico si el estado que representa cambia,
+  p. ej. "Expandir menú" / "Minimizar menú").
+- Todo campo tiene `label` asociado con `htmlFor` + `id` (usa un generador de id estable,
+  como `useId()`, en componentes reutilizables para no colisionar entre instancias).
+- Los errores de un campo se asocian con `aria-invalid` + `aria-describedby` apuntando al
+  id del mensaje de error, y el mensaje lleva `role="alert"` o `role="status"` para que un
+  lector de pantalla lo anuncie.
+- El anillo de foco usa el token de foco del proyecto y se dispara con `focus-visible`, no
+  con `focus:` a secas (que también dispara con click de mouse) ni con un color
+  hardcodeado.
+- Los overlays (modal, dropdown, dialog) cierran con Escape, atrapan el foco dentro
+  mientras están abiertos, y restauran el foco al elemento que los abrió al cerrarse.
+- Los SVG puramente decorativos llevan `aria-hidden="true"`.
+- Los colores se aplican por token semántico del proyecto, nunca como clase de color cruda
+  (`gray-*`, `red-*`) ni hex suelto en el JSX.
+
+## 4. Manejo de errores y carga
+
+- Las rutas con carga asíncrona muestran un skeleton fiel al layout real (mismo header,
+  mismas filas o secciones), nunca un spinner de página completa.
+- Durante el envío de un formulario: el botón queda `disabled`, muestra un spinner, y su
+  label cambia a gerundio ("Enviando…", "Guardando…").
+- Los errores de formulario se muestran inline junto al campo que falló, no solo en un
+  banner genérico, y se anuncian por ARIA. En formularios largos, mueve el foco al primer
+  mensaje de error tras un submit fallido.
+- Nunca silencies un error de red o de submit: siempre mapéalo a un mensaje legible para
+  el usuario y regístralo (`console.error` o equivalente). Un `catch` vacío o que solo
+  cambia estado sin loguear es un antipatrón.
+- Los estados vacíos (empty states) son un componente dedicado con copy accionable, no un
+  `null` o una tabla sin filas sin explicación.
+- Los estados de éxito son una vista o tarjeta dedicada, no solo la desaparición del
+  formulario.
+- Toda ruta que hace fetching que puede fallar tiene un error boundary (`error.tsx` o
+  equivalente del framework) con una acción de reintento.
+
+## 5. Microinteracciones
+
+- El hover y el active de un control viven en la primitiva (el componente base), no se
+  duplican en cada lugar que lo usa.
+- `prefers-reduced-motion` se respeta siempre: si la animación es CSS, usa el prefijo o
+  gate correspondiente (`motion-safe:` o un override global en `prefers-reduced-motion:
+  reduce`); si la animación es JS/imperativa, verifica la preferencia del sistema antes de
+  animar (equivalente a `useReducedMotion()`).
+- El cierre animado de un overlay dispara el `onClose` real cuando termina la animación de
+  salida (`onAnimationEnd` o equivalente), nunca antes — si no, el contenido desaparece
+  antes de que termine la transición.
+- Para acciones tipo "copiar al portapapeles": intercambia el label a un estado de
+  confirmación ("¡Copiado!") por ~2 segundos y envuelve la llamada al portapapeles en
+  `try/catch` (el acceso al portapapeles puede estar bloqueado por el navegador).
+- Las animaciones en cascada (listas, grids) usan un delay proporcional al índice del
+  elemento, no todos animan al mismo tiempo.
+- Los keyframes nuevos se declaran en el theme o en el CSS global del proyecto, no inline
+  por componente.
+
+## 6. Región: Chile (es-CL)
+
+> Si el proyecto no tiene helpers propios de RUT/teléfono/moneda, usa o instala
+> `@devground/chile-formats` en vez de reimplementarlos; si ya tiene un helper, respétalo.
+
+- **RUT**: usa un único helper de formateo (puntos y guion) y de validación (módulo 11);
+  aplica la máscara en el `onChange` pero persiste siempre el valor limpio, sin puntos ni
+  guion. El mensaje de error debe mencionar el dígito verificador ("RUT inválido, verifica
+  el dígito verificador"). Nunca reimplementes el algoritmo de módulo 11 dentro de un
+  componente.
+- **Teléfono**: muestra el formato visual `+56 9 XXXX XXXX`, con `inputMode="tel"` y
+  `autoComplete="tel"`; normaliza el valor antes de persistirlo (no guardes el string tal
+  como el usuario lo tipeó).
+- **Moneda, UF y fechas**: usa `Intl.NumberFormat("es-CL")` e `Intl.DateTimeFormat("es-CL")`
+  centralizados en un único helper compartido del proyecto. Nunca uses `toLocaleString` ad
+  hoc dentro de un componente, ni reimplementes el formateador en más de un lugar.

package/skills/ui-conventions/references/mining-prompt.md

@@ -0,0 +1,38 @@
+# Prompt de minado — convenciones de UI de un repo
+
+Este prompt es reutilizable: pégalo en cualquier repo cuando quieras generar su overlay de
+convenciones de UI (`docs/ui-conventions.md`), el archivo que la skill `ui-conventions`
+carga después con precedencia sobre la capa base.
+
+---
+
+Actúa como un auditor de convenciones de interfaz. Recorre el frontend del repo actual (no
+solo el README) y extrae los patrones recurrentes reales del código, organizados en estas
+categorías:
+
+1. Componentes propios vs. primitivas del navegador.
+2. Formateo de inputs.
+3. Accesibilidad y estados de foco.
+4. Manejo de errores y carga.
+5. Microinteracciones.
+6. Regional: Chile (es-CL) si aplica — RUT, teléfono, moneda/UF, fechas.
+
+Para cada patrón que documentes:
+
+- Escribe la regla como un enunciado imperativo, no como una descripción.
+- Cita un ejemplo correcto real del repo con `ruta/al/archivo.ext:línea`.
+- Cita un antipatrón real si existe, con su propia ruta:línea. Los antipatrones citados son
+  deuda conocida documentada, no licencia para repetirlos en código nuevo.
+
+Verifica el stack real contra el código (versión de framework, versión de Tailwind,
+sistema de componentes, si hay toaster o librería de motion) — no confíes en el README ni
+en archivos de configuración desactualizados si el código dice otra cosa.
+
+Genera `docs/ui-conventions.md` en la raíz del repo auditado, usando el formato de
+`references/overlay-template.md` de esta skill: mismo orden de secciones que la base
+(0 a 6), mismo formato de patrón (Regla · Ejemplo correcto · Antipatrón), y cerrando con
+una tabla de deuda conocida.
+
+Ese archivo (`docs/ui-conventions.md`) es el overlay que la skill `ui-conventions` cargará
+automáticamente la próxima vez que se genere o edite UI en este repo, y sus reglas
+concretas prevalecerán sobre la capa base genérica en caso de conflicto.

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

@@ -0,0 +1,52 @@
+# Convenciones de interfaz — [nombre del proyecto]
+
+> Lo definido en este archivo sustituye a la regla genérica de `base.md` en caso de
+> conflicto.
+
+**Stack:** [framework + versión] · [versión de Tailwind u otro CSS] · [sistema de
+componentes: shadcn, design system propio, ninguno] · [toast: sí/no, cuál] · [motion:
+librería o CSS puro, ninguna]
+
+## 1. Componentes propios vs. primitivas del navegador
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+## 2. Formateo de inputs
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+## 3. Accesibilidad y estados de foco
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+## 4. Manejo de errores y carga
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+## 5. Microinteracciones
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+## 6. Regional: Chile (es-CL)
+
+- **Regla:** [enunciado imperativo]
+  **Ejemplo correcto:** `ruta/al/archivo.ext:línea`
+  **Antipatrón:** [qué evita]
+
+> Helper preferente si el repo no tiene uno propio: @devground/chile-formats.
+
+## Deuda conocida
+
+| Deuda | Ubicación | Patrón correcto |
+| --- | --- | --- |
+| [descripción] | `ruta/al/archivo.ext:línea` | [qué debería usarse en su lugar] |