primer commit

2026-10-13 21:22:54 -06:00
commit b6b4bc3f01
13 changed files with 2428 additions and 0 deletions
@@ -0,0 +1,165 @@
+---
+name: manuales-factorpesca
+description: Genera manuales de usuario en PDF con un diseño visual estandarizado (paleta azul marino, tipografía Inter, página Letter) a partir de una aplicación web real. Combina la skill playwright-skill de lackeyjb para capturar pantallas con un generador HTML→PDF basado en Playwright. Aplica estructura editorial (portada, índice, requisitos previos, capítulos numerados, solución de problemas, glosario, aviso de propiedad) y un checklist de calidad antes de entregar. Use when the user asks to create, regenerate, or review a Spanish-language user manual PDF for a web application, or when they need the FactorPesca editorial design system applied to a technical document.
+license: UNLICENSED
+metadata:
+  author: factorpesca
+  version: "1.0.0"
+allowed-tools: Bash(node:*) Bash(npm:*) Read Write Edit Glob Grep
+---
+
+# manuales-factorpesca
+
+## Objetivo
+
+Crear manuales de usuario en PDF para aplicaciones web de FactorPesca,
+con un diseño visual consistente (paleta azul marino, Inter, página Letter)
+y contenido verificado a partir de la aplicación real.
+
+## Cuándo usar esta skill
+
+- El usuario pide "manual de usuario", "manual PDF", "documentación para usuarios".
+- El usuario pide regenerar, actualizar o revisar un manual existente.
+- Se necesita aplicar el sistema de diseño FactorPesca a un manual nuevo o existente.
+
+## Herramientas
+
+- **Captura y navegación**: usa la skill `playwright-skill` de lackeyjb para
+  recorrer la aplicación y obtener las capturas de pantalla. Es la fuente
+  oficial de los artefactos visuales.
+- **Generación de PDF**: usa el script `scripts/build-manual.js`, que importa
+  Playwright directamente. No es estrictamente necesario instalar Chromium
+  dos veces: la skill de lackeyjb ya lo trae.
+- **No inventes pantallas**: cada captura debe corresponder a un estado real
+  de la aplicación, capturado con Playwright.
+
+Instalación de la skill auxiliar (ejecutar una sola vez por entorno):
+
+```bash
+# Global
+npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes
+
+# Local al proyecto
+npx skills add lackeyjb/playwright-skill --skill playwright-skill --yes
+```
+
+## Estructura de la skill
+
+```
+manuales-factorpesca/
+├── SKILL.md                        # este archivo
+├── references/
+│   ├── estilo.md                   # paleta, tipografía, componentes, tono
+│   ├── capturas.md                 # cómo capturar con playwright-skill
+│   ├── estructura.md               # anatomía obligatoria del documento
+│   └── calidad.md                  # checklist pre-entrega
+├── templates/
+│   ├── manual.html                 # plantilla semántica
+│   ├── manual.css                  # estilos pantalla + @page Letter
+│   └── manual.js                   # auto-TOC, anotaciones, numeración
+└── scripts/
+    ├── build-manual.js             # Playwright: HTML → PDF
+    ├── package.json
+    └── README.md
+```
+
+Carga `references/estilo.md` antes de empezar para conocer la paleta y los
+componentes disponibles. Carga `references/estructura.md` para conocer la
+anatomía obligatoria del documento.
+
+## Flujo de trabajo
+
+1. **Identificar** la aplicación, la audiencia y el objetivo del manual.
+2. **Definir** los procesos que se documentarán. Confirmar con el usuario el
+   alcance antes de empezar.
+3. **Preparar el entorno**: instalar dependencias de la skill
+   `playwright-skill` y de `scripts/` (`npm install`).
+4. **Capturar** las pantallas siguiendo `references/capturas.md`. Guardar
+   en `artifacts/` con el patrón `NN-slug.png`.
+5. **Redactar** el contenido en español claro, una acción principal por paso.
+6. **Rellenar** `templates/manual.html`: portada, índice, resumen,
+   requisitos, capítulos, troubleshooting, glosario, aviso de propiedad.
+7. **Construir** el PDF con `node scripts/build-manual.js`.
+8. **Verificar** el PDF aplicando `references/calidad.md`.
+9. **Entregar** el archivo final desde `dist/`.
+
+## Reglas editoriales
+
+- Títulos descriptivos y pasos numerados. Una acción principal por paso.
+- Indicar el resultado esperado después de acciones importantes.
+- Añadir callouts de advertencia antes de operaciones irreversibles.
+- Evitar párrafos largos. Dividir en pasos o listas.
+- Mantener consistencia con los nombres de botones y campos de la UI.
+- Tono: segunda persona, presente indicativo para acciones, futuro para
+  consecuencias. Sin "simplemente", "fácilmente", "obviamente".
+- No incluir contraseñas, tokens, datos personales reales ni identificadores
+  confidenciales en capturas ni en el texto.
+
+## Capturas de pantalla
+
+- Capturar después de que la UI termine de actualizarse
+  (`await page.getByRole(...).waitFor()`).
+- Usar viewport 1440×900 a 2x de DPI para nitidez en impresión.
+- Anotar las capturas con círculos numerados
+  (`<ol class="annotations" data-annotations='[{"x":50,"y":30,"n":1}]'>`).
+- Cerrar banners de cookies, tooltips de onboarding y notificaciones.
+- Nombres `NN-slug.png` dentro de `artifacts/`.
+
+Detalles completos en `references/capturas.md`.
+
+## Estilo visual obligatorio
+
+- Paleta: azul marino FactorPesca (`#0B2545` primary, `#F4A300` accent).
+- Tipografía: Inter (cuerpo) y JetBrains Mono (código).
+- Página Letter 8.5×11", márgenes 22mm.
+- Cabecera con nombre del capítulo (eyebrow small caps).
+- Pie con "FactorPesca · Manual de usuario" y "Página X de Y".
+- Portada a sangre (full bleed navy).
+
+Detalles y excepciones en `references/estilo.md`.
+
+## Estructura obligatoria del documento
+
+1. Portada
+2. Índice (auto-generado)
+3. Resumen ejecutivo
+4. Requisitos previos
+5. Capítulos (uno por proceso)
+6. Solución de problemas
+7. Glosario (opcional)
+8. Aviso de propiedad y confidencialidad (obligatoria)
+
+Detalles y reglas de salto de página en `references/estructura.md`.
+
+## Generación del PDF
+
+Tras editar `templates/manual.html`:
+
+```bash
+cd manuales-factorpesca
+node scripts/build-manual.js
+```
+
+Por defecto produce `dist/manual-{aplicacion}-v{version}.pdf`. Más opciones en
+`scripts/README.md`.
+
+## Entrega y calidad
+
+Antes de declarar el manual como terminado:
+
+- Recorrer el manual página a página, marcando cualquier desviación.
+- Aplicar el checklist completo de `references/calidad.md`.
+- Corregir en el HTML fuente, no en el PDF.
+- Volver a generar hasta que el checklist esté limpio.
+- Marcar la versión como `released` y entregar el archivo desde `dist/`.
+
+## Anti-patrones
+
+- Capturar pantallas con datos personales reales o placeholders que parezcan reales.
+- Inventar mensajes, botones, opciones o pantallas que no existen en la app.
+- Pegar imágenes sin alinearlas con la posición real del elemento.
+- Usar un color fuera de la paleta autorizada.
+- Cambiar la tipografía del manual a otra familia que no sea Inter o JetBrains Mono.
+- Dejar capturas de pantalla con banners de cookies, tooltips o estados de carga.
+- Declarar terminado un manual con pasos sin captura o capturas sin paso.
+- Generar el PDF sin `-webkit-print-color-adjust: exact` (los callouts salen en blanco).