jovd83/prototype-sketching-skill

Habilidad de Boceto de Prototipos

Haz que una aplicación web funcional parezca dibujada a mano para que los clientes vean que es un prototipo, no un producto terminado. Esto es solo una capa de apariencia. Es puramente aditiva y totalmente reversible.

Barreras de alcance (lea primero, nunca las viole)

1. Solo toque puntos de entrada de estilos y index.html. Agregue una hoja de estilos, pegue un bloque SVG, establezca dos atributos. Nada más.
2. Nunca edite componentes, plantillas, lógica .ts/.tsx/.jsx/.vue, enrutamiento, estado, servicios o pruebas.
3. Nunca intercambie componentes por bibliotecas de componentes esbozados (p. ej., wired-elements) — eso reescribe el marcado. Prohibido.
4. Nunca recoloque ni distorsione logotipos, fotos, gráficos o iconos que deban permanecer nítidos — use la clase de exclusión.
5. La reversión debe ser trivial: eliminar los dos atributos de <html> desactiva toda la capa.

Cómo funciona (un modelo mental)

• Una hoja de estilos assets/sketch-skin.css define los 5 estilos + la rampa de esbozo.
• Un bloque SVG assets/sketch-filters.html define los filtros de bamboleo (#sketch-25 … #sketch-100).
• La activación consiste en dos atributos en <html>: data-sketch="<estilo>" y data-sketch-level="<0|25|50|75|100>".
• El aspecto proviene de: cambio de fuente manuscrita + cajas dibujadas a mano (bordes irregulares, rellenos planos) + un filtro SVG de desplazamiento cuya fuerza es el nivel de esbozo. La fuente lleva el texto; el filtro bambolea solo la decoración de las cajas (nunca desenfoca el texto).

Inicio rápido (haga esto en orden)

1. Confirme que la solicitud es solo de apariencia. Si el usuario desea cambios de comportamiento/diseño, deténgase — eso está fuera del alcance.
2. Detecte el framework y encuentre su hoja de estilos global + index.html (consulte la tabla de recetas a continuación).
3. Elija un estilo (tabla en "Estilos") y un nivel (0, 25, 50, 75 o 100).
4. Agregue el CSS de la capa a los estilos globales del proyecto:
   • Copie assets/sketch-skin.css en el proyecto (p. ej., src/styles.scss) o @import lo. La importación de la fuente ya está dentro de ese archivo (uso en línea).
5. Pegue los filtros SVG de assets/sketch-filters.html inmediatamente después de la etiqueta <body> de apertura en index.html. (Obligatorio — filter: url(#sketch-…) solo se resuelve si estas definiciones están en el DOM).
6. Active editando la etiqueta <html> en index.html:

   <html lang="es" data-sketch="balsamiq" data-sketch-level="50">
   

7. Verifique en el navegador. Para revertir, elimine los dos atributos data-sketch* (el CSS/SVG agregado puede permanecer inactivo — no hacen nada sin los atributos).

Estilos

data-sketch	Aspecto	Fuente	Uso
balsamiq	Wireframe limpio en escala de grises, cajas planas	Balsamiq Sans	El predeterminado "esto es un mockup"
sharpie	Marcador negro grueso, trazo pesado	Permanent Marker	Boceto de pizarra / taller
pencil	Grafito claro, trazos suaves	Gaegu	Borrador suave "lápiz sobre papel"
doodle	Juguetón, acentos de color claro	Short Stack	Conceptos informales y amigables
blueprint	Tinta blanca sobre papel azul	Patrick Hand	Sensación técnica de "tablero de dibujo"

Nivel de esbozo

data-sketch-level controla cuán temblorosas son las líneas. Selecciona un filtro de desplazamiento SVG diferente:

Nivel	Efecto
0	Cajas dibujadas a mano + fuente, pero líneas rectas y firmes (más limpio)
25	Bamboleo sutil
50	Claramente dibujado a mano (predeterminado recomendado)
75	Boceto suelto y enérgico
100	Muy tosco, "garabato" máximo

Si data-sketch está configurado pero data-sketch-level se omite, la capa usa por defecto el nivel 50.

Marca de agua diagonal (opcional)

Para estampar toda la pantalla como borrador, agregue un tercer atributo <html> con el texto a mostrar:

<html data-sketch="balsamiq" data-sketch-level="50" data-sketch-watermark="BORRADOR">

data-sketch-watermark pinta una palabra escrita a mano tenue en diagonal a través del viewport. Es una capa fija no interactiva (pointer-events: none), por lo que nunca bloquea clics, nunca cambia el diseño y permanece en su lugar a través de cambios de página y ruta. Cualquier texto funciona (BORRADOR, PROTOTIPO, CONFIDENCIAL, un nombre de cliente...). Elimine el atributo para desactivarlo. Con la superposición, un campo de texto Marca de agua lo activa en vivo.

Modales, ventanas emergentes y navegación SPA

Debido a que la capa se activa mediante atributos en <html> y se estiliza con selectores globales [data-sketch] …, todo lo que aparece después de la activación la hereda automáticamente — diálogos, ventanas emergentes, menús desplegables, información sobre herramientas y notificaciones (incluidas las montadas en portales), y cada pantalla a la que navegue en una aplicación de una sola página. No hay nada que cablear por componente o por ruta.

Dos cosas lo mantienen consistente:

• Las listas de selectores ya cubren dialog, [popover], [role="dialog"], [aria-modal="true"], .modal, .popover, menús, información sobre herramientas y notificaciones, además del ::backdrop nativo.
• El script de superposición observa <body> y vuelve a inyectar los filtros SVG si un framework reemplaza el cuerpo en un cambio de ruta, para que el bamboleo nunca se pierda en silencio. (Con el modelo de atributo estático, pegue sketch-filters.html una vez después de <body>; los frameworks SPA se montan en una raíz hija y lo dejan intacto).

Recetas de inyección por framework

La capa es independiente del framework. Estos son los objetivos exactos; detalles completos en references/implementation.md.

Stack	Agregar CSS a	Pegar SVG en	Establecer atributos en
Angular	src/styles.scss (o styles.css)	src/index.html después de <body>	<html> en src/index.html
React / Vite	src/index.css (importado en main.tsx)	index.html después de <body>	<html> en index.html
Vue	src/assets/main.css (importado en main.ts)	index.html después de <body>	<html> en index.html
HTML estático	enlazar sketch-skin.css en <head>	index.html después de <body>	<html> en index.html

Mantener activos específicos nítidos (exclusión)

La capa no editará el marcado, pero si el usuario solicita explícitamente proteger un elemento (logotipo, gráfico), el único cambio de marcado permitido es agregar el gancho de exclusión a ese único elemento:

<img src="logo.svg" class="no-sketch" alt="Logotipo">

.no-sketch (o data-no-sketch) elimina el filtro de bamboleo y las anulaciones de color de ese elemento. Úselo con moderación y solo cuando se le solicite.

Superposición de vista previa interactiva (opcional)

Cuando el usuario desee alternar estilos en vivo (por ejemplo, mostrarle a un cliente un interruptor), use la superposición en lugar de atributos estáticos:

1. Agregue assets/sketch-skin.css a los estilos globales (como en Inicio rápido).
2. Agregue una etiqueta de script antes de </body>:

   <script src="sketch-toggle.js" defer></script>
   

3. Hecho. El script renderiza un panel flotante con APAGADO + un radio por tema, un deslizador de esbozo 0–100% y un campo de texto de marca de agua, cambia los atributos <html> en vivo y recuerda la elección en localStorage. Inyecta automáticamente los filtros SVG (y los vuelve a inyectar si un SPA reemplaza el cuerpo), por lo que el paso 5 de Inicio rápido (pegar sketch-filters.html) no es necesario.

Esto sigue siendo solo apariencia y no destructivo — el script solo establece atributos. Elimine la etiqueta para desactivarlo. Elija este modelo cuando la solicitud sea "déjeme a mí/al cliente cambiar los estilos"; use atributos estáticos para una apariencia fija y estable para capturas de pantalla.

Galería de capturas de pantalla

README.md muestra cada estilo y la escalera 0→100% usando los PNG en demo/screenshots/. Esas imágenes están pre-renderizadas; la aplicación de demostración interactiva y el script de captura de Playwright que las generan viven en la fuente de desarrollo del proyecto y no se incluyen con la habilidad instalada. La habilidad en sí son solo assets/ + references/ — sin paso de compilación, sin dependencias.

Ejemplos

Ejemplo 1 — Demostración Angular en Balsamiq, boceto moderado

• Entrada: "Haz que esta aplicación Angular parezca un wireframe de Balsamiq para la demostración de mañana."
• Acciones: agregar sketch-skin.css a src/styles.scss; pegar filtros en src/index.html; establecer <html data-sketch="balsamiq" data-sketch-level="50">.
• Resultado: la aplicación se ejecuta de manera idéntica; se renderiza como un wireframe en escala de grises.

Ejemplo 2 — React, sharpie máximo

• Entrada: "Aplicación React, aspecto completo de marcador de pizarra, muy tosco."
• Acciones: importar sketch-skin.css en main.tsx; pegar filtros en index.html; establecer data-sketch="sharpie" data-sketch-level="100".

Ejemplo 3 — Desactivarlo

• Entrada: "Vuelve a la interfaz real."
• Acción: eliminar data-sketch y data-sketch-level de <html>. Hecho — no se necesita ningún otro cambio.

Solución de problemas

Síntoma	Causa	Solución
Las cajas se ven dibujadas a mano pero las líneas son perfectamente rectas	Los filtros SVG no están en el DOM, o nivel 0	Confirme que sketch-filters.html está pegado después de <body>; establezca nivel ≥ 25
No cambió nada en absoluto	Faltan atributos o el CSS no se cargó	Verifique que <html data-sketch="…"> esté presente y que sketch-skin.css esté en los estilos globales
El texto se ve borroso	Filtro aplicado al texto/todo <body>	No agregue filter: al body o al texto; la capa filtra solo la decoración de las cajas — vuelva a copiar sketch-skin.css sin modificaciones
Las fuentes no son manuscritas	Sin conexión / Google Fonts bloqueadas	Aloje las fuentes usted mismo — consulte assets/fonts/README.md
La página se siente lenta con tablas/cuadrículas enormes	Costo de feDisplacementMap en DOM grande	Reduzca el nivel, o limite la lista de selectores de bamboleo (consulte references/implementation.md)
Un logotipo se desaturó/se volvió tembloroso	Sin exclusión en ese activo	Agregue class="no-sketch" a ese único elemento
Las fuentes de iconos / iconos SVG desaparecieron	Aplanamiento agresivo	Agregue no-sketch al contenedor de iconos, o consulte la nota de iconos en references/implementation.md

Archivos de referencia (lea solo cuando sea necesario)

• references/styles.md — especificación exacta de fuente/paleta/trazo para cada uno de los 5 estilos, y cómo agregar un nuevo estilo.
• references/implementation.md — matemática de filtros SVG, paso a paso por framework, ajuste de selectores, fuentes sin conexión, rendimiento, detalles de reversión.