@saulwade/swl-ses 1.0.0

package/habilidades/typescript-diagnosticos/SKILL.md

@@ -0,0 +1,513 @@
+---
+name: typescript-diagnosticos
+description: >
+  Guía canónica de códigos de error del compilador TypeScript (TS1xxx–TS7xxx).
+  Extraída de diagnosticMessages.json del repositorio microsoft/TypeScript.
+  Cubre los errores más frecuentes con causa, fix idiomático y anti-patrón a evitar.
+  Cargar cuando se revisa código TypeScript con errores de compilación o cuando
+  se necesita identificar la causa raíz de un error TSxxxx.
+version: 1.0.0
+herramientasPermitidas: [Read, Bash, Glob, Grep]
+fuente: temp/TypeScript-main/src/compiler/diagnosticMessages.json
+tags: [typescript, diagnósticos, errores, compilador, type-safety]
+exclusiones:
+  - "No cargar para errores de runtime JavaScript que no involucran el compilador TypeScript — si el código compila pero falla en ejecución, no hay código TS#### que diagnosticar."
+  - "No cargar para errores de bundlers (Vite, webpack) que no son errores del compilador tsc — los errores de bundler tienen prefijos diferentes y causas de resolución de módulos; cargar `build-errors-typescript`."
+  - "No cargar para diseñar tipos avanzados (generics, mapped types, conditional types) — para diseño del sistema de tipos cargar `typescript-avanzado`."
+  - "No cargar para errores de ESLint o Prettier en archivos .ts — ESLint/Prettier no generan códigos TS####; sus códigos de error son de sus propias reglas."
+evolvable: true  # default para skill estandar
+---
+# Diagnósticos canónicos del compilador TypeScript
+
+Guía de referencia rápida. Fuente: `diagnosticMessages.json` del compilador TypeScript oficial.
+
+## Cuándo NO cargar
+
+- La pregunta es sobre errores de runtime JavaScript que no involucran al compilador — si el código compila pero falla en ejecución, no hay código TS#### que diagnosticar.
+- Los errores vienen de bundlers (Vite, webpack) con prefijos distintos a TS#### — esos son errores de resolución de módulos; cargar `build-errors-typescript`.
+- La tarea es diseñar tipos avanzados (generics, mapped types, conditional types) — para diseño del sistema de tipos cargar `typescript-avanzado`.
+- Los errores son de ESLint o Prettier en archivos `.ts` — ESLint/Prettier no generan códigos TS####; sus reglas tienen nombres propios como `@typescript-eslint/no-explicit-any`.
+
+---
+
+## Errores de asignación de tipos (TS2xxx)
+
+Los más frecuentes en proyectos con `strict: true`.
+
+### TS2322 — Type '{0}' is not assignable to type '{1}'
+
+**Causa:** Tipos incompatibles en asignación directa o retorno de función.
+
+```typescript
+// MAL
+const x: number = "hola";          // TS2322
+function getId(): number { return "abc"; }  // TS2322
+
+// BIEN
+const x: number = 42;
+function getId(): number { return 123; }
+
+// Caso literal — usar as const
+const dir = "ltr" as const;        // tipo: "ltr", no string
+```
+
+**Anti-patrón a evitar:** `const x = valor as any` para silenciar el error.
+
+---
+
+### TS2345 — Argument of type '{0}' is not assignable to parameter of type '{1}'
+
+**Causa:** Tipo incorrecto al llamar una función.
+
+```typescript
+function procesar(items: string[]) { ... }
+procesar([1, 2, 3]);   // TS2345 — number[] no es string[]
+
+// BIEN — corregir el tipo del argumento
+procesar(["a", "b"]);
+// o corregir el parámetro si el diseño lo permite
+function procesar(items: Array<string | number>) { ... }
+```
+
+---
+
+### TS2339 — Property '{0}' does not exist on type '{1}'
+
+**Causa:** Acceso a propiedad inexistente en la interfaz/tipo.
+
+```typescript
+interface Usuario { nombre: string; }
+const u: Usuario = { nombre: "Ana" };
+console.log(u.email);   // TS2339
+
+// BIEN — opción A: agregar al tipo
+interface Usuario { nombre: string; email?: string; }
+// BIEN — opción B: usar acceso indexado tipado
+function getField<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+```
+
+---
+
+### TS2353 — Object literal may only specify known properties
+
+**Causa:** Propiedad extra en object literal (excess property check).
+
+```typescript
+interface Config { host: string; port: number; }
+const cfg: Config = { host: "localhost", port: 3000, debug: true };  // TS2353
+
+// BIEN — eliminar o agregar al tipo
+// Nota: el excess property check solo aplica a object literals directos
+const base = { host: "localhost", port: 3000, debug: true };
+const cfg: Config = base;   // Válido — asignación indirecta no aplica la regla
+```
+
+---
+
+### TS2540 — Cannot assign to '{0}' because it is a read-only property
+
+**Causa:** Mutación de propiedad `readonly` o de `Readonly<T>`.
+
+```typescript
+interface Config { readonly host: string; }
+const cfg: Config = { host: "localhost" };
+cfg.host = "prod";   // TS2540
+
+// BIEN — crear nuevo objeto con spread
+const prodCfg: Config = { ...cfg, host: "prod" };
+```
+
+---
+
+### TS2739 — Type '{0}' is missing the following properties from type '{1}'
+
+**Causa:** Objeto incompleto — faltan propiedades requeridas.
+
+```typescript
+interface Producto { id: number; nombre: string; precio: number; }
+const p: Producto = { id: 1, nombre: "Widget" };   // TS2739 falta precio
+
+// BIEN
+const p: Producto = { id: 1, nombre: "Widget", precio: 9.99 };
+// O si la construcción es parcial
+const borrador: Partial<Producto> = { id: 1, nombre: "Widget" };
+```
+
+---
+
+### TS2741 — Property '{0}' is missing in type '{1}' but required in type '{2}'
+
+**Causa:** Al extender o implementar una interfaz, falta implementar una propiedad requerida.
+
+```typescript
+interface Animal { nombre: string; sonido: string; }
+const perro: Animal = { nombre: "Rex" };   // TS2741 falta sonido
+
+// BIEN — completar la implementación
+const perro: Animal = { nombre: "Rex", sonido: "Guau" };
+// O hacer la propiedad opcional si el diseño lo permite
+interface Animal { nombre: string; sonido?: string; }
+```
+
+---
+
+## Errores de null y undefined (TS2532, TS2533, TS2571)
+
+Activos con `strictNullChecks: true`.
+
+### TS2532 — Object is possibly 'undefined'
+
+**Causa:** Acceso a una propiedad sin verificar que el objeto no sea `undefined`.
+
+```typescript
+function getUser(id: number): User | undefined { ... }
+const user = getUser(1);
+console.log(user.nombre);   // TS2532
+
+// BIEN — opción A: narrowing explícito
+if (user !== undefined) { console.log(user.nombre); }
+
+// BIEN — opción B: optional chaining
+console.log(user?.nombre);
+
+// BIEN — opción C: non-null assertion SOLO cuando tienes garantía externa
+console.log(user!.nombre);   // Solo si sabes que no puede ser undefined
+```
+
+---
+
+### TS2533 — Object is possibly 'null' or 'undefined'
+
+**Causa:** Acceso sin verificar que no sea ni `null` ni `undefined`.
+
+```typescript
+const el = document.getElementById("app");
+el.innerHTML = "hola";   // TS2533
+
+// BIEN
+if (el !== null) { el.innerHTML = "hola"; }
+// O
+el?.innerHTML;   // Silencioso si el es null — cuidado con efectos secundarios
+```
+
+---
+
+### TS2571 — Object is of type 'unknown'
+
+**Causa:** Intento de usar una variable de tipo `unknown` sin narrowing.
+
+```typescript
+async function fetchData(): Promise<unknown> { ... }
+const data = await fetchData();
+console.log(data.nombre);   // TS2571
+
+// BIEN — type guard
+function isUsuario(x: unknown): x is Usuario {
+  return typeof x === "object" && x !== null && "nombre" in x;
+}
+if (isUsuario(data)) { console.log(data.nombre); }
+
+// BIEN — instanceof
+try { ... } catch (e: unknown) {
+  if (e instanceof Error) { console.error(e.message); }
+}
+```
+
+---
+
+## Errores de módulo (TS2304, TS2305, TS2307)
+
+### TS2304 — Cannot find name '{0}'
+
+**Causa:** Variable, tipo o función no importado o no declarado.
+
+```typescript
+const resultado = calcular(5);   // TS2304 si calcular no está importado
+
+// BIEN
+import { calcular } from "./utils/calcular";
+```
+
+---
+
+### TS2305 — Module '{0}' has no exported member '{1}'
+
+**Causa:** Import de algo que no está exportado en el módulo de origen.
+
+```typescript
+import { calcular, formatear } from "./utils";   // TS2305 si formatear no se exporta
+
+// Verificar que el módulo lo exporta
+export function formatear(n: number): string { ... }
+```
+
+---
+
+### TS2307 — Cannot find module '{0}' or its corresponding type declarations
+
+**Causa:** Módulo sin declaraciones de tipos o ruta incorrecta.
+
+```typescript
+import express from "express";   // TS2307 si @types/express no está instalado
+import { algo } from "./ruta-inexistente";   // TS2307
+
+// BIEN — instalar tipos
+// npm install --save-dev @types/express
+
+// BIEN — declaración manual para módulos sin @types
+declare module "nombre-del-modulo" {
+  export function fn(): void;
+}
+```
+
+---
+
+## Errores de implicit any (TS7xxx)
+
+Activos con `noImplicitAny: true` (incluido en `strict: true`).
+
+### TS7006 — Parameter '{0}' implicitly has an '{1}' type
+
+**Causa:** Parámetro de función sin anotación de tipo.
+
+```typescript
+// MAL
+function duplicar(n) { return n * 2; }   // TS7006
+
+// BIEN
+function duplicar(n: number): number { return n * 2; }
+```
+
+---
+
+### TS7010 — '{0}', which lacks return-type annotation, implicitly has an '{1}' return type
+
+**Causa:** Función cuyo tipo de retorno no puede inferirse claramente.
+
+```typescript
+// MAL — TypeScript infiere 'any' en casos ambiguos
+function cargar(url) { return fetch(url).then(r => r.json()); }
+
+// BIEN
+async function cargar(url: string): Promise<unknown> {
+  const resp = await fetch(url);
+  return resp.json() as unknown;
+}
+```
+
+---
+
+### TS7016 — Could not find a declaration file for module '{0}'
+
+**Causa:** Módulo npm sin `@types/` ni declaraciones propias.
+
+```typescript
+import algo from "libreria-sin-tipos";   // TS7016
+
+// Solución A — instalar tipos comunitarios
+// npm install --save-dev @types/libreria-sin-tipos
+
+// Solución B — declaración mínima en src/types/libreria-sin-tipos.d.ts
+declare module "libreria-sin-tipos" {
+  const value: unknown;
+  export default value;
+}
+
+// Solución C — skipLibCheck (solo en casos excepcionales, documenta por qué)
+// tsconfig.json: { "compilerOptions": { "skipLibCheck": true } }
+```
+
+---
+
+### TS7017 — Element implicitly has an 'any' type because type '{0}' has no index signature
+
+**Causa:** Acceso con key dinámica a un objeto sin index signature.
+
+```typescript
+const config = { host: "localhost", port: 3000 };
+const key = "host";
+const value = config[key];   // TS7017
+
+// BIEN — opción A: keyof
+function getConfig<K extends keyof typeof config>(key: K): typeof config[K] {
+  return config[key];
+}
+
+// BIEN — opción B: Map con tipo explícito
+const configMap = new Map<string, string | number>();
+configMap.set("host", "localhost");
+
+// BIEN — opción C: Record si los valores son homogéneos
+const config: Record<string, string> = { host: "localhost" };
+```
+
+---
+
+### TS7031 — Binding element '{0}' implicitly has an '{1}' type
+
+**Causa:** Destructuring de parámetro sin anotación.
+
+```typescript
+// MAL
+function render({ nombre, edad }) { ... }   // TS7031
+
+// BIEN
+interface Props { nombre: string; edad: number; }
+function render({ nombre, edad }: Props) { ... }
+```
+
+---
+
+## Errores de función y callable (TS2349, TS2355, TS2554, TS2769)
+
+### TS2349 — This expression is not callable
+
+**Causa:** Intentar llamar algo que no es una función según los tipos.
+
+```typescript
+const handler: string | (() => void) = "texto";
+handler();   // TS2349 — podría ser string
+
+// BIEN
+if (typeof handler === "function") { handler(); }
+```
+
+---
+
+### TS2355 — A function whose declared type is neither 'undefined', 'void', nor 'any' must return a value
+
+**Causa:** No todos los branches de la función retornan un valor.
+
+```typescript
+function dividir(a: number, b: number): number {
+  if (b !== 0) { return a / b; }
+  // TS2355 — no hay return en el else
+}
+
+// BIEN
+function dividir(a: number, b: number): number {
+  if (b === 0) throw new Error("División por cero");
+  return a / b;
+}
+```
+
+---
+
+### TS2554 — Expected {0} arguments, but got {1}
+
+**Causa:** Número incorrecto de argumentos al llamar una función.
+
+```typescript
+function sumar(a: number, b: number): number { return a + b; }
+sumar(1);          // TS2554 — faltan argumentos
+sumar(1, 2, 3);    // TS2554 — argumentos de más
+
+// BIEN — si el tercer argumento es opcional
+function sumar(a: number, b: number, c?: number): number {
+  return a + b + (c ?? 0);
+}
+```
+
+---
+
+### TS2769 — No overload matches this call
+
+**Causa:** Ninguna de las sobrecargas de una función acepta los tipos de argumentos dados.
+
+```typescript
+// Función con sobrecargas
+function procesar(x: string): string;
+function procesar(x: number): number;
+function procesar(x: string | number): string | number { return x; }
+
+procesar(true);   // TS2769 — boolean no coincide con ninguna sobrecarga
+
+// BIEN — verificar qué sobrecargas existen y pasar el tipo correcto
+procesar("texto");   // OK
+procesar(42);        // OK
+```
+
+---
+
+## Errores de cast (TS2352, TS2693)
+
+### TS2352 — Conversion of type '{0}' to type '{1}' may be a mistake
+
+**Causa:** Cast (`as`) entre tipos sin superposición de propiedades.
+
+```typescript
+const n = 42;
+const s = n as string;   // TS2352 — number y string no se superponen
+
+// Anti-patrón — doble cast para evadir el error
+const s = n as unknown as string;   // Compila pero es inseguro
+
+// BIEN — convertir correctamente
+const s = String(n);
+```
+
+---
+
+### TS2693 — '{0}' only refers to a type, but is being used as a value here
+
+**Causa:** Usar una interfaz o tipo como valor en runtime.
+
+```typescript
+interface Config { host: string; }
+if (x instanceof Config) { ... }   // TS2693 — interfaces no existen en runtime
+
+// BIEN — usar type guard con validación de propiedades
+function isConfig(x: unknown): x is Config {
+  return typeof x === "object" && x !== null && "host" in x;
+}
+```
+
+---
+
+## Referencia rápida — códigos por categoría
+
+| Categoría | Códigos frecuentes |
+|-----------|-------------------|
+| Asignación de tipos | TS2322, TS2345, TS2739, TS2741 |
+| Null/undefined | TS2532, TS2533, TS2571 |
+| Propiedades | TS2339, TS2353, TS2540 |
+| Módulos | TS2304, TS2305, TS2307 |
+| Implicit any | TS7006, TS7010, TS7016, TS7017, TS7031 |
+| Función/callable | TS2349, TS2355, TS2554, TS2769 |
+| Cast | TS2352, TS2693 |
+
+## Comandos de diagnóstico
+
+```bash
+# Ver todos los errores del proyecto agrupados por código
+npx tsc --noEmit 2>&1 | grep -oP 'TS\d+' | sort | uniq -c | sort -rn
+
+# Ver el detalle de los primeros 20 errores
+npx tsc --noEmit 2>&1 | head -60
+
+# Buscar supresiones en el código fuente
+grep -rn "@ts-ignore\|@ts-expect-error\|as any\|as unknown as" \
+  --include="*.ts" --include="*.tsx" \
+  --exclude-dir=node_modules --exclude-dir=dist | head -30
+
+# Verificar strict mode activo
+cat tsconfig.json | grep -E '"strict"|"noImplicitAny"|"strictNullChecks"'
+```
+
+## Gotchas / Errores comunes no obvios
+
+**TS2339 en código correcto después de actualizar TypeScript**: un upgrade de TS 4.x a 5.x puede revelar TS2339 en código que antes compilaba porque las definiciones de tipo de `@types/node` o librerías cambiaron. Causa: librerías como `express` o `mongoose` actualizan sus `@types/*` con definiciones más estrictas — una propiedad que era `any` ahora tiene tipo concreto. Fix: actualizar las dependencias `@types/*` junto con TypeScript, no solo el compilador.
+
+**TS2590 "Expression produces a union type that is too complex to represent"**: ocurre al hacer operaciones sobre uniones grandes (más de ~25 miembros) como `Partial<A & B & C>` donde A, B, C son interfaces con muchos campos. Causa: TypeScript tiene un límite interno de complejidad en la representación de tipos. Fix: dividir la unión en tipos intermedios nombrados, o usar `interface` con `extends` en lugar de intersección `&` para reducir la profundidad de evaluación.
+
+**`// @ts-ignore` suprime el error siguiente pero también errores reales en la misma línea**: si una línea tiene dos errores y se pone `@ts-ignore`, ambos se suprimen — incluyendo uno legítimo que debería corregirse. Fix: preferir `// @ts-expect-error` que falla en CI si el error desaparece (señal de que la supresión ya no es necesaria), y anotar el código TS#### específico en el comentario.
+
+**TS7031 en callbacks de arrays sin anotación de contexto**: `[1, 2, 3].reduce((acc, val) => acc + val)` falla con TS7031 "Binding element 'acc' implicitly has an 'any' type" si `noImplicitAny: true` y TypeScript no puede inferir el tipo inicial del acumulador. Fix: anotar el valor inicial explícitamente: `.reduce((acc, val) => acc + val, 0)` — el tipo del acumulador se infiere del valor inicial, no del callback.
+
+## Fuente
+
+- `temp/TypeScript-main/src/compiler/diagnosticMessages.json` — 8,559 líneas, fuente primaria
+- Compilador TypeScript oficial: `microsoft/TypeScript` (modo mantenimiento; TS 7.0 se reescribe en Go)
+- Documentación oficial: https://www.typescriptlang.org/tsconfig

package/habilidades/ux-diseno/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ux-diseno
+description: Principios de UX design para desarrolladores. Heurísticas de Nielsen, Fitts's Law, Ley de Miller, Gestalt, jerarquía visual, micro-interacciones, feedback visual, estados vacíos, error states, loading states.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+exclusiones:
+  - "No cargar para accesibilidad técnica (ARIA, contraste WCAG, navegación por teclado, lectores de pantalla) — para accesibilidad cargar `accesibilidad-a11y`."
+  - "No cargar para implementación CSS/Tailwind de los diseños — los principios aquí son conceptuales; para implementación cargar `css-moderno` o `tailwind-experto`."
+  - "No cargar para investigación de usuario, entrevistas o user research — este skill cubre decisiones de diseño de implementación, no metodología de research."
+  - "No cargar para diseño de sistemas de diseño (Design Tokens, Storybook, Figma) — este skill cubre principios UX aplicados al código, no herramientas de diseño."
+evolvable: true  # default para skill estandar
+---
+# UX Design para Desarrolladores
+
+## Cuándo NO cargar
+
+- La tarea es accesibilidad técnica: ARIA correcta, contraste WCAG 2.1, focus trap, lectores de pantalla — cargar `accesibilidad-a11y`.
+- La implementación concreta es en CSS o Tailwind — los principios aquí son conceptuales; para implementación cargar `css-moderno` o `tailwind-experto`.
+- La tarea es investigación de usuario, entrevistas o user testing — este skill cubre decisiones de diseño en el código, no metodología de research.
+- El tema es sistemas de diseño: Design Tokens, Storybook, integración Figma — este skill cubre principios UX, no herramientas de diseño.
+
+Un desarrollador que entiende UX toma mejores decisiones de implementación sin necesitar
+validación en cada detalle visual. Estos principios reducen fricción y aumentan la usabilidad
+sin depender de un diseñador para cada componente.
+
+---
+
+## 1. Las 10 Heurísticas de Nielsen (resumen activo)
+
+- **H1 — Visibilidad del estado**: Feedback inmediato. Loading states: skeleton > spinner > texto.
+- **H2 — Match con el mundo real**: Hablar el idioma del usuario, no del desarrollador. NUNCA mostrar "Error 500" o UUIDs.
+- **H3 — Control y libertad**: Botón "Cancelar", "Deshacer", confirmación antes de eliminar, breadcrumbs.
+- **H4 — Consistencia**: Mismas convenciones siempre. Azul subrayado = enlace. Logo = inicio. X = cerrar. Escape = cancelar.
+- **H5 — Prevención de errores**: Deshabilitar botón hasta formulario válido. Máscaras de input. Confirmar acciones peligrosas.
+- **H6 — Reconocimiento antes que recuerdo**: Mostrar contexto entre pasos. Autocompletar. Progreso visible.
+- **H7 — Flexibilidad**: Keyboard shortcuts, acciones en masa, filtros guardados.
+- **H8 — Diseño minimalista**: Eliminar texto que nadie lee, campos que nadie llena, iconos sin texto.
+- **H9 — Recuperación de errores**: Mensaje = Qué pasó + Por qué + Qué hacer. Ejemplo: "El RFC debe tener 13 caracteres. Ejemplo: PEGJ850101GR5".
+- **H10 — Ayuda**: Tooltips en campos técnicos, links a artículos, ejemplos reales en errores.
+
+---
+
+## 2. Ley de Fitts — Tamaño y Distancia
+
+Objetivos más grandes y más cercanos son más fáciles de alcanzar.
+
+- Botones de acción principal: mínimo 44x44px de área táctil (estándar de accesibilidad)
+- Acciones destructivas ALEJADAS de las primarias y con menor prominencia visual
+- Acción principal prominente y a la derecha en formularios
+
+---
+
+## 3. Ley de Miller — 7 más o menos 2
+
+- Menú de navegación: máximo 7 opciones de primer nivel
+- Pasos de wizard: máximo 5-7 pasos
+- Columnas en tabla: máximo 7 visibles sin scroll
+- Opciones en dropdown: si hay más de 7, agregar búsqueda
+- Formulario: agrupar campos en secciones (máximo 7 por sección)
+
+---
+
+## 4. Principios Gestalt
+
+- **Proximidad**: Elementos cercanos parecen relacionados. Poco espacio dentro del grupo, mucho entre secciones.
+- **Similitud**: Mismo color + estilo = misma función. NUNCA mismo color para funciones distintas.
+- **Continuidad**: Alineación para guiar al ojo. Labels alineados, columnas numéricas a la derecha.
+
+---
+
+## 5. Estados que Toda UI Debe Manejar
+
+Toda pantalla con datos debe implementar estos 4 estados:
+
+1. **Loading**: Skeleton loader para listas, spinner inline para acciones puntuales
+2. **Empty state**: Contexto + acción ("No hay expedientes. Crear expediente")
+3. **Error state**: Qué pasó + qué hacer + botón reintentar
+4. **Success/Data**: El estado normal con datos
+
+---
+
+## 6. Checklist Pre-Entrega de UI
+
+Antes de marcar cualquier feature de UI como terminada, verificar cada punto con
+valores operativos concretos — no con criterios subjetivos como "se ve bien":
+
+| Aspecto | Requisito operativo | Anti-patrón a evitar |
+|---------|--------------------|-----------------------|
+| **Iconos** | SVG de librería consistente (Heroicons, Lucide, Material Symbols). Un solo set por proyecto | Emojis como iconos funcionales — no se renderizan igual entre plataformas |
+| **Cursores** | `cursor: pointer` en todo elemento clicable: botones, enlaces, toggles, tabs, cards clicables | Elementos clicables con cursor default — el usuario no sabe que puede interactuar |
+| **Hover/Active** | Transición de 150–300ms. Hover muestra cambio visual; active muestra feedback de presión | Transiciones > 500ms (se sienten lentas) o 0ms (se sienten rotas) |
+| **Contraste** | Texto normal 4.5:1, texto grande 3:1, componentes de UI 3:1 (WCAG 2.1 AA) | Texto gris claro sobre fondo blanco — falla contraste en todos los monitores |
+| **Foco teclado** | `focus-visible` con anillo de 2px de contraste 3:1 contra el fondo. Tab order lógico | `outline: none` sin reemplazo — invisible para usuarios de teclado |
+| **Movimiento** | `@media (prefers-reduced-motion: reduce)` desactiva animaciones no esenciales | Animaciones sin escape — usuarios con vértigo o epilepsia fotosensible |
+| **Breakpoints** | Verificar en 375px (móvil), 768px (tablet), 1024px (laptop), 1440px (desktop) | Solo probar en 1 resolución — se rompe en el dispositivo del usuario |
+| **Estados** | Loading (skeleton), empty, error (qué pasó + qué hacer), success — los 4 siempre | Solo el happy path — la primera interacción del usuario suele ser el empty state |
+| **Touch targets** | Mínimo 44×44px de área táctil en móvil. Separación mínima de 8px entre targets | Botones de 24px — imposibles de presionar con precisión en pantalla táctil |
+
+---
+
+## Patrones de Referencia Completos
+
+Para implementaciones de jerarquía visual (escala tipográfica), estados de UI
+con código HTML/CSS, micro-interacciones, formularios UX, mobile first, y tabla
+completa de anti-patrones UX, ver
+[recursos/patrones-ux-referencia.md](recursos/patrones-ux-referencia.md).
+
+## Gotchas / Errores comunes no obvios
+
+**Los skeleton loaders que no coinciden con el layout real crean un "layout shift" perceptible al resolver**: si el skeleton muestra 3 líneas horizontales pero el contenido real es una tarjeta con imagen y botones, el usuario percibe un salto visual brusco al cargar. Causa: el skeleton debe ser una aproximación fiel del contenido real. Fix: construir el skeleton usando los mismos contenedores y proporciones del componente real, solo reemplazando el contenido con barras animadas — usar las mismas clases de grid/flex del componente original.
+
+**Deshabilitar el botón de submit durante la validación de formulario frustran a usuarios mobile**: en dispositivos táctiles con teclado virtual, el usuario cierra el teclado y toca el botón — si el botón está deshabilitado porque el campo no pasó validación, el usuario no recibe feedback de por qué. Causa: la validación inline (campo por campo) no siempre es visible cuando el teclado oculta parte del formulario. Fix: permitir el submit siempre, mostrar todos los errores inline al enviar, y enfocar automáticamente el primer campo con error (`scrollIntoView()` + `focus()`).
+
+**Mensajes de error genéricos ("Algo salió mal") bloquean al usuario más que los técnicos**: en producción es tentador mostrar mensajes genéricos para no exponer internos, pero el usuario no puede resolver un error sin saber qué hacer. Causa: confundir privacidad de implementación con utilidad del mensaje de error. Fix: separar el mensaje visible del usuario (qué pasó en términos de negocio + qué puede hacer) del log interno (detalles técnicos). El mensaje de error debe responder: ¿Qué pasó? + ¿Por qué? + ¿Qué hago ahora?
+
+**El estado vacío (empty state) con solo texto "No hay resultados" no guía al usuario al siguiente paso**: el empty state es frecuentemente la primera pantalla que ve un usuario nuevo — si solo dice "No tienes facturas" sin una CTA clara, el usuario no sabe cómo empezar. Causa: el empty state se diseña como excepción en lugar de como estado de onboarding. Fix: el empty state debe tener: ícono/ilustración que contextualice, texto que explique qué puede hacer aquí, y un botón de acción primaria que lleve al siguiente paso ("Crear primera factura").

package/habilidades/ux-diseno/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "ux-diseno",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para ux-diseno — principios de diseño de interacción, jerarquía, affordances.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Un formulario tiene 15 campos y el usuario lo abandona. ¿Primer heurística a revisar?",
+      "files": [],
+      "expectations": [
+        "Reducir campos a los estrictamente necesarios.",
+        "La respuesta menciona que cada campo añade fricción medible.",
+        "Sugiere: progressive disclosure, auto-fill, valores por defecto razonables."
+      ],
+      "tags": ["forms"]
+    },
+    {
+      "id": "anti-modal-abuse",
+      "prompt": "La app tiene modal tras modal — ¿bien o mal?",
+      "files": [],
+      "expectations": [
+        "Anti-patrón — los modales interrumpen el flujo.",
+        "Reglas: reservar para confirmaciones críticas/bloqueantes o información focus-requerida.",
+        "Alternativas: drawer lateral, inline editing, toast."
+      ],
+      "grading_guidance": "Failure si justifica modales sin restricciones.",
+      "tags": ["anti-pattern"]
+    },
+    {
+      "id": "feedback",
+      "prompt": "Usuario presiona botón de submit y no pasa nada visible por 2 segundos. ¿Qué le falta?",
+      "files": [],
+      "expectations": [
+        "Feedback inmediato (<100ms): cambio de estado del botón (disabled, loading spinner).",
+        "La respuesta menciona que sin feedback el usuario vuelve a clickar → double submit.",
+        "Cita umbrales de percepción (100ms instantáneo, 1s tolerable)."
+      ],
+      "tags": ["feedback"]
+    }
+  ]
+}