Captura de referencia de UI
El código proporciona estructura, estilos, cadenas e iconos. No proporciona lo que sucede en tiempo de ejecución (qué responde un backend, en qué orden aparecen las cosas, cuánto espera la aplicación real), y no dice nada sobre la UI de otra compañía. Este skill llena esos vacíos con referencias, en un orden fijo de preferencia, y nunca improvisa en el navegador personal de alguien.
Esa última regla tiene una historia. En la producción de la que provienen estos skills, se permitió que un agente entrara al navegador con sesión iniciada del revisor para capturar una aplicación en vivo. Los flujos en vivo se colgaron, el agente siguió haciendo pasos de "limpieza" después de que el revisor dijera que parara, dejó elementos sueltos en un espacio de trabajo de prueba, y la sesión terminó mal después de unos 68 minutos sin construir nada utilizable. Las mismas capturas se recuperaron después de la transcripción de la sesión en minutos. Primero referencias offline; un navegador solo cuando el usuario lo solicite, aislado, y detenido en el momento en que diga que pare.
Dónde van las cosas
- Entradas (grabaciones, exportaciones, capturas de pantalla que el usuario entrega): cópialas en
products/<slug>/references/<name>/tan pronto como lleguen. Las carpetas de Descargas y las carpetas temporales de captura del SO se limpian, y una grabación en la producción fuente vivía en una carpeta que el sistema habría eliminado. Los nombres de grabaciones de macOS contienen un espacio estrecho sin separación (U+202F) antes de AM/PM: búscalos con un glob, no escribiendo el nombre. - Material de trabajo (miles de fotogramas, capturas recuperadas, OCR sin procesar): una carpeta temporal
fuera de cada repositorio, por ejemplo
$TMPDIR/pvs-<slug>-<name>/. - Resultados que vale la pena conservar (la línea de tiempo del OCR, fotogramas clave con datos reales
recortados, el análisis):
references/<name>/, citados desde SOURCES.md.
Las grabaciones y capturas de un espacio de trabajo real contienen nombres reales de clientes, correos electrónicos, números de teléfono, identificadores internos y conversaciones de otras personas. Nunca van al repositorio del workbench, y el video nunca los muestra: la sección 1 paso 6 enumera lo que debe cambiar.
Elegir la técnica
| Tienes | Técnica | Leer |
|---|---|---|
| Una grabación de pantalla del producto | 1. Analizar la grabación | references/recording-analysis.md |
| Sesiones pasadas que vieron la aplicación | 2. Recuperar capturas de transcripciones | este archivo, sección 2 |
| Una aplicación que se pueda ejecutar localmente | 3. Instancia local compilada como producción | references/local-instance.md |
| El producto de otra compañía | 4. Investigación web, solo fuentes públicas | references/third-party-ui-prompt.md |
| Nada (una llamada telefónica, una tarjeta final, texto generado) | Diseñarlo desde el kit y marcarlo | product-truth (mock) |
Inténtalos en ese orden. Antes de pedirle a alguien que grabe, revisa la sección 2: las capturas pueden ya existir. Si ninguno de los cuatro funciona, dilo; no recurras al navegador del revisor.
1. Analizar una grabación de pantalla
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/ui-reference-capture/scripts"
W="$TMPDIR/pvs-acme-board" # temporal, fuera del repositorio
bash "$S/frames.sh" references/board/rec.mov "$W" --fps 10 --logical-width 1440
bash "$S/ocr.sh" "$W/logical" "$W/ocr.jsonl" # solo macOS
"$PVS_HOME/bin/pvs-py" "$S/ocr_events.py" "$W/ocr.jsonl" references/board/ocr-timeline.txt --fps 10 \
--region "panel=0.6,0,1,[email protected]"
"$PVS_HOME/bin/pvs-py" "$S/grid.py" sheet "$W/overview.png" "$W/logical" --every 20 --cols 4
frames.shescribe miniaturas pequeñas (detección de cambios) y fotogramas al ancho lógico de la aplicación (una grabación retina es 2x: el ancho lógico es la mitad del ancho en píxeles), así que un píxel de fotograma es un píxel CSS de la aplicación reconstruida.ocr.shcompilaocr.swift(Apple Vision) una vez en una carpeta de caché y escribe una línea JSON por fotograma. En Linux sale con "unsupported": lee las contact sheets en su lugar.ocr_events.pyconvierte el OCR por fotograma en intervalos estables,inicio-fin [región] texto. Esa línea de tiempo da las cadenas exactas que muestra la aplicación real y cuándo, lo cual supera a adivinar a ojo desde un video.grid.py sheetcrea contact sheets: una vista general cada 2 s, luego contact sheets densas a 10 fps por fase.grid.py overlaydibuja una cuadrícula en píxeles lógicos sobre un fotograma para medir.- Guarda los fotogramas clave como
references/<name>/frames/<t>-<state>.jpg(recortados de datos reales). - Escribe
references/<name>/analysis.mdcon la estructura enreferences/recording-analysis.md: la línea de tiempo real con cadenas exactas, movimiento medido (cuánto tarda un panel en abrirse, cuánto reposa el cursor), una tabla "debe cambiar para el video" (nombres reales, correos, teléfonos, espacios de trabajo, identificadores internos, esperas largas, elementos del SO como el Dock), y brechas del producto que plantear antes de que nadie construya sobre ellas (un paso que la historia necesita pero que la grabación muestra fallando).
Las grabaciones ocultan brechas cuando las esperas se comprimen; anota cada espera que acortes.
2. Recuperar capturas de sesiones pasadas
Cada imagen que devolvió una herramienta en una sesión de Claude Code (capturas de pantalla del navegador, capturas de ventana, imágenes leídas) y cada imagen pegada en el chat se almacena en el JSONL de esa sesión.
"$PVS_HOME/bin/pvs-py" "$S/recover_transcript_images.py" ~/.claude/projects/<project>/<session>.jsonl \
[--from-line N] [--tool screenshot]
Sin carpeta de salida, escribe en una carpeta temporal nueva y rechaza cualquier carpeta dentro de un
árbol de trabajo de git, porque estas capturas muestran cuentas reales. Escribe index.tsv (archivo,
hora, herramienta, entrada) para que puedas encontrar las pantallas que necesitas. Revísalas en
contact sheets (grid.py sheet <out> <dir> --labels name), luego copia solo las limpiadas, con
datos reales recortados, en references/<name>/. En la producción fuente se construyó un video
completo a partir de 117 imágenes recuperadas más el código.
3. Una instancia local compilada como producción
La referencia más fiel cuando la aplicación se puede ejecutar en la máquina del usuario: compílala
desde el commit de producción con los argumentos de compilación de producción, siémbrala con datos
ficticios, aíslala de todo sistema compartido, y captúrala con un navegador sin interfaz gráfica.
Lee references/local-instance.md antes de empezar; el usuario debe aceptar ejecutar su aplicación,
y nunca usa sus cuentas o bases de datos compartidas.
4. UI de terceros
Para pantallas de otra compañía, lanza un subagente de investigación con
references/third-party-ui-prompt.md: solo fuentes públicas (documentación oficial, centros de
ayuda, kits de prensa, capturas de pantalla de marketing, demos públicas incrustadas propiedad del
vendedor), nunca un inicio de sesión, nunca un envío o una reserva, unos 30 minutos. Cada valor
vuelve marcado como verificado, medido o inferido. Prefiere el componente propio del producto
cuando lo tenga (un producto que renderiza una vista previa de una aplicación de chat tiene un
componente de vista previa; úsalo en lugar de reconstruir la aplicación de chat). Muestra una
pantalla completa de terceros solo cuando pruebe una integración real; en otros casos usa logotipos
e insignias dentro del producto.
Paridad: demostrar que la reconstrucción coincide
"$PVS_HOME/bin/pvs-py" "$S/pair.py" snapshots/nocam-12.4s.png references/board/frames/12.4-board.png \
640 40 1100 300 "$W/pair-board-header.png" --ref-scale 2 --logical-width 1440 --render-width 1920
Toma nuestra instantánea con la cámara a escala 1 (una copia de la composición con
#camera{transform:none!important}), recorta el mismo cuadro lógico de ambas, y apílalas. El
script imprime la diferencia absoluta media por canal; itera hasta que deje de bajar y la imagen
apilada no muestre desplazamiento. Mide en píxeles de aplicación y convierte explícitamente:
confundir las escalas fue una fuente recurrente de coordenadas incorrectas.
Reglas y por qué
- Nunca el navegador o perfil personal del revisor, y nada tomado de él (fuentes, iconos, almacenamiento). Cuando alguien diga que pare, detén cada acción del navegador de inmediato, incluida la limpieza.
- Nunca iniciar sesión, nunca leer tokens o almacenamiento del navegador. Si una captura necesita un inicio de sesión, la persona escribe su propia contraseña en su propia sesión, o la captura no se realiza.
- El material recuperado y grabado se mantiene privado. Carpeta temporal primero, solo copias recortadas.
- Marca cada valor inferido. Una referencia que está medio adivinada debe decir qué mitad.