166 lines
6.9 KiB
Markdown
166 lines
6.9 KiB
Markdown
---
|
||
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).
|