marker-sketch

¿Qué hace marker-sketch?

Transformar una idea en un boceto a rotulador: trazo negro grueso ligeramente tembloroso, relleno gris desplazado con estrías de rotulador, sombra arrojada gris, texto manuscrito corto, papel punteado. El resultado es siempre el mismo porque el estilo vive en un núcleo fijo (assets/template.svg, assets/glyphes.svg) y la reflexión sigue siempre el mismo protocolo. Nada se redibuja de memoria: se ensambla.

Rutas y dependencias

En los comandos, ${CLAUDE_SKILL_DIR} es la carpeta de esta skill (Claude Code lo reemplaza automáticamente). En claude.ai, si la variable aparece tal cual, usar la ruta relativa desde la carpeta de la skill copiada en el entorno de ejecución (scripts/compose.py). Los archivos de trabajo (draft.svg, croquis.svg) se escriben en el directorio de trabajo, nunca en la skill.

Dependencias: Python 3 es suficiente para compose.py (el texto permanece en <text> con la fuente incrustada). fonttools convierte el texto en trazados (--outline, renderizado idéntico en todas partes), playwright con Chromium produce los PNG de control (render.py). Instalación: pip install fonttools playwright && playwright install chromium. Si falta una dependencia y no se instala, entregar el SVG y decir que no se ha realizado el control visual.

1. Elegir el modo en diez segundos

Situación	Modo	Salida	Tiempo estimado
Pregunta o solicitud de esquema, respuesta ilustrada	Croquis (por defecto)	un SVG	una sola generación
Reunión, taller, intercambio oral, "muestra lo que acabamos de decir"	Live	un SVG 16:9 muy legible, retocado en cada intercambio	unos segundos por retoque
Esquema denso (más de 10 objetos), enlaces numerosos, renderizado controlado	Taller	SVG construido por script, PNG de control	un minuto
"Ahora, después, más tarde", "actualmente, mañana", evolución, tendencia, elementos para mover	Interactivo	una página HTML autónoma	una configuración JSON

En caso de duda, empezar con Croquis. No usar nunca three.js por defecto: solo se usa en Taller, para fabricar un símbolo en perspectiva que falte (ver references/glyphes.md, sección 3D).

2. Protocolo mental, siempre el mismo (antes de trazar)

Responder mentalmente a estas seis preguntas, en orden. Esto es lo que garantiza la coherencia, no el talento.

1. Mensaje en una frase. ¿Qué debe entender el lector en tres segundos? Esta frase se convierte en el título, o en la anotación azul.
2. Familia de diagrama. Elegir en references/familias-diagramas.md (quince familias: flujo, bucle, árbol, conjuntos, capas, hub, rueda, curva, matriz, red, escena, maqueta, antes/después, friso, embudo).
3. Metáfora opcional. Si la idea es abstracta (tensión, crecimiento, deuda, fricción), buscar un objeto físico que transmita la tensión y que se dibuje en una decena de trazos (references/metaforas.md). Si no, quedarse con la familia.
4. Presupuesto. 5 a 9 objetos, 40 % de blanco, textos de una a tres palabras (un pie de foto de una frase como máximo). En Live: 7 objetos como máximo.
5. Jerarquía de tinta. Negro = el corazón del mensaje (como máximo un objeto completamente negro). Gris = el contexto. Azul bolígrafo = anotaciones, flechas de comentario, números. Un solo acento de relleno por dibujo (amarillo resaltador, naranja, rojo, azul cielo o arena), menos del 10 % de la superficie, nunca para decorar.
6. Composición. Lectura de izquierda a derecha y de arriba abajo, un punto focal, alineaciones sobre una cuadrícula suelta, espacio reservado para las anotaciones.

Luego escribir. Luego controlar (sección 8).

3. Reglas de estilo no negociables

• Nunca degradado, nunca contorno fino y regular, nunca sombra difusa. Sombra = copia gris desplazada (-7, 10).
• Tres grises + negro + papel: f1 claro, f2 medio, f3 oscuro, f4 negro sólido.
• Flechas abiertas en V (clases arr, arrb, arrg), curvas en S en lugar de codos en ángulo recto.
• Flujo gris punteado ancho (flow), perímetros negros en puntos pequeños (dotk), guiones (dash).
• Texto: fuente Patrick Hand, clases t (36), tl (52, títulos), ts (27, mini), tb (azul), tg (gris), tw (blanco sobre negro). Español cuidado: acentos en mayúsculas, ñ, ¿? y ¡! correctos, comillas «», sin guión largo, apóstrofo curvo ’.
• Las palabras son las del lector. Sin jerga inventada, sin frases.
• Sin emoji, sin logotipo de marca, sin personaje protegido.

Valores numéricos exactos, colores y casos particulares: references/gramatica-visual.md.

4. Modo Croquis: escribir directamente

El dibujo bruto solo contiene el contenido. El núcleo de estilo lo añade compose.py.

Patrón de un objeto (cuatro capas, mismo id compartido):

<use href="#a1" x="-7" y="10" class="sh"/>        <!-- sombra -->
<use href="#a1" class="pp"/>                       <!-- papel opaco -->
<use href="#a1" x="-2.5" y="2.5" class="f1"/>     <!-- relleno desplazado -->
<g class="ink"><path id="a1" d="M300 300 L560 296 L556 420 L296 424 L302 296"/></g>
<text class="t" x="430" y="372">Idea</text>

Los ángulos sobresalen ligeramente (el trazado no se cierra exactamente), los lados nunca son paralelos al píxel. Para los símbolos (persona, ventana, base de datos, nube, lupa...), usar la biblioteca:

<use href="#g-person" x="540" y="260" class="cb"/>   <!-- clases de tono: cb co cr cs ch c1 c3 c4 -->

Catálogo: python3 ${CLAUDE_SKILL_DIR}/scripts/compose.py --catalog o references/glyphes.md. Lámina visual: references/lamina-simbolos.png.

Montaje y control:

python3 ${CLAUDE_SKILL_DIR}/scripts/compose.py draft.svg -o croquis.svg --outline      # papel, puntos, filtros, texto en trazados
python3 ${CLAUDE_SKILL_DIR}/scripts/check.py draft.svg                                  # presupuesto, acentos, símbolos, acentos de color
python3 ${CLAUDE_SKILL_DIR}/scripts/render.py croquis.svg                               # PNG de control (Chromium)

Opciones de compose.py: --paper cream|white|kraft|yellow|blue, --no-dots, --transparent (para insertar en una diapositiva), --size 1200x1200, --embed-font (mantiene el texto editable), --title.

Sin ejecución de código (conversación simple en claude.ai): copiar el bloque <defs> de assets/template.svg tal cual, pegar allí solo los símbolos utilizados desde assets/glyphes.svg, luego el contenido dentro de <g id="drawing" filter="url(#wob)">. Decir explícitamente que no se ha podido realizar el control visual.

5. Modo Live: reunión, taller, oral

Leer references/modo-live.md antes del primer retoque. Lo esencial:

• Escuchar, no redactar. Extraer del intercambio 3 a 7 elementos: los nombres se convierten en objetos, los verbos en flechas, "pero" y "si no" en ramas, "antes/después" en dos columnas, "primero, luego" en un flujo.
• Formato 16:9, texto mínimo 36 px (t), títulos 52 px (tl), nunca ts. Legible a cuatro metros.
• Posiciones estables. En cada retoque, mover solo lo que cambia. Reutilizar los mismos identificadores y coordenadas. El equipo no debe perder sus referencias.
• Retoques orales: "añade", "conecta", "tacha", "destaca" (negro sólido o resaltador), "versión limpia" (realinear, una sola vez al final).
• Proyección: python3 ${CLAUDE_SKILL_DIR}/scripts/live.py draft.svg abre una página que se actualiza automáticamente al reescribir el archivo (pantalla completa con la tecla f). En claude.ai: volver a publicar el mismo artifact o renderizar el SVG a PNG en cada retoque.
• Maquetas y flujos en directo: recetas en references/wireframes-flujos.md.

6. Modo Taller: esquemas densos construidos por script

Para más de diez objetos o muchos enlaces, escribir unas líneas con scripts/sketch.py: los enlaces se calculan en los bordes de los objetos, curvas en S y flechas abiertas incluidas.

import sys; sys.path.insert(0, "${CLAUDE_SKILL_DIR}/scripts")
from sketch import Sketch
s = Sketch()
s.box("a", 260, 420, "Explorar", fill="f1")        # (id, centro x, centro y, texto)
s.box("b", 800, 420, "Definir", fill="fh")
s.glyph("c", "g-flag", 1340, 400, "Entregar")
s.link("a", "b"); s.link("b", "c", label="validar")
s.perimeter(["a", "b"], "Discovery")
s.note(1330, 640, "se mide aquí", target="c")
s.save("draft.svg")

Objetos: box (formas box, pill, oval, opción solid=False para conjuntos que se solapan), glyph, text, label, wf (elementos de maqueta), badge (número azul). Enlaces: link(kind="ink|gray|flow|dash|blue|line"), arrow, perimeter, note, highlight, raw (SVG libre). Ejemplos completos en examples/build_examples.py.

Para un diseño automático de un grafo grande, calcular las posiciones con ELK o dagre (npm), luego pasar las coordenadas a sketch.py.

7. Modo Interactivo: evolución en el tiempo

Cuando la solicitud habla de evolución, estados sucesivos, "ahora, después, más tarde", un cambio de tendencia, una organización que se transforma, piezas que mover: producir una página HTML autónoma. Leer references/interactivo.md (seis patrones, esquema de la configuración, trampas).

Principio: un dibujo bruto (los elementos tienen un id) + una configuración JSON (estados, imágenes clave por elemento: x y s r o d draw txt, capas, notas):

python3 ${CLAUDE_SKILL_DIR}/scripts/compose.py draft.svg --interactive scenes.json -o page.html
python3 ${CLAUDE_SKILL_DIR}/scripts/render.py page.html --state 1        # controlar cada estado

La página ofrece: botones de estados, control deslizante de tiempo, reproducción, capas para mostrar u ocultar, arrastrar y soltar elementos marcados como drag, doble clic para renombrar un texto, enlaces que siguen a los elementos, exportación del estado a SVG, copia de la disposición (JSON), teclado (flechas, espacio, f). Sin dependencias, funciona offline. Ejemplos: examples/migracion-organizacion.html, examples/tendencia-adopcion.html.

8. Control antes de responder

1. check.py sin error (símbolos conocidos, guiones largos ausentes, un solo acento de color).
2. Renderizado PNG revisado: texto legible, nada se solapa, sombras visibles, punto focal evidente, blanco suficiente.
3. El mensaje se entiende en una frase mirando el dibujo sin leer el texto.
4. Si un control visual es imposible, decirlo.

9. Entregar según el entorno

• Claude Code: escribir croquis.svg (y el PNG) en el directorio de trabajo, dar la ruta. En Live, lanzar live.py.
• claude.ai con ejecución de código: generar, controlar, enviar el SVG y el PNG. Para una página interactiva o un dibujo para conservar y compartir, publicar como artifact (cargar primero la skill artifact-design, título de dos a cuatro palabras); el HTML producido por compose.py --interactive ya es autónomo.
• Sin ejecución: SVG completo escrito a mano según la sección 4, anunciado como no controlado.

Respuestas en español: aplicar espanol-perfecto a las etiquetas del dibujo como al texto circundante.

10. Índice de referencias

Archivo	Cuándo leerlo
references/gramatica-visual.md	valores exactos del estilo, clases, papeles, casos límite
references/familias-diagramas.md	elegir y componer una de las quince familias
references/metaforas.md	idea abstracta para hacerla visible
references/glyphes.md	catálogo de 47 símbolos, añadir un símbolo, 3D opcional
references/modo-live.md	reunión, taller, oral
references/wireframes-flujos.md	maquetas, recorridos, estados de pantalla
references/interactivo.md	páginas animadas, estados, elementos arrastrables
references/lamina-simbolos.png	vista previa de todos los símbolos
examples/	seis bocetos (SVG y PNG), dos páginas interactivas, brut/ (dibujos fuente y configuraciones), build_examples.py