# Andamiaje de prototipo trazable

Maquinaria reutilizable de la **fase 3** de Argui (ver
[methodology/prototype.md](../../methodology/prototype.md)). Convierte un archivo HTML estático en un
prototipo navegable, trazable al PRD (Product Requirements Document) y comentable por los stakeholders — sin backend.

Es **mecanismo, no agente**: idéntico entre proyectos, por eso se distribuye. HTML/CSS/JS vanilla,
sin framework ni build. Portable a cualquier prototipo estático.

## El prototipo es un solo archivo

Un prototipo, un archivo `.html` con todo adentro: las pantallas, el CSS del producto, y el CSS y
el JS de este andamiaje pegados inline. Se abre con doble clic desde el disco, se manda por
correo, no tiene rutas relativas que romper y el feedback de todas las pantallas queda en un
solo lugar. La navegación entre pantallas es cliente (mostrar/ocultar secciones), no enlaces a
otros archivos.

Si el prototipo crece hasta volverse difícil de editar (referencia: más de ~15 pantallas), se
parte por área funcional en varios archivos autónomos. Es la excepción, no el punto de partida —
y cada archivo debe declarar el mismo `data-proyecto` para que el feedback no se fragmente.

El archivo lleva adentro el producto del cliente antes de existir: es confidencial. No va a un
repositorio público; si se publica para que un stakeholder lo abra, va en una URL no adivinable,
con `<meta name="robots" content="noindex, nofollow">`, y se apaga al cerrar la fase. Los datos
de ejemplo son inventados. Ver [methodology/prototype.md](../../methodology/prototype.md) →
*Dónde vive el prototipo*.

## Archivos

| Archivo | Qué es |
|---|---|
| `argui-prototipo.css` | Estilos del marco y del modo prototipo: barra, insignias, notas, panel de feedback. |
| `argui-prototipo.js` | Runtime: switch de modo, trazabilidad, comentarios, export, envío por correo. |
| `check-consistency.mjs` | Valida que cada ID referido en el prototipo esté definido en el PRD (Node 18+). |
| `SKILL.md` | Envoltorio de skill para Claude Code (opcional; el mecanismo no la requiere). |

## Cómo se cablea

1. Pega el contenido de `argui-prototipo.css` en un `<style>` y el de `argui-prototipo.js` en un
   `<script>`, dentro del archivo del prototipo:

   ```html
   <style>/* …contenido de argui-prototipo.css… */</style>
   ...
   <script data-proyecto="acme"
           data-prd-base="prd.html"
           data-formspree="https://formspree.io/f/xxxxxxx">
     /* …contenido de argui-prototipo.js… */
   </script>
   ```

   - `data-proyecto` (recomendado): identifica el prototipo para guardar el feedback. Si se
     omite se usa la ruta del archivo — y el feedback se pierde al renombrarlo o moverlo.
   - `data-prd-base` (opcional): documento PRD al que apuntan las insignias por defecto.
   - `data-formspree` (opcional): endpoint de [Formspree](https://formspree.io/) para recibir
     el feedback por correo. Si se omite, el botón "Enviar por correo" no aparece. Es lo único
     del andamiaje que sale a un tercero —y lo que le manda son comentarios sobre el producto
     del cliente—, así que se cablea solo con su aprobación; sin él, el canal es el export.

   Durante el desarrollo puedes mantenerlos como archivos externos (`<link>` + `<script src>`)
   y pegarlos inline al entregar; el runtime funciona igual en ambos casos.

2. Marca cada bloque de UI (interfaz de usuario) con el **ID estable** del requisito que lo define:

   ```html
   <section data-prd="RF-12 · RDA automática">
     …contenido del bloque…
   </section>
   ```

   - `data-prd`: la referencia visible en la insignia. **Empieza por el ID** (`RF-12`, `MET-3`).
     Se traza por ID y no por número de sección porque el ID sobrevive a la partición del PRD
     en F3.4.
   - `data-prd-href` (opcional): enlace explícito. Si se omite, se construye desde
     `data-prd-base` con la convención `RF-12` → `#rf-12`.

3. Anota dudas para el cliente donde correspondan (visibles solo con el modo encendido):

   ```html
   <p data-prd-note="¿El cliente confirma que el tope es de 30 días?">…</p>
   ```

## Modo prototipo

El prototipo tiene un **marco** —una barra fija arriba— que nunca se confunde con el producto.
Ahí viven el switch de modo, el contador de comentarios y los botones de feedback.

- **Encendido** (por defecto en la primera visita): aparecen las insignias de trazabilidad, las
  notas de aclaración y el comentario por bloque.
- **Apagado**: el lienzo se ve como producción; solo queda el marco.
- El estado se recuerda por visitante (`localStorage`) y se puede forzar con `?prototipo=1` o
  `?prototipo=0` en la URL.
- **Vista limpia** — `?limpio` en la URL: sin marco y sin anotaciones. Para demo de venta,
  capturas de pantalla o mostrarle el producto a un usuario final.

Los comentarios se guardan en `localStorage` y se exportan a **Markdown / JSON** — ese export es
el input para iterar el PRD. Con Formspree configurado, también se envían por correo. Si el
navegador no permite guardar (algunos bloquean `localStorage` en `file://`), el marco lo avisa y
el feedback dura solo la sesión: hay que exportar antes de cerrar.

## Controles del prototipo: Rol · Fase · Escenario

Tres dimensiones declarativas que el marco pinta como selectores. Son el mecanismo del
**refinamiento** (F3.5): sin poder cambiar de escenario no se pueden acordar los estados de
vacío, carga, error y permiso denegado. Funcionan con el modo encendido **y** apagado: pertenecen
al marco, no a la anotación.

1. Declara los valores en el script (cada dimensión es opcional; la que no se declara no aparece):

   ```html
   <script data-proyecto="acme"
           data-roles="Admin,Operario"
           data-fases="Solicitud,Aprobación,Cierre"
           data-escenarios="Normal,Vacío,Carga,Error,Sin permiso">
   ```

2. El estado seleccionado se refleja en la raíz del documento, con el valor en minúsculas y sin
   acentos (`Sin permiso` → `sin-permiso`):

   ```html
   <html data-rol="admin" data-fase="solicitud" data-escenario="normal">
   ```

3. Los bloques se muestran u ocultan solos con `data-cuando-rol`, `data-cuando-fase` y
   `data-cuando-escenario` (varios valores separados por coma o espacio). Sin el atributo, un
   bloque siempre se ve:

   ```html
   <div data-cuando-escenario="normal">Lista con datos</div>
   <div data-cuando-escenario="vacio">Aún no hay solicitudes</div>
   <div data-cuando-escenario="error, sin-permiso">No pudimos cargar esto</div>
   <button data-cuando-rol="admin">Eliminar</button>
   ```

   Para lo que no es mostrar/ocultar —un texto o un estilo que cambia según el rol— usa
   selectores de atributo en tu CSS: `[data-rol="operario"] .barra-acciones { … }`.

4. Se puede compartir un estado concreto por URL: `?rol=admin&escenario=error`. Combinado con
   `?limpio`, sirve para mandar una captura o una demo de un estado puntual.

### API del runtime

`window.ArguiPrototipo`:

| Miembro | Qué hace |
|---|---|
| `refrescar()` | Reaplica visibilidad y anotación tras cambiar de pantalla (también hay un observador automático). |
| `dimension(clave, valor)` | Cambia `rol`, `fase` o `escenario` por código. |
| `modo(bool)` | Enciende o apaga el modo prototipo por código. |
| `controles` | El elemento de la barra donde viven los selectores, por si necesitas agregar uno propio. |

## Validar consistencia

```bash
node check-consistency.mjs --proto prototipo.html --prd prd.md
```

Reporta IDs referidos en el prototipo que no están definidos en ningún PRD (error, sale con
código 1) y requisitos del PRD sin ancla en el prototipo (aviso). Cuenta como definición un ID en
fila de tabla, encabezado o ítem en negrita — no una mención en prosa, para que un ID mal escrito
salga como roto. Útil en un hook de pre-commit o en CI.

## Definition of Done (recordatorio)

Ningún cambio al prototipo está terminado si no actualiza las superficies que toca: el HTML, la
prosa del PRD, la referencia de trazabilidad (`data-prd`), los specs y —cuando el ajuste toca
apariencia— el design system. Ver [methodology/prototype.md](../../methodology/prototype.md).