Diagram Studio
Convierte una especificación JSON en un diagrama nítido. El aspecto es totalmente configurable:
- Dibujado a mano: oscilación de rough.js y fuentes de escritura a mano.
- Vectorial limpio: sin oscilación, fuentes sans o serif, sombras suaves.
- Cualquier punto intermedio.
Todo el texto se convierte en contornos, por lo que el SVG y el PNG se ven idénticos en todas partes. Un linter detecta superposiciones, texto desbordado, etiquetas en los bordes y flechas que atraviesan cajas.
Todo está empaquetado: solo se requiere Node 18+, sin npm install y sin red.
SKILL_DIR a continuación significa la ruta absoluta de esta carpeta de habilidad (la carpeta que contiene este archivo).
node SKILL_DIR/scripts/render.mjs diagram.json --out out/ # → out/diagram.png (2x), .svg, .report.json, .tiles/
0. Ejecución en Codex, Claude Code u otro agente
- SKILL_DIR:
- En Codex, expande la ruta corta de la habilidad con la tabla de raíces de habilidades (p. ej.,
r0/diagram-studio/SKILL.md→~/.codex/skills/diagram-studio). - En Claude Code suele ser
~/.claude/skills/diagram-studio. - Siempre llama a los scripts con esa ruta absoluta.
- En Codex, expande la ruta corta de la habilidad con la tabla de raíces de habilidades (p. ej.,
- Es obligatorio mirar las imágenes: la original, la cuadrícula, los mosaicos y la comparación.
- Codex: usa la herramienta
view_imagecon la ruta PNG.render.mjsescribename.preview.png(≤ 1400 px) para esto, por lo que no es necesario redimensionar la imagen tú mismo; usaname.tiles/*.pngpara los detalles. - Claude Code: usa la herramienta Read.
- Nunca juzgues un renderizado solo por la salida del linter.
- Codex: usa la herramienta
- Amigable con entornos de pruebas:
- Solo se necesita
node. No hay llamadas de red ni instalaciones. - Las salidas van a
--out; mantenlo dentro del espacio de trabajo, p. ej.,./diagram-out. - La conversión WebP/HEIC escribe en el directorio temporal del sistema.
- Solo se necesita
- El usuario pegó una imagen en lugar de dar una ruta: si puedes ver una ruta de archivo adjunto, úsala. De lo contrario, pide la ruta del archivo, porque las herramientas necesitan un archivo real.
- Finalización: enumera las rutas absolutas del PNG, SVG y JSON para que el usuario pueda abrirlos.
1. Elegir el trabajo
| El usuario quiere | Trabajo | Leer a continuación |
|---|---|---|
| "Hacer esta imagen más clara / de mayor resolución / más limpia", "redibujar / reconstruir / 复刻 / 高清重建 esto" | A. Reconstruir desde imagen. Prioridad de fidelidad: mantener el estilo original a menos que se indique lo contrario | references/rebuild-from-image.md (obligatorio) |
| "Embellecer / ordenar / 美化 este diagrama" | A + pulido. Igual que A, luego mejorar jerarquía, espaciado y alineación | references/rebuild-from-image.md |
| Un diagrama nuevo a partir de una descripción, código o notas | B. Nuevo diagrama | references/spec.md |
| Un aspecto diferente ("hacerlo dibujado a mano", "corporativo plano", "plano", "para un artículo") | C. Cambiar estilo | references/style-guide.md |
Para una imagen dada, haz coincidir su estilo por defecto: dibujado a mano sigue siendo dibujado a mano, plano sigue siendo plano, y sus colores y categoría de fuente se mantienen como están. Solo cambia el aspecto cuando el usuario lo pida. Los ajustes preestablecidos son puntos de partida, no límites; styleOverrides, paletas personalizadas y archivos de fuente personalizados ("fonts") pueden reproducir casi cualquier aspecto. Pregunta sobre el nivel de fidelidad solo cuando la solicitud sea genuinamente ambigua, por ejemplo "embellecer" sin un estilo de referencia. De lo contrario, por defecto fiel + más claro.
Comienza desde la plantilla más cercana en templates/: cópiala en tu carpeta de trabajo y edita la copia. Las vistas previas están en assets/gallery/. Una plantilla es un patrón, no contenido: reemplaza todo su texto y mantén los saltos de línea y las flechas exactamente como en tu fuente. --expect detecta elementos sobrantes y cambios de redacción.
| Plantilla | Muestra |
|---|---|
dense-rebuild.json | Reconstrucción de una imagen de arquitectura densa: coordenadas explícitas, tarjetas, paneles, conectores fusionados, etiquetas en línea |
pipeline-rag.json | Tubería de izquierda a derecha: filas con connect, rightOf, paneles de ajuste automático |
layered-architecture-zh.json | Arquitectura en capas en chino: filas apiladas below, flechas en abanico, cilindros |
flowchart-decision.json | Diagrama de flujo: píldora, diamante, ramas sí/no, flechas de retorno |
agent-loop.json | Ciclo: flechas curvas, insignias, centro elíptico |
auto-layout.json | Sin coordenadas: diseño automático ELK con grupos |
2. El bucle (cada trabajo)
-
Inventario primero. Enumera cada cadena de texto textualmente (guárdala como
texts.txt, una por línea), cada nodo, cada flecha (de → a, etiqueta) y cada grupo. Nada se inventa ni se omite. -
Escribe
name.json, comenzando desde una plantilla. -
Renderiza:
node SKILL_DIR/scripts/render.mjs name.json --out OUT --expect texts.txt -
Corrige cada ERROR; cada uno viene con una solución concreta
→. Corrige las ADVERTENCIAS a menos que sean intencionadas, y silencia las intencionadas con"ignore": ["code"]en ese elemento o flecha. -
Mira
OUT/name.pngyOUT/name.tiles/*.png, y compara con el original (scripts/compare.mjs). Ejecuta la lista de verificación enprompts/visual-review.md; el linter no puede juzgar el significado, el equilibrio o la fidelidad. -
Repite los pasos 3–5 hasta que haya 0 errores y se lea bien (generalmente de 2 a 4 rondas).
-
Entrega:
name.png: 2x; usa--scale 3para imprimir.name.svg: vectorial.name.json: conservado para ediciones posteriores.
Añade una línea sobre lo que mantuviste y lo que mejoraste.
3. Especificación en 60 segundos
{
"canvas": { "width": 1600 },
"style": "marker",
"title": "Checkout Service",
"subtitle": "{blue:clients} · {purple:services} · {green:data}",
"elements": [
{ "id": "web", "title": "Web app", "icon": "app-window", "x": 120, "y": 220 },
{ "id": "api", "title": "API", "color": "purple", "emphasis": true, "rightOf": "web", "gap": 160,
"lines": ["`POST /checkout`", { "text": "validates cart", "muted": true }] },
{ "id": "db", "type": "cylinder", "title": "Orders DB", "color": "green", "below": "api", "gap": 120 },
{ "id": "core", "type": "panel", "title": "Backend", "color": "purple", "contains": ["api", "db"] },
{ "id": "n1", "type": "note", "text": "Idempotent by **order id**", "rightOf": "core", "gap": 40 }
],
"arrows": [
{ "from": "web", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "db", "label": "INSERT", "color": "green" }
]
}
-
Tipos de elementos:
box(por defecto),pill,ellipse,circle,diamond,cylinder,note,card,panel,text,icon,badge,image,path(forma SVG personalizada), más los ayudantes de diseñorow,columnygroup. -
Posiciona cada elemento con uno de estos:
x/ypara la esquina superior izquierda, ocx/cypara el centro.below/above/rightOf/leftOfmásgap.contains, que ajusta automáticamente un panel alrededor de sus hijos.
El tamaño es automático. Establece
w/hpara coincidir exactamente con un original. -
Texto:
titlees negrita, y\ndivide la línea.linesson líneas del cuerpo. Marcado dentro del texto:**bold**`code`(usa la fuente de código){green:span}y{muted:span}->(se dibuja como un glifo de flecha)
El chino y el inglés se mezclan libremente. Por elemento puedes establecer
size,textSize,font,textColoryalign. -
Color con una familia (
blue purple green orange red teal yellow pink gray navy), un tono (blue.tint),#hexo un nombre CSS simple comowhite, establecido a través decolor,fill,strokeytextColor. -
Flechas conectan
fromato:- Fija un lado y deslízate a lo largo de él con
"id.right"o"id.right+20". - Etiquetas:
label, colocada conlabelPos(above,below,left,rightoinline) y desplazada conlabelAt. - Aspecto:
dash,color,widthyhead(end,start,bothonone). - Ruta: puntos
via,points(una polilínea exacta), o"route": "curve".
- Fija un lado y deslízate a lo largo de él con
Cada clave está en references/spec.md.
4. Aspecto: estilo, paleta, fuente, efectos
-
Ajustes preestablecidos de estilo:
- Dibujado a mano:
marker(por defecto),neat,excalidraw,sketchy,whiteboard,pencil,blueprint,chalk. - Limpio:
clean,paper.
Cualquier campo de ajuste preestablecido se puede anular mediante
styleOverrides:roughness(0 = líneas perfectamente rectas) ybowingfillStyle(solid,hachure,cross-hatch,dotsonone)strokeScale,cornerRadiusshadow(none,softohard)font,cjkFont,codeFont,background
- Dibujado a mano:
-
Paletas:
marker,pastel,excalidraw,mono,academic,colorblind,modern,blueprint,chalkboard,midnight. Para reproducir los colores de un original exactamente, ejecutanode SKILL_DIR/scripts/palette.mjs original.pngy pega el resultado. -
Fuentes:
- Escritura a mano:
shantell,kalam,caveat,patrick,architects. - Sans:
inter. Serif:serif. Mono:mono. - CJK:
kai(escrita a mano),kuaile(juguetona),sans-sc(limpia). - Tus propios
.ttf/.otf/.woff:"fonts": {"brand": {"regular": "Brand.ttf", "bold": "Brand-Bold.ttf"}}, luego"font": "brand".
- Escritura a mano:
-
Catálogos:
assets/gallery/styles.png,palettes.pngyfonts.png. Regéneralos conscripts/catalog.mjs. -
Iconos: Más de 1500 iconos de Lucide. Busca con
node SKILL_DIR/scripts/icons.mjs search 数据库 robot queue, y previsualiza conicons.mjs sheet a,b,c. -
Herramientas de imagen original:
grid.mjs: superpone coordenadas en el original. Lee las etiquetas del eje rojo, nunca las posiciones de píxeles.fontmatch.mjs: muestra texto de muestra en cada fuente junto a un recorte ampliado del original.palette.mjs: extrae los colores del original.crop.mjs: recorta logotipos, fotos o capturas de pantalla para incrustarlos como elementosimage.compare.mjs: revisión lado a lado; añade--crop x,y,w,hpara ampliar ambas imágenes a la misma región.
-
Versiones oscuras o alternativas: mantén la misma especificación y cambia solo
palette(midnight,blueprintochalkboard) ostyle, luego renderiza con otro--name. -
Para diapositivas (PPT, Keynote):
"canvas": {"aspect": "16:9"}rellena la imagen con la relación de aspecto de la diapositiva."background": "transparent"da un PNG con alfa. El SVG también se puede pegar directamente.
5. Reglas de claridad (siempre aplicables)
- Mantén las palabras exactamente como se dan: etiquetas, identificadores de código y términos chinos. Nunca inventes, traduzcas ni elimines texto a menos que se te pida.
- Haz visible la jerarquía:
- Título en negrita por caja.
- Identificadores como texto del cuerpo o
code. - Explicaciones como texto
muted. - Títulos de sección en el color de su sección.
- El color significa algo: una familia por región o rol, utilizada de forma coherente. Las etiquetas de las flechas heredan el color de su flecha.
- Espacio para respirar:
- ≥ 60 px entre formas unidas por una flecha etiquetada, ≥ 24 px en caso contrario.
- Paneles ajustados con
contains. - Sin etiqueta en un borde.
- Legible al reducir:
- Texto ≥ 18 px (valores predeterminados: nodo 30, cuerpo 25, etiqueta 24).
- Lienzo de 1400–2200 px de ancho, con una relación de aspecto entre 1:2 y 3:1. El linter advierte en caso contrario.
- Cadenas largas de 6 o más nodos: enróllalas en 2–3 filas, o usa ELK
"direction": "DOWN", en lugar de una fila muy larga.
- Pocos cruces y sin desvíos. Alinea y reordena antes de añadir
via. - Pule, no rediseñes, en trabajos de reconstrucción: mejora la alineación, el espaciado y la jerarquía, pero mantén la topología, el orden de lectura y la identidad del estilo.
6. Definición de terminado
-
render.mjsinforma 0 errores. Cualquier advertencia restante es intencionada y se silencia conignore. - Cada cadena del inventario está presente y escrita exactamente (
--expect texts.txtpasa). - Has visto el PNG y los mosaicos, y para las reconstrucciones los has comparado lado a lado con el original: misma estructura, misma identidad de estilo, más claro.
- Has entregado el PNG, SVG y JSON, con una breve nota "mantenido / mejorado".
7. Solución de problemas
node: command not found: instala Node 18+. No se necesita nada más.- La entrada WebP, HEIC, BMP o TIFF se convierte automáticamente cuando
sips,magick,dwebp,ffmpego Python PIL están disponibles. De lo contrario, pide al usuario un PNG o JPEG. - Un carácter se renderiza como
?: las fuentes incluidas cubren latín, chino GB2312 y símbolos comunes. Reformúlalo, o registra una fuente que lo tenga. - Para cada código de lint y su solución, consulta
references/troubleshooting.md.