IbrahimSobh/content-mermaid

Content Mermaid

Produce diagramas Mermaid para procesos y estructuras técnicas. Es la contraparte rápida y basada en sintaxis de content-diagrams: mismos estándares de claridad visual, pero construido sobre un lenguaje que ya garantiza una geometría correcta, por lo que el esfuerzo se centra en elegir el tipo de diagrama adecuado y un sistema de colores legible y consistente, en lugar de verificar coordenadas.

Relación con content-diagrams

Ambas habilidades comparten los mismos estándares — texto legible, un sistema de colores real en lugar de decoración, claridad sobre densidad— pero content-diagrams calcula su propia geometría SVG manualmente mientras que esta habilidad delega la geometría por completo al motor de diseño de Mermaid; elige entre ellas según dónde se visualizará realmente el diagrama (superficie Mermaid nativa vs. una plataforma que solo muestra imágenes estáticas), no por costumbre, y si realmente no estás seguro, pregunta — el código fuente de Mermaid no se convierte en una imagen independiente y pulida sin un trabajo real de reelaboración.

Por qué no hay bucle de verificación aquí

content-diagrams dedica la mayor parte de su esfuerzo a la geometría: una línea, caja o etiqueta SVG son solo números que Claude calculó, y los números calculados pueden ser incorrectos — de ahí renderizar, capturar, recortar y verificar.

Mermaid elimina ese modo de fallo por completo. El ancho de los nodos, el ajuste de texto, las rutas de las flechas y la evitación de colisiones entre elementos son tarea del renderizador, no de Claude — el renderizador no colocará una etiqueta encima de una caja ni trazará una línea a través de una forma. Rederivar ese bucle de verificación aquí (capturar el diagrama renderizado, recortarlo, verificar superposiciones) solo quemaría tokens y latencia confirmando algo que la herramienta ya garantiza.

Lo que aún puede fallar es completamente diferente, y completamente textual:

• Sintaxis rota (corchetes no cerrados, una palabra reservada usada como ID de nodo, tipos de flecha no coincidentes)
• Una arista que hace referencia a un ID de nodo que nunca se ha definido
• Mal contraste de color (un relleno y un color de texto que en realidad no se leen el uno contra el otro)
• El tipo de diagrama incorrecto para la estructura real del contenido

Así que la verificación aquí significa: leer la sintaxis una vez para comprobar su corrección, verificar que cada classDef empareje un relleno con un color de texto genuinamente contrastado, y confirmar que el tipo de diagrama coincide con lo que se está modelando. No se requiere renderizado de imágenes.

Selección del tipo de diagrama

Elige el tipo según la estructura del contenido — este es el equivalente Mermaid de la selección de motivos de content-diagrams:

Estructura del contenido	Tipo Mermaid
Pasos secuenciales con ramas/bucles (un proceso, un flujo de trabajo, un algoritmo)	flowchart TD (arriba-abajo) o LR (izquierda-derecha para pipelines/líneas de tiempo)
Mensajes ordenados en el tiempo entre actores/servicios (llamadas API, intercambios de protocolo)	sequenceDiagram
Estados de una entidad y las transiciones entre ellos (un ciclo de vida, una máquina de estados)	stateDiagram-v2
Modelo de datos / relaciones entre entidades (esquemas, tablas de BD)	erDiagram
Estructura orientada a objetos (clases, herencia, interfaces)	classDiagram
Cronograma con duraciones y dependencias	gantt
Desglose jerárquico / lluvia de ideas sin secuencia estricta	mindmap
Narrativa cronológica (historial de un proyecto, historial de versiones)	timeline
Priorización de dos ejes (impacto vs. esfuerzo, etc.)	quadrantChart

No uses flowchart por defecto para todo — una solicitud como "diagrama cómo se llaman nuestros servicios entre sí" es un sequenceDiagram aunque sea tentador dibujarlo como cajas y flechas; una solicitud como "muestra los estados por los que pasa un ticket" es stateDiagram-v2, no un diagrama de flujo con rombos que representan estados.

Sistema de color y legibilidad

Este es el único lugar donde la verificación manual sigue siendo importante, porque Mermaid renderizará sin quejarse opciones de color ilegibles.

La regla: cada classDef debe emparejar un relleno con un color de texto que se haya elegido deliberadamente para contrastar con él — nunca dejes color sin establecer y esperes que el tema por defecto funcione. La paleta predeterminada de Mermaid (verde/rosa/azul suave con texto negro) está bien precisamente porque el relleno y el texto se eligieron juntos; en el momento en que sobrescribes fill con algo más saturado u oscuro, también debes establecer color explícitamente, o reproducirás un defecto común: cajas de aspecto legible con texto que en realidad tiene poco contraste contra ellas.

Dos recetas de paleta, elige una y úsala de forma consistente en todas las clases de un diagrama (no las mezcles):

1. Relleno oscuro / texto blanco (la predeterminada — probada, alto contraste, se lee bien tanto en temas claros como oscuros del chat):

   classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff
   

2. Relleno de tinte claro / texto oscuro / trazo saturado (úsala cuando un diagrama necesite situarse visualmente junto a un SVG de content-diagrams que siga su convención de tinte claro):

   classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
   

Tomando prestada directamente la regla de content-diagrams: un tono por categoría, aplicado dondequiera que aparezca esa categoría — el mismo color en relleno/trazo en cada nodo de ese rol, no uno único. Asigna tonos por rol, p. ej.:

• Azul → entradas / datos / elementos del backlog
• Verde → proceso / pasos de trabajo activos
• Ámbar o marrón → puntos de decisión / compuertas
• Púrpura → salidas / versiones / estados terminales
• Rojo → bucles de retroalimentación / rutas de fallo / retrospectiva

Bloquea el canvas para que no dependa del modo claro/oscuro del anfitrión. Coloca una directiva init como la primera línea del diagrama:

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%

theme: 'base' más themeVariables explícitos significa que el diagrama se ve igual independientemente del tema Mermaid al que el entorno anfitrión tenga como predeterminado — no confíes solo en el nombre del tema predeterminado (default, dark, forest, etc.), ya que eso deja los colores reales a lo que decida el renderizador.

Tamaño de fuente: 16px como mínimo para cualquier diagrama con más de unos pocos nodos; 14px solo si el diagrama es lo suficientemente simple como para que la legibilidad no esté en duda. Si un diagrama necesita reducirse por debajo de 14px para que quepan sus etiquetas, esa es la misma señal de "claridad sobre densidad" de content-diagrams — divide el diagrama o recorta contenido, no reduzcas más el texto.

El alcance del estilo difiere según el tipo de diagrama: flowchart, stateDiagram-v2 y classDiagram admiten la asignación directa de classDef/class por nodo, así que usa el sistema de color por categoría anterior nodo por nodo. sequenceDiagram, erDiagram y gantt tienen un estilo por elemento mucho más limitado — para esos, pon el esfuerzo en los themeVariables en el bloque init (actorBkg, actorTextColor, noteBkgColor, etc. para diagramas de secuencia) en lugar de esperar que las clases a nivel de nodo funcionen de la misma manera.

Gramática de flechas

A diferencia del SVG codificado a mano, Mermaid renderiza las etiquetas de las flechas limpiamente con colocación automática — el texto de -->|etiqueta| no corre el riesgo de caer encima de una forma como lo haría una etiqueta SVG posicionada manualmente. Por lo tanto, a diferencia de la opción predeterminada de content-diagrams de "mantener el texto fuera de las flechas, decodificar mediante leyenda", etiquetar las flechas directamente está bien y a menudo es más claro aquí. Aun así, mantén las etiquetas como fragmentos cortos ("aprobado", "reintentar", "en caso de fallo") en lugar de frases — una etiqueta es una etiqueta, no una oración.

Reserva el estilo de línea para la misma distinción amplia que usa content-diagrams:

• Flecha sólida (-->) → flujo primario/normal
• Flecha discontinua (-.->) → retroalimentación, una ruta opcional o una interacción externa/indirecta
• Flecha gruesa (==>) → una ruta enfatizada o crítica, utilizada con moderación

Mantén las etiquetas cortas; usa subgrafos para agrupar

El texto del nodo debe ser una frase corta, no una oración — Mermaid ajustará o desbordará torpemente las etiquetas de longitud de párrafo como cualquier otra herramienta. Si un nodo necesita varias líneas, introdúcelas explícitamente con <br/> dentro de la etiqueta en lugar de confiar en que el ajuste automático corte en un lugar sensato.

Usa subgraph para agrupar pasos relacionados (por ejemplo, todo dentro de un sprint, una etapa de despliegue, un límite de servicio) — es el equivalente Mermaid de una caja de agrupación, y se puede estilizar con su propia línea style NombreSubgrafo fill:...,stroke:.... No anides subgrafos a más de un nivel de profundidad; se vuelve difícil de leer rápidamente.

Flujo de trabajo

1. Identifica la estructura subyacente y elige el tipo de diagrama de la tabla anterior antes de escribir cualquier sintaxis.
2. Asigna colores de categoría a los roles presentes (entradas, pasos de proceso, decisiones, salidas, retroalimentación) — esboza esto en una o dos oraciones antes de escribir los classDef, igual que el paso de "esbozar el razonamiento del motivo" de content-diagrams, para que la elección sea auditable si el usuario quiere ajustar una pieza.
3. Escribe el diagrama, comenzando con la directiva %%{init: ...}%%, luego la estructura, luego las asignaciones de classDef/class (o themeVariables para tipos que no admiten clases por nodo).
4. Autoverifica la sintaxis — cada ID de nodo usado en una arista está definido en alguna parte; cada classDef tiene tanto fill como color establecidos; los corchetes/comillas están equilibrados; no hay etiquetas de longitud de párrafo. Sin renderizado, sin capturas de pantalla.
5. Guarda como un archivo .mermaid mediante create_file para que se renderice en línea como un artefacto, usando un slug descriptivo: /mnt/user-data/outputs/<slug>.mermaid. Preséntalo con present_files.
6. Si el usuario necesita el diagrama como una imagen estática portátil (para incrustarlo en algún lugar que no renderice Mermaid, o para archivarlo), dilo claramente: este entorno no ejecuta de forma fiable la exportación headless de Mermaid a imagen (depende de una descarga de Chromium a la que la red en modo sandbox generalmente no puede acceder). Señala mermaid.live para una exportación manual, o cambia a content-diagrams si el requisito real es un gráfico independiente.

Qué no hacer

• No dejes el color de un classDef sin establecer después de sobrescribir fill — ese es el error de contraste exacto que esta habilidad existe para evitar.
• No mezcles las recetas de paleta de relleno oscuro y relleno claro dentro de un mismo diagrama.
• No uses flowchart por defecto para cada solicitud — elige el tipo que coincida con la estructura real (secuencia, estado, ER, etc.).
• No reintroduzcas el bucle de renderizar/recortar/verificar de content-diagrams aquí — está resolviendo un problema que el motor de diseño de Mermaid no tiene.
• No pongas texto de longitud de párrafo en una etiqueta de nodo; ajusta con <br/> o recorta el contenido.
• No anides subgrafos a más de un nivel.
• No prometas una exportación limpia a PNG/SVG desde este sandbox sin advertir que el renderizado headless de Mermaid puede no funcionar aquí.