create-lexy 0.6.1 → 0.6.3

package/templates/ai/TECHNICAL-USAGE.md

@@ -0,0 +1,220 @@
+# Guía técnica de uso del proyecto Lexy
+
+Esta guía es para devs y agentes de IA que trabajan dentro de un proyecto Lexy
+(creado con `create-lexy`). Es el **anexo técnico que ejecuta la skill `lexy-dev`**;
+el flujo de trabajo lo define esa skill, no este documento.
+
+## El modelo registry (léelo primero)
+
+**Los componentes viven en tu proyecto.** No hay librería npm de componentes: el
+catálogo Lexy es un registry versionado (`@lexydesign/registry`) y el CLI
+`create-lexy` trae cada componente como código local — tuyo y editable.
+
+- **Míralo** antes de instalar: `npx create-lexy view button` (código + doc + metadata).
+- **Instálalo**: `npx create-lexy add button` (con sus dependencias, en la ruta de `.lexy`).
+- **Edítalo localmente con libertad**: es código del proyecto, no hay internals prohibidos.
+- **Mantén la divergencia visible**: `diff` y `doctor` comparan tu copia con el registry vigente.
+
+## Archivos de referencia
+
+- `.lexy`: configuración generada del proyecto. Define arquitectura, rutas reales y componentes instalados (con la versión del registry con la que entraron).
+- [ai/lexy-ai-manifest.json](lexy-ai-manifest.json): índice técnico generado — comandos del registry, patrón de import local (`componentImportPattern`) y rutas del prototipo.
+- `src/prototype/data-contract/prototype-data-contract.ts`: fuente de verdad de entidades, campos, relaciones, estados y proyecciones usados por la experiencia. Confirma la ruta exacta en el manifest.
+- `src/prototype/ports/`: interfaces y adapters mock/producción para cargas de datos y eventos publicados.
+- `src/prototype/mock-store/fixtures.ts`: registros sintéticos iniciales.
+- `src/prototype/mock-store/mock-store.ts`: estado mock compartido y persistente.
+- [ai/IMPLEMENTATION-PROTOCOL.md](IMPLEMENTATION-PROTOCOL.md): protocolo para implementar interfaces con componentes del registry.
+- [AGENTS.md](../AGENTS.md): prompt base para agentes.
+- [ai/pautas/](pautas/): criterios de diseño y UX writing.
+
+Antes de crear archivos propios o escribir imports, lee `.lexy` y usa sus rutas como fuente de verdad.
+Antes de implementar UI, lee `ai/IMPLEMENTATION-PROTOCOL.md`.
+
+## Comandos del proyecto
+
+```bash
+pnpm dev              # vista previa
+pnpm check:data-contract # valida el contrato de datos
+pnpm check:prototype     # valida el contrato del prototipo
+pnpm build            # valida el prototipo y crea el build de producción
+pnpm build:app        # build de aplicación sin repetir el chequeo explícito
+pnpm preview          # revisar el build
+pnpm lint:geometry    # contrato de geometría Lexy (espaciado, radios, sombras)
+```
+
+## Contrato de datos
+
+Antes de agregar un dato visible, editable, calculado o filtrable a una pantalla:
+
+1. revisa el contrato indicado por `prototype.dataContractPath` en el manifest;
+2. declara el dato y sus relaciones o proyecciones;
+3. usa IDs frontend `camelCase`;
+4. conserva nombres backend `snake_case` únicamente en `source.reference`;
+5. marca como `generatedByUsability` + `pendingTi` lo que aún deba validar TI;
+6. ejecuta `pnpm check:data-contract`.
+
+El contrato no contiene registros mock, datos personales reales, eventos ni
+persistencia. Describe qué datos existen y qué significan para la experiencia.
+
+## Ports de lectura y escritura
+
+Los componentes importan `read` y `write` desde `src/prototype/ports`:
+
+```ts
+const leads = await read.load("Crm_Leads-ListaLeads_V1", params, {
+  description: "Carga el listado de leads.",
+  reads: { entities: ["lead"] },
+});
+
+const receipt = await write.publish("Crm_Leads-LeadCreado_V1", payload, {
+  description: "Publica la creación de un lead.",
+  writes: { entities: ["lead"], fields: ["lead.nombre"] },
+});
+```
+
+Una lectura devuelve datos o lanza un error. Una publicación devuelve
+`{ eventId, status }`, donde `status` es un código HTTP. Un filtro sobre datos ya
+cargados es local y no requiere `read.load`.
+
+En diseño, `ports/index.ts` usa los adapters mock; en producción se conecta
+`productionRead` al GET real y `productionWrite` a la publicación/worker. No
+cambies los componentes para hacer ese swap.
+
+## Mock-store persistente
+
+La data mock no vive en componentes. Vive en:
+
+- `src/prototype/mock-store/fixtures.ts`: dataset inicial;
+- `src/prototype/mock-store/mock-store.ts`: estado compartido, suscripciones y
+  persistencia local;
+- `src/prototype/ports/mock-read.ts`: lecturas genéricas por metadata `reads`;
+- `src/prototype/ports/mock-write.ts`: publicaciones, receipt y mutación genérica
+  por metadata `writes`.
+
+Los datos deben ser sintéticos, explícitos y deterministas. Usa RUT, teléfonos,
+fechas, CLP y correos con formato chileno. Incrementa `datasetVersion` cuando
+cambies fixtures persistibles y ejecuta `pnpm check:prototype`.
+
+## Comandos del registry
+
+```bash
+npx create-lexy view --list        # catálogo completo
+npx create-lexy view button        # ver un componente antes de instalar
+npx create-lexy view button --installed   # ver la copia local
+npx create-lexy add button         # instalar (resuelve dependencias internas)
+npx create-lexy add button --overwrite    # re-instalar pisando cambios locales
+npx create-lexy diff button        # copia local vs registry vigente (exit 1 si difiere)
+npx create-lexy doctor             # salud del proyecto + drift de lo instalado
+npx create-lexy doctor --strict    # las ediciones locales también fallan (CI)
+```
+
+## Crear un proyecto nuevo
+
+```bash
+npx create-lexy create mi-app                       # interactivo
+npx create-lexy create mi-app -t feature -w crm     # automatizado (feature, CRM)
+npx create-lexy create mi-app -t layer -w cliente   # automatizado (layer, cliente)
+```
+
+## Arquitecturas y paths
+
+El import local depende de la arquitectura de `.lexy`. El patrón exacto vive en
+`componentImportPattern` del manifest; estos son los dos casos:
+
+### Feature
+
+- Componentes: `src/shared/components/base`
+- Hooks: `src/shared/hooks` · Servicios: `src/shared/services` · Utilidades: `src/shared/lib` · Vistas: `src/features`
+- Helper `cn`: `@/shared/lib/utils/cn`
+- Import: `import { Button } from "@/shared/components/base/Button";`
+
+### Layer
+
+- Componentes: `src/components/base`
+- Hooks: `src/hooks` · Servicios: `src/services` · Utilidades: `src/lib` · Vistas: `src/views`
+- Helper `cn`: `@/lib/utils/cn`
+- Import: `import { Button } from "@/components/base/Button";`
+
+## Qué hace `add` exactamente
+
+- Resuelve el componente y sus **dependencias internas transitivas** (por ejemplo, un combobox trae también su popover y su botón).
+- Copia los archivos a la ruta de componentes definida en `.lexy`, **incluida la guía `{Component}.md`** (viaja junto al código para que un agente la lea al trabajar).
+- Adapta el import del helper `cn` a la arquitectura del proyecto.
+- Instala **solo** las dependencias npm que el proyecto aún no tiene.
+- Anota la versión en `.lexy` → `installed`, para que `diff`/`doctor` puedan razonar el drift.
+- Si tu copia local tiene cambios, **pide confirmación** antes de sobrescribir (`--overwrite` para CI/agentes).
+
+## Editar componentes instalados
+
+Editar la copia local es el flujo normal del modelo — no hay "internals" prohibidos.
+Reglas de oficio:
+
+- Mantén `pnpm lint:geometry` en verde: el contrato de geometría se fiscaliza en cada repo.
+- Actualiza el `{Component}.md` local si cambias la API o el comportamiento.
+- La divergencia queda visible en `doctor` como _"editado localmente"_: es información, no error. Si más adelante quieres volver a la versión del registry, `add --overwrite`.
+
+## Diagnosticar el proyecto
+
+Comando de solo lectura. No modifica ni instala nada:
+
+```bash
+npx create-lexy doctor
+```
+
+Verifica:
+
+- `.lexy` existe y es JSON válido (arquitectura, rutas, instalados).
+- El theme (`src/lexy-theme.css`) y el helper `cn` están presentes.
+- Por cada componente instalado: archivos presentes y su estado frente al registry vigente — **al día**, **desactualizado** (el registry avanzó; exit 1) o **editado localmente** (aviso; con `--strict`, exit 1).
+- La capa de IA instalada (este directorio) está completa según el manifest.
+
+Exit code `0` si todo está OK y `1` si hay algo roto o desactualizado, por lo que sirve en CI.
+
+## Componentes disponibles
+
+El catálogo vivo es el registry: `npx create-lexy view --list` lo consulta
+(no se duplica aquí ni en el manifest — así no puede driftar). La guía de uso de
+cada componente es su companion doc `{Component}.md`: instalada junto al
+componente, o visible con `view` antes de instalar.
+
+Regla rápida para componer: para sidebar, header, diálogo y acordeón usa las
+versiones **data-driven** (`AppSidebar`, `AppHeaderBar`, `AppDialog`,
+`AppAccordion`); para el layout de una app interna, `SidebarProvider` +
+`AppSidebar` + `SidebarInset`. Las primitivas equivalentes son para
+composiciones a medida.
+
+## Reglas para agentes de IA
+
+1. Antes de implementar una interfaz, descubre los componentes con `npx create-lexy view --list` y revisa los elegidos con `view {component}`.
+2. Si un componente existe en el registry, **instálalo** (`add`) — no lo reescribas a mano ni lo reemplaces con HTML/CSS propio.
+3. La ausencia de componentes locales no significa ausencia de sistema; significa que aún no los has instalado.
+4. Usa el import local que corresponde a `.lexy` (`componentImportPattern` del manifest). No inventes rutas.
+5. Edita los componentes instalados cuando el diseño lo pida — esa libertad es el modelo. Mantén `lint:geometry` en verde y el `{Component}.md` al día.
+6. Si necesitas un componente que no está en el catálogo, confirma con `view` que no hay equivalente y créalo siguiendo los patrones del proyecto (o propónlo para el registry).
+7. Todo lo de **diseño** (qué componente elegir y por qué, cliente vs CRM, densidad y espaciado, accesibilidad, jerarquía y landmarks, UX writing, progressive disclosure) tiene su fuente de verdad en las pautas de `ai/pautas/`. Léelas según el tema; no infieras estas reglas desde este documento ni desde el manifest.
+8. Antes de cerrar, valida contra el `## Criterio final` de `ai/IMPLEMENTATION-PROTOCOL.md`: contratos de experiencia, técnico, accesibilidad, jerarquía, microcopy y arquitectura de información.
+9. No agregues a la UI datos que no estén declarados en el contrato cuando
+   `prototype.enabled` sea `true`.
+10. No pegues fixtures mock en componentes; usa `prototype.fixturesPath`.
+11. No llames evento a una lectura remota; usa `read.load`.
+12. No llames al backend directamente desde componentes; conserva el límite de
+    los ports.
+
+## Cuando implementes desde Figma
+
+La referencia visual es un **contrato de patrón**. Las reglas de lectura (qué
+observar y conservar) viven en
+[ai/pautas/arquitectura-informacion-ux.md](pautas/arquitectura-informacion-ux.md)
+(«Referencias visuales») y el detalle de implementación en
+[ai/IMPLEMENTATION-PROTOCOL.md](IMPLEMENTATION-PROTOCOL.md) («Cuando hay
+referencia Figma»). En corto: identifica el patrón antes de escribir código,
+materialízalo con componentes del registry y no agregues secciones que la
+referencia no muestra.
+
+## Retirar la infraestructura de IA
+
+Los archivos de contexto de IA no son necesarios para ejecutar la aplicación y
+pueden retirarse antes de producción. El comando exacto y la verificación de
+referencias residuales viven **solo** en
+[ai/PRODUCTION-CLEANUP.md](PRODUCTION-CLEANUP.md); síguelo desde ahí para no
+borrar de más ni de menos.

package/templates/ai/pautas/arquitectura-informacion-ux.md

@@ -0,0 +1,243 @@
+# Arquitectura de informacion y carga visual
+
+Esta pauta guía cómo ordenar información en interfaces Lexy para que sean claras, progresivas y fáciles de leer. Úsala junto con la filosofía de cliente o CRM y la guía de UX writing.
+
+## Regla base
+
+La interfaz no debe mostrar todo al mismo tiempo para parecer completa. Debe mostrar primero lo que permite avanzar, y revelar el resto cuando el usuario lo necesita.
+
+Una buena pantalla Lexy tiene:
+
+- Un foco principal evidente.
+- Un título que explica la tarea o el estado, no una etiqueta decorativa.
+- Secciones agrupadas por decisión o acción.
+- Jerarquía visual suficiente para escanear sin leer todo.
+- Contenido secundario disponible, pero no compitiendo con la acción principal.
+- Accesibilidad resuelta desde la estructura: orden lógico, etiquetas claras, foco visible y estados que no dependan solo del color.
+
+## Jerarquía
+
+La jerarquía ayuda a que la persona entienda dónde está, qué es importante y qué puede hacer. Debe existir en dos niveles al mismo tiempo:
+
+- **Jerarquía visual:** tamaño, peso, espaciado, contraste, color, forma, iconos, movimiento y posición.
+- **Jerarquía semántica:** orden del HTML, landmarks, headings, labels y foco.
+
+La jerarquía visual y la semántica deben coincidir. Si la pantalla se ve como un flujo claro pero el HTML se lee desordenado, la interfaz falla para tecnologías asistivas y también aumenta el riesgo de errores de implementación.
+
+### Feedback y disponibilidad
+
+Usa feedback visual, textual y de interacción para mostrar qué está disponible:
+
+- Labels visibles para controles y campos.
+- Estados claros: activo, seleccionado, deshabilitado, error, éxito, pendiente.
+- Iconos como apoyo, no como única explicación.
+- Color con texto o forma adicional cuando comunica estado.
+- Feedback de foco, hover, active y loading cuando corresponda.
+
+### Reducir complejidad
+
+Cada botón, imagen, icono, línea de texto, card y separador aumenta la complejidad de la UI. Antes de agregar algo, pregunta:
+
+- ¿Ayuda a ubicar a la persona?
+- ¿Aclara qué es importante?
+- ¿Permite actuar o decidir?
+- ¿Reduce riesgo, error o ansiedad?
+
+Si no cumple ninguna, elimínalo.
+
+### Niveles de importancia
+
+Para expresar importancia relativa:
+
+- Coloca acciones principales arriba o abajo de la pantalla, en zonas fáciles de encontrar.
+- Mantén juntas las acciones relacionadas.
+- Agrupa elementos de jerarquía similar.
+- Evita que acciones secundarias compitan con la acción principal.
+- Usa contraste, tamaño y espaciado para dirigir la mirada, no solo color.
+
+### Landmarks y headings web
+
+Las tecnologías asistivas transforman la pantalla en una experiencia lineal. Por eso el orden del DOM, landmarks y headings importan tanto como el layout visual.
+
+Usa estos landmarks cuando correspondan:
+
+- `nav`: listas o grupos de navegación. Si hay más de uno, usa `aria-label` para diferenciarlos.
+- `search`: búsqueda principal o contextual.
+- `main`: contenido principal de la página. Debe haber solo uno.
+- `header`: cabecera o banner repetido de la página.
+- `aside`: contenido complementario que puede entenderse por separado.
+- `footer`: información final o legal del sitio.
+- `section`: región importante dentro de `main`, etiquetada con heading claro.
+- `form`: bloque que captura o envía información.
+
+Reglas:
+
+- Un solo `h1` para el propósito principal de la página.
+- Usa `h2` para secciones principales y `h3` para subsecciones.
+- No saltes niveles de heading solo para conseguir un tamaño visual.
+- El orden del DOM debe seguir el orden de lectura esperado.
+- En grillas, el orden debe leerse de izquierda a derecha y de arriba abajo.
+- Si una región es importante, su nombre debe ser claro para navegación asistiva.
+
+## Accesibilidad y carga cognitiva
+
+La accesibilidad ayuda a todas las personas, no solo a quienes tienen una discapacidad permanente. Una persona puede estar con baja visión, usando lector de pantalla, con una lesión temporal, con poca concentración, en una pantalla pequeña o bajo presión.
+
+Diseña la arquitectura de información considerando:
+
+- Orden de lectura lógico, de arriba hacia abajo y de lo general a lo específico.
+- Encabezados reales y jerárquicos, no texto grande usado como decoración.
+- Agrupación con `fieldset`/`legend` o secciones claras cuando los campos pertenecen a una misma decisión.
+- Acciones cercanas al contenido que afectan.
+- Ayuda contextual en el punto de necesidad.
+- Estados, errores y avisos expresados con texto además de color.
+- Progressive disclosure que reduzca carga cognitiva sin esconder información crítica.
+
+Honrar necesidades individuales significa permitir que la interfaz tolere distintas formas de uso: teclado, zoom, lectura pausada, revisión antes de enviar, cambios de preferencia y corrección sin perder trabajo.
+
+## Evita eyebrows
+
+Evita usar eyebrows como recurso por defecto. Un eyebrow es una etiqueta pequeña arriba del título, por ejemplo `PASO 1`, `NUEVA SOLICITUD`, `CLIENTE`, `LEGAL TECH`, `RESUMEN`.
+
+En Lexy suelen agregar ruido porque:
+
+- Repiten información que ya puede decir el título.
+- Hacen que la pantalla se sienta más marketera que útil.
+- Crean una capa visual extra antes del contenido real.
+- Empujan a usar jerarquía decorativa en vez de jerarquía funcional.
+
+### Qué usar en vez de eyebrows
+
+Prefiere:
+
+- Títulos informativos: `Completa tus datos para revisar tu caso`.
+- Subtítulos con próximo paso: `Usaremos esta información para preparar la primera revisión`.
+- Estados integrados al componente: badges, tags, status dots o texto de estado cerca del dato.
+- Breadcrumbs o tabs cuando la navegación lo requiere.
+- Stepper o progreso cuando el flujo realmente tiene pasos.
+
+### Cuándo sí puede existir una etiqueta superior
+
+Solo úsala si cumple una función real:
+
+- Estado operativo: `En revisión`, `Pendiente`, `Vence hoy`.
+- Ubicación en un flujo: `Paso 2 de 4`, si el paso ayuda a orientarse.
+- Tipo de caso o categoría que cambia decisiones: `Deuda`, `Despido`, `Salud`.
+
+Si la etiqueta no cambia comprensión, prioridad o acción, elimínala.
+
+## Progressive disclosure
+
+Progressive disclosure significa mostrar primero lo esencial y revelar detalles, excepciones o acciones secundarias cuando sean necesarias.
+
+Úsalo para manejar carga visual sin esconder información importante.
+
+### Orden recomendado
+
+1. Qué está pasando o qué debe hacer la persona.
+2. Por qué importa o qué pasará después.
+3. Acción principal.
+4. Campos o datos mínimos para avanzar.
+5. Información secundaria agrupada.
+6. Ayuda contextual, detalles legales, ejemplos o excepciones.
+
+### Patrones útiles
+
+- Pasos cortos para flujos largos.
+- Secciones colapsables para detalles no críticos.
+- Tabs cuando hay categorías pares que no se necesitan ver al mismo tiempo.
+- Dialog o sheet para acciones puntuales que no deben romper contexto.
+- Ayuda contextual cerca del campo, no en bloques largos al inicio.
+- Resúmenes progresivos: mostrar lo capturado y permitir editar por sección.
+
+### No ocultes
+
+No uses progressive disclosure para esconder:
+
+- Costos, consecuencias o riesgos.
+- Errores que bloquean el avance.
+- Datos necesarios para tomar una decisión.
+- Próximos pasos después de enviar información.
+- Plazos relevantes.
+
+## Referencias visuales
+
+Si el encargo incluye Figma, screenshot o un diseño anterior, primero extrae el patrón antes de proponer mejoras.
+
+Observa y conserva:
+
+- Tipo de pantalla: ficha, wizard, desk, tabla, formulario, carga de documentos, detalle.
+- Navegación: stepper, tabs, sidebar, header, footer o ninguna.
+- Densidad: compacta, media, espaciosa.
+- Contenedores: continuidad del formulario, cards, tabla, paneles, sheets.
+- Posición del CTA principal.
+- Ayuda: inline, tooltip, floating help, banner.
+- Ancho del contenido y alineación general.
+
+No cambies el tipo de pantalla por iniciativa propia. Si la referencia es una ficha web con stepper y una sola etapa visible, no la conviertas en una página con hero, sidebar, cards, resumen sticky o todas las etapas abiertas.
+
+## Patrón: ficha web cliente
+
+Usa este patrón para formularios de antecedentes, intake legal, fichas de litigios o cualquier flujo donde una persona debe entregar datos para revisión.
+
+Estructura recomendada:
+
+1. Stepper superior cuando hay varias etapas.
+2. Fondo calmo y continuo.
+3. Contenido principal en una columna de ancho controlado.
+4. Título de la etapa, no frase de marketing.
+5. Texto breve de contexto.
+6. Nota de obligatorios si aplica.
+7. Campos agrupados por relación natural.
+8. CTA principal al final del paso.
+9. Ayuda flotante o contextual si reduce ansiedad.
+
+Evita:
+
+- Hero.
+- Eyebrow.
+- Card lateral de próximos pasos.
+- Cards por cada sección del formulario.
+- Iconos de sección como decoración.
+- Mostrar deudas, bienes, sociedades y confirmación en la misma pantalla si el patrón tiene pasos.
+
+## Cliente vs CRM
+
+### Interfaces de cliente
+
+Prioriza calma y claridad:
+
+- Una idea principal por pantalla o sección.
+- Copy corto que explique el beneficio y el siguiente paso.
+- Menos campos visibles cuando el flujo pueda dividirse.
+- Ayuda contextual que reduzca ansiedad.
+- Confirmaciones claras después de enviar información.
+
+Evita dashboards densos, muchas tarjetas compitiendo y bloques largos de explicación antes de la acción.
+
+### Interfaces CRM o internas
+
+Prioriza tarea y escaneo:
+
+- La información que se consulta junta debe vivir junta.
+- Muestra más densidad solo si está jerarquizada.
+- Usa tablas, listas, filtros y estados visibles cuando aceleran el trabajo.
+- Lleva acciones frecuentes cerca del dato o fila correspondiente.
+- Oculta detalles secundarios, no acciones frecuentes.
+
+Evita esconder contexto operativo en modales innecesarios o colapsar información que el abogado necesita comparar.
+
+## Checklist UX antes de entregar
+
+1. ¿El título dice la tarea, estado o beneficio real sin necesitar un eyebrow?
+2. ¿La primera pantalla deja claro qué hacer y qué pasará después?
+3. ¿Cada sección agrupa información que se usa junta?
+4. ¿La información secundaria está disponible sin competir con lo principal?
+5. ¿Hay algún bloque, tarjeta o etiqueta que solo decora? Elimínalo.
+6. ¿Los campos aparecen en el orden en que la persona puede responderlos?
+7. ¿Los errores y estados aparecen cerca de donde se corrigen?
+8. ¿La acción principal es visible sin buscarla?
+9. ¿La pantalla se puede escanear en diagonal?
+10. ¿La composición reduce carga visual sin esconder consecuencias importantes?
+11. ¿El orden del HTML coincide con el orden visual y de lectura?
+12. ¿Hay landmarks y headings suficientes para navegar la página con lector de pantalla?