dtthaison/uix-skill

¿Qué hace uix-skill?

Construye interfaces que se vean diseñadas, no generadas. Decide el aspecto una vez (DESIGN.md), construye a partir de él, verifica el resultado con scripts.

Rutas: todas las rutas references/, data/ y scripts/ a continuación son relativas a la carpeta que contiene este SKILL.md. Ejecuta los scripts desde la raíz del proyecto del usuario como node <esa carpeta>/scripts/<nombre>.mjs. Los scripts necesitan Node 22.

Comandos

Comando	Tarea
/uix init	Lee el proyecto, hace 3 preguntas, ofrece 3 direcciones, escribe y verifica DESIGN.md.
/uix build	Construye una página, pantalla o componente desde DESIGN.md, lo verifica, lo corrige. Por defecto.
/uix audit	Ejecuta las comprobaciones e informa. No edita nada.
/uix polish	Corrige los principales problemas de auditoría. Mantiene la lógica, las rutas y el significado del texto.
/uix motion	Revisa o añade animaciones, después de las 4 preguntas.

El verbo puede llegar como /uix-skill <verbo>, como uix <verbo>, o como una solicitud directa ("haz la página de configuración", "audita esta pantalla"). Asigna una solicitud directa al verbo más cercano. Sin coincidencia clara: build.

Reglas estrictas

1. DESIGN.md existe: léelo primero y construye a partir de él. Omite la recopilación de información y las direcciones. Nunca inventes colores, fuentes o radios que no defina.
2. Nunca informes como terminado antes de que se haya ejecutado scripts/rules.mjs y, para stacks web, también scripts/check.mjs. Si una comprobación no se puede ejecutar (ver Comprobaciones), informa no verificado: <razón>.
3. Máximo 2 rondas de reparación después de una comprobación. Luego informa lo que queda.
4. Imágenes: activos del proyecto, luego Openverse/Wikimedia con crédito, luego arte CSS/SVG. Nunca un marcador de posición vacío.
5. Solo herramientas gratuitas. Sin APIs de pago, sin claves.
6. No edites archivos fuera del ámbito de la interfaz de usuario de la solicitud. /uix audit no edita nada.
7. Carga solo los archivos que nombran las tablas siguientes. Carga un archivo de stack, excepto shadcn y nuxt-ui: carga esa guía más la guía del framework anfitrión.

Orden de ejecución

1. Lee el proyecto: package.json, configuración, estilos existentes, DESIGN.md, public/ o assets/.
2. Detecta el stack (tabla siguiente). Carga su guía.
3. Recopilación de información. Haz las 3 preguntas juntas, en un solo mensaje: audiencia, el trabajo de la pantalla, tono. Stacks móviles: el tono también pregunta "¿animación tranquila o animada?"; registra la respuesta como el nivel de animación en DESIGN.md (references/design-md.md). Omite cualquier pregunta que el usuario o el proyecto ya haya respondido.
4. Ofrece 3 direcciones de references/directions.md que difieran claramente en tono, densidad y temperatura de color. Espera la elección. Una dirección que el propietario ya haya elegido de antemano omite la oferta.
5. Escribe DESIGN.md (references/design-md.md) y verifícalo. Corrige todos los errores de verificación.
6. Elige una estructura de references/layouts-web.md (marketing, contenido) o references/layouts-app.md (pantallas con inicio de sesión).
7. Construye la primera sección. Texto real, imágenes reales, todos los estados de los componentes.
8. Comprueba (abajo). Corrige errores, luego advertencias. Máximo 2 rondas.
9. Informa.

Los pasos 3 a 5 pertenecen a init. build usa un DESIGN.md existente; si no hay ninguno, ejecuta init primero.

Los sistemas de diseño existentes ganan

• DESIGN.md existe: léelo, verifícalo, construye a partir de él.
• No hay DESIGN.md pero el proyecto tiene sus propios tokens o tema (configuración de Tailwind, variables CSS, archivo de tema): /uix init escribe un DESIGN.md (en la raíz del proyecto) a partir de esos tokens. No ofrezcas nuevas direcciones a menos que el usuario solicite un nuevo aspecto.
• Ninguno de los dos: init completo.
• Tokens propios significa colores, fuentes o espaciado más allá de los valores predeterminados iniciales del framework, en un bloque @theme de Tailwind v4, una configuración de Tailwind, propiedades personalizadas de CSS o un archivo de tema de plataforma. El --background/--foreground predeterminado de create-next-app no cuenta.

Qué cargar

No cargues nada más hasta que sea necesario.

Cuándo	Cargar
Cualquier build, polish o audit	references/anti-slop.md, references/components-a11y.md
init, o cualquier escritura de DESIGN.md	references/design-md.md
init (ofreciendo direcciones)	references/directions.md, luego las filas elegidas de data/fonts.csv, data/palettes.csv, data/styles.csv
Página de marketing, contenido, catálogo	references/layouts-web.md
Dashboard, tabla, formulario, configuración, autenticación	references/layouts-app.md
Cualquier animación, o /uix motion	references/motion.md
Build, polish o audit móvil	references/mobile-foundations.md, references/mobile-patterns.md
Animación móvil	references/mobile-motion.md en lugar de references/motion.md
Móvil: visualización segura de la app, Expo Go frente a una compilación de desarrollo, comprobaciones de toque y deslizamiento	references/mobile-testing.md
init para una app móvil	data/mobile-styles.csv en lugar de data/styles.csv (las filas elegidas)
Cualquier espacio de imagen	references/images.md
Ejemplo de forma de DESIGN.md	data/examples/ledger.md, field-notes.md o harbor.md. Solo uno.
Cada tarea	Una references/stacks/<id>.md. Para shadcn o nuxt-ui, también la guía anfitriona (ver Detección de stack).

Detección de stack

La primera coincidencia gana, de arriba a abajo. Sin coincidencias: html-tailwind. Coincide con nombres de dependencias exactos (next, no next-themes).

Señal	Id de stack
@nuxt/ui en package.json	nuxt-ui
components.json con shadcn, o @/components/ui	shadcn
Archivo artisan o laravel/framework en composer.json	laravel
nuxt en package.json	nuxtjs
next en package.json	nextjs
@angular/core o angular.json	angular
astro en package.json o astro.config.*	astro
svelte o @sveltejs/kit	svelte
vue en package.json	vue
three en package.json	threejs
react-native o expo en package.json	react-native
react en package.json	react
pubspec.yaml	flutter
build.gradle(.kts) con Compose (androidx.compose)	jetpack-compose
*.xcodeproj o Package.swift con SwiftUI	swiftui
*.csproj con Avalonia	avalonia
*.csproj con Uno. o Uno.WinUI	uno
*.csproj con Microsoft.WindowsAppSDK	winui
*.csproj con <UseWPF>true</UseWPF>	wpf
*.csproj con TargetPlatformIdentifier UAP o Microsoft.NETCore.UniversalWindowsPlatform	uwp
pom.xml o build.gradle con javafx	javafx
ninguno de los anteriores	html-tailwind

Ids web: angular, astro, html-tailwind, laravel, nextjs, nuxt-ui, nuxtjs, react, shadcn, svelte, threejs, vue. El resto son nativos. "Stack móvil" significa react-native, flutter, swiftui o jetpack-compose. Sus solicitudes también cargan las filas móviles de "Qué cargar". El stack más específico gana: nextjs sobre react, react-native sobre react, laravel sobre su frontend JS. Los stacks de capa de componentes cargan dos guías: shadcn más la guía anfitriona (nextjs, react, astro, laravel, ... detectada por esta tabla con la fila shadcn omitida), y nuxt-ui más nuxtjs. Cada otro proyecto carga una.

Comprobaciones

Desde la raíz del proyecto del usuario. Reemplaza <skill> con la carpeta que contiene este SKILL.md.

node <skill>/scripts/rules.mjs [--design DESIGN.md] <ruta...>
node <skill>/scripts/check.mjs <url|archivo> [--widths 375,768,1280] [--out .uix/shots] [--themes attr=v1,v2]
node <skill>/scripts/images.mjs "<consulta>" [--count 6]

• Los tres imprimen JSON. rules.mjs imprime {findings, skipped}: los archivos minificados, de más de 1 MB o ilegibles van a skipped con una razón y no son un error. check.mjs imprime {shots, findings, notes}; lee notes (por ejemplo, un tiempo de espera de carga sondeado temprano, o una captura de pantalla que falló). Salida 0: limpio. Salida 1: hallazgos de error (rules.mjs, check.mjs). Salida 2: problema de uso o entorno (los tres). images.mjs solo sale con 0 o 2.
• La salida 2 nunca es un resultado limpio y nunca cuenta como una ronda de reparación. Si check.mjs no puede alcanzar la página y el proyecto tiene un script de desarrollo obvio (npm run dev, etc.), inícialo una vez en segundo plano y vuelve a intentarlo. De lo contrario, pregunta al usuario. Nombra lo que falta (Chrome, Node 22, un servidor que no se está ejecutando).
• Si la comprobación aún no se puede ejecutar, el informe dice no verificado: <razón>.
• Stacks web: ejecuta rules.mjs en la fuente, luego check.mjs en la URL del servidor de desarrollo o el archivo construido. Los anchos son 375, 768 y 1280. Las capturas de pantalla se guardan en .uix/shots: <w>.png es la página completa, y <w>-<n>.png son mosaicos de máximo 1600 px. Mira los mosaicos, no la toma completa; se reduce a ilegible. check.mjs desplaza la página primero para que el contenido que se revela al desplazarse se muestre.
• Cuando el proyecto define varios temas ([data-theme], [data-skin], .dark), pásalos con --themes, por ejemplo --themes data-skin=oatmeal,rose o --themes class=dark. Cada tema se prueba en el último ancho; sus hallazgos llevan theme.
• Los hallazgos de contraste se agrupan por par de colores (count, sample, selectors). Corrige el token, no cada elemento.
• React Native (Expo): ejecuta rules.mjs, luego node <skill>/scripts/check-mobile.mjs --app exp://127.0.0.1:<puerto> contra un servidor Metro en ejecución; añade --platform android para emuladores Android (las banderas y el archivo de rutas están en la guía del stack). Imprime {shots, findings, notes} y sale con 0, 1 o 2 como check.mjs. Una nota que comienza con maestro missing: significa que la jerarquía y el flujo no se ejecutaron; infórmalo como no verificado: <razón>, no como una ejecución exitosa. Las capturas se guardan en .uix/mobile-shots. Un hallazgo route-not-navigated es un error y nunca un resultado limpio: la captura muestra otra pantalla. Bucle de reparación: vuelve a comprobar con --only <rutas> y una entrada --devices, no la matriz completa.
• Otros stacks móviles: ejecuta rules.mjs. Las apps nativas de iOS (SwiftUI) luego usan check-mobile.mjs --native (banderas en la guía del stack); en un pase de auditoría --out "$(mktemp -d)". Otros usan la receta de captura de pantalla manual en "Cómo comprobar" del archivo del stack (claro, oscuro, texto xxxl). Sin simulador disponible: no verificado: <razón>. Se aplica el límite de 2 rondas.
• Otros stacks nativos: ejecuta rules.mjs, luego la lista de verificación manual en "Cómo comprobar" del archivo del stack. No hay comprobación de navegador.
• Corrige los hallazgos de error antes que los de warn. Una advertencia que mantengas necesita una razón de una línea.
• Bucle de reparación: comprueba, corrige, vuelve a comprobar. Máximo 2 rondas. Luego detente e informa.
• Los ids de reglas y sus correcciones están en references/anti-slop.md. También enumera reglas de juicio que ningún script detecta; revísalas tú mismo.

Contratos de comandos

init

1. Lee el proyecto, detecta el stack, carga su guía.
2. Tokens existentes o DESIGN.md: ver "Los sistemas de diseño existentes ganan".
3. De lo contrario, haz las 3 preguntas, ofrece 3 direcciones claramente diferentes, espera. Cualquier stack: detecta el idioma del contenido (lang, archivos i18n, texto) y selecciona solo las filas de data/fonts.csv cuya columna scripts lo cubra.
4. Escribe DESIGN.md. Verifica: npx --yes @google/[email protected] lint DESIGN.md. Corrige errores.
5. Informa la dirección elegida, los archivos escritos y el resultado de la verificación.

build

1. Lee DESIGN.md, la guía del stack y el archivo de diseño.
2. Elige una estructura. Di cuál y por qué en una línea.
3. Construye la primera sección completamente. Luego el resto.
4. Ejecuta las comprobaciones. Corrige en máximo 2 rondas.
5. Informa.

audit

1. Detecta el stack y carga su guía.
2. Ejecuta las comprobaciones. Revisa las reglas de juicio. Pasa --out "$(mktemp -d)" a check.mjs y también a check-mobile.mjs, para que la auditoría no escriba nada en el proyecto.
3. Genera una tabla. No edites nada.

Antes	Después	Por qué
lo que hay ahora	lo que debería ser	el id de regla o razón

polish

1. Detecta el stack y carga su guía.
2. Ejecuta primero una auditoría.
3. Corrige los principales problemas, errores primero. No cambies la lógica, las rutas o el significado del texto.
4. Vuelve a ejecutar las comprobaciones. Máximo 2 rondas. Informa.

motion

1. Carga references/motion.md (stacks móviles: references/mobile-motion.md). Responde sus 4 preguntas por escrito para cada animación: necesaria, qué comunica, qué easing, cuánto dura.
2. Elimina cualquier animación sin una respuesta clara. Añade manejo de prefers-reduced-motion (la guía del stack nombra el equivalente nativo).
3. Genera una tabla Antes / Después / Por qué. Aplica el cambio solo cuando el usuario pidió añadir o corregir animación, no para revisarla.

Informe

Termina cada ejecución con:

• Lo que cambió (archivos).
• Hallazgos que permanecen, cada uno con id de regla y razón.
• Rutas de capturas de pantalla y mosaicos en .uix/shots (web), rutas de capturas en .uix/mobile-shots (móvil) o las comprobaciones manuales realizadas (otros nativos).
• Créditos de imágenes añadidos.