Diseño de Diagramas
Crea diagramas como archivos HTML autocontenidos con SVG en línea y un sistema de diseño editorial.
Cuarenta y cinco tipos visuales. Los patrones semánticos describen comportamiento; las referencias de tipo describen la disposición.
0. Configuración inicial — puerta de guía de estilo
Antes de generar tu primer diagrama en un nuevo proyecto, verifica que la guía de estilo haya sido personalizada.
No envíes en silencio diagramas con apariencia predeterminada a un proyecto con marca.
Primero resuelve cualquier marcador .diagram-design del proyecto según references/profiles.md; un marcador resuelto con éxito selecciona su perfil y omite esta puerta. Esa referencia es responsable de los fallos, el valor predeterminado protegido y el comportamiento de guardado.
Abre references/style-guide.md y verifica los tokens predeterminados. Si aún son los valores predeterminados de envío (papel #f5f5f5, tinta #2d3142, acento #bf4520), pausa y pregunta al usuario:
"Este es tu primer diagrama en este proyecto y la guía de estilo sigue siendo la predeterminada. ¿Personalizar ahora? Opciones: (a) URL del sitio web, (b) habilidad instalada, (c) carpeta local/sistema de diseño, (d) pegar tokens, (e) mantener predeterminado, (f) cargar perfil guardado."
Luego bifurca según la sección correspondiente de references/onboarding.md; para (f) sigue references/profiles.md.
Una vez que la guía de estilo haya sido personalizada (o el usuario haya elegido explícitamente el valor predeterminado), omite esta puerta en ejecuciones posteriores. Un encabezado de perfil principal nombra el perfil activo copiado. Sin encabezado, cualquier valor de rol semántico o familia tipográfica que difiera de los valores predeterminados de envío significa personalizado-no guardado: omite la puerta y ofrece guardarlo como perfil. Los tokens totalmente predeterminados sin marcador/encabezado activan la puerta. Después de la incorporación, ofrece guardar como perfil de cliente nombrado según references/profiles.md.
1. Filosofía
El movimiento de mayor calidad suele ser la eliminación.
Aplicado a esquemas:
- Cada nodo representa una idea distinta. Dos nodos que siempre viajan juntos son un solo nodo.
- Cada conexión lleva información. Si la relación es obvia por la disposición, elimina la línea.
- El coral es editorial, no una bandera. 1–2 nodos focales por diagrama. Usarlo en 5 nodos borra la señal.
- El esquema no está terminado cuando se ha añadido todo. Está terminado cuando no se puede eliminar nada.
Densidad objetivo: 4/10. Suficiente para ser técnicamente completo. No tan denso que necesite una guía. Por encima de 9 nodos, probablemente sean dos diagramas.
2. Cuándo usar
Usa para cualquiera de los 45 tipos visuales (§3) cuando un lector aprenda más de un elemento visual que de prosa, una tabla o una lista con viñetas.
No uses para:
- Diagramas unicode rápidos → una herramienta de texto plano separada como wiretext. Esta habilidad no incluye una.
- Listas de cosas → tabla o viñetas.
- Antes/después solo de atributos → tabla; cambios de topología → Arquitectura delta.
- "Diagramas" de una sola forma → simplemente escribe la oración.
Antes de dibujar, pregúntate: ¿Aprendería más el lector de esto que de un párrafo bien escrito? Si no, no dibujes.
3. Selección: patrón semántico, luego tipo visual
Cuando el comportamiento, estado, aplicación o riesgo lleva el significado, primero carga references/semantic-patterns.md y elige un patrón primario. Luego elige el tipo visual más cercano para la disposición. Si ningún patrón coincide, elige el tipo directamente.
| Disparador de comportamiento | Patrón semántico → tipo más cercano |
|---|---|
| Fan-in, profundidad de cola, capacidad finita, cuello de botella | Cola de fan-in / cuello de botella → Flujo de datos |
| Ranuras repetidas de Pregunta / Entrada / Gobernanza / Salida en etapas | Marco de etapas con ranuras semánticas → Proceso |
| Conversación o entrada difusa se convierte en un artefacto duradero estructurado | Entrada no estructurada → artefacto estructurado → Flujo de datos |
| Dos trazas de reglas necesitan pasar/fallar/saltar/no alcanzado y primera divergencia | Trazas emparejadas de evaluación de políticas → Diagrama de flujo |
| Límites de confianza más rutas de ingreso o despliegue permitidas/prohibidas | Camino pavimentado seguro → Arquitectura |
| Controles agrupados por dónde se aplican | Catálogo de gobernanza / control → Pila de capas |
| Las defensas compensan brechas previas y el riesgo residual se propaga | Capas de seguridad compensatorias → Pila de capas |
| Descomposición jerárquica direccionable por ID que necesita E/S por bloque, restricciones y un enlace de código | Descomposición de bloque trazable → Árbol |
| Un sujeto progresa a través de fases, esperas, reintentos, cancelación y resultados terminales | Mapa de fases del ciclo de vida → Máquina de estados |
El patrón posee los primitivos semánticos y su presupuesto más ajustado; el tipo posee la gramática de disposición. Usa references/animation.md solo cuando se solicite movimiento o aclare materialmente un cambio ordenado; lo estático sigue siendo el valor predeterminado.
Guía de tipos visuales (45)
| Si estás mostrando… | Usa | Referencia |
|---|---|---|
| Componentes + conexiones en una instantánea; ámbitos anidados de administración vs. tráfico | Arquitectura | type-architecture.md |
| Cambio estructural entre topologías sincronizadas de Antes / Después, con un libro de Cambios | Arquitectura delta | type-architecture-delta.md |
| Panorama de TI heredado por fase o departamento; muestra el estado anterior | Estado actual de TI | type-it-state.md |
| Lógica de decisión con ramificaciones | Diagrama de flujo | type-flowchart.md |
| Mensajes ordenados en el tiempo entre actores | Secuencia | type-sequence.md |
| Estados + transiciones + guardas | Máquina de estados | type-state.md |
| Entidades + campos + relaciones | ER / modelo de datos | type-er.md |
| Eventos posicionados en el tiempo | Línea de tiempo | type-timeline.md |
| Proceso multifuncional con traspasos | Carril | type-swimlane.md |
| Posicionamiento / priorización en dos ejes | Cuadrante | type-quadrant.md |
| Múltiples entidades puntuadas en 3–5 criterios cuantitativos | Radar / Araña | type-radar.md |
| Una serie cuantitativa a través de categorías cíclicas; ángulo=categoría, radio= magnitud | Gráfico polar | type-polar.md |
| Ciclo de refuerzo; el último paso alimenta al primero y un centro acumula estado | Bucle | type-loop.md |
| Jerarquía a través de contención / alcance | Anidado | type-nested.md |
| Relaciones padre → hijo | Árbol | type-tree.md |
| Propiedad humana/agente/equipo, reportes, enrutamiento, escalamiento | Organigrama | type-org-chart.md |
| Niveles de abstracción apilados | Pila de capas | type-layers.md |
| Partes de un objeto separadas a lo largo de un eje: un desmontaje, un desempaquetado, orden de ensamblaje | Axonométrica explotada | type-exploded.md |
| Un piso o sitio visto desde arriba en ángulo: habitaciones con muebles, edificios por fase | Plano axonométrico | type-axonometric-plan.md |
| Superposición entre conjuntos | Venn | type-venn.md |
| Jerarquía clasificada o caída de conversión | Pirámide / embudo | type-pyramid.md |
| Comparación cuantitativa entre categorías | Gráfico de barras | type-bar.md |
| Un total inicial puenteado a un total final por contribuciones firmadas (puente presupuestario, deltas de personal) | Cascada | type-waterfall.md |
| Parte de un todo donde los tamaños relativos son la historia | Treemap | type-treemap.md |
| Datos tabulados cruzados; el relleno codifica el valor por celda | Mapa de calor | type-heatmap.md |
| Tendencias continuas a lo largo del tiempo, cambio entre exactamente dos estados (slopegraph), una distribución por serie (ridgeline) o movimiento de rango a través de varias instantáneas (bump) | Gráfico de líneas | type-line.md |
| Tareas y fases en una línea de tiempo | Gantt | type-gantt.md |
| Correlación o distribución de dos variables; burbuja (tres variables), enjambre de abejas (una variable, punto por elemento) y diagrama de caja (resumen de cinco números por grupo) variantes | Gráfico de dispersión | type-scatter.md |
| Pila de datos de extremo a extremo en un clúster de contenedores | Alto nivel | type-high-level.md |
| Proceso secuencial multi-actor con traspasos de datos | Proceso | type-process.md |
| Almacenamiento de datos de varios niveles con niveles de calidad y políticas de acceso | Medallón | type-medallion.md |
| Flujo de datos con ámbito de rol: quién hace qué en cada paso de la canalización | Flujo de datos | type-data-flow.md |
| Topología de integración de una plataforma de datos — fuentes → núcleo → consumidores | Integración DP | type-dp-integration.md |
| Matriz de permisos de acceso por rol / por componente | Matriz de seguridad DP | type-dp-security-matrix.md |
| Una cantidad que se divide y fusiona a través de etapas, ancho de banda = cantidad | Sankey | type-sankey.md |
| Causas de un efecto observado, agrupadas por categoría (análisis de causa raíz) | Espina de pescado | type-fishbone.md |
| Cadena de valor frente a evolución: qué construir, comprar y qué se está moviendo | Mapa de Wardley | type-wardley.md |
| Trabajo en progreso por estado, con límites de WIP y elementos bloqueados | Kanban | type-kanban.md |
| Lo que una persona hace a través de las etapas de una experiencia y cómo se siente | Viaje del usuario | type-journey.md |
| Lo que el cliente hace vs lo que el servicio oculta, a través de etapas, con una línea de visibilidad | Plano de servicio | type-service-blueprint.md |
| Dónde se ejecuta el software: zonas, hosts, artefactos, réplicas, puertos | Despliegue | type-deployment.md |
| Qué depende de qué, con fan-in y ciclos que un árbol no puede expresar | Gráfico de dependencias | type-dependency.md |
| Clases con operaciones, herencia, composición (otras rutas UML en otra parte) | Clase UML | type-uml-class.md |
| Columna vertebral narrativa dividida en versiones, con la línea de corte | Mapa de historias | type-story-map.md |
| Tablas físicas: tipos SQL, restricciones, índices, FK a nivel de columna | Esquema de base de datos | type-db-schema.md |
Reglas generales:
- Si una tabla de 3 columnas comunica lo mismo, elige la tabla.
- Si dos tipos parecen útiles, elige el eje dominante; un patrón semántico puede agregar primitivos específicos del comportamiento, no una segunda gramática de disposición.
- Si has superado el presupuesto de complejidad (§7), divide en una vista general + detalle.
Siempre carga la referencia del tipo elegido enlazada en la guía antes de dibujar. Cuando se enrute arriba, también carga semantic-patterns.md; cuando se elija animación, carga animation.md.
Confirmar antes de dibujar
Antes de renderizar, indica el plan en un mensaje corto: el tipo visual elegido (y el patrón semántico, si está enrutado), el preset de tamaño y cualquier cosa que el presupuesto de complejidad (§7) fuerce a excluir. Si el usuario es alcanzable, permite que redirija antes de dibujar; si no, procede y anota los supuestos junto al entregable. Omite la pausa solo cuando la solicitud ya fije tipo, tamaño y contenido exactamente.
4. Anti-patrones universales
Estos marcan esquemas "AI slop" de cualquier tipo:
| Anti-patrón | Por qué falla |
|---|---|
| Modo oscuro + resplandor cian/púrpura | Se ve "técnico" sin decisiones de diseño |
| JetBrains Mono como fuente "dev" genérica | Mono es para contenido técnico: puertos, comandos, URL. Los nombres van en Geist sans. |
| Cajas idénticas para cada nodo | Borra la jerarquía |
| Leyenda flotando dentro del área del diagrama | Choca con los nodos |
| Etiquetas de flecha sin rectángulo de enmascaramiento | Se sangra a través de la línea |
Texto vertical con writing-mode en flechas | Ilegible |
| 3 tarjetas de resumen de igual ancho como predeterminado | Cuadrícula genérica: varía los anchos |
| Sombra en cualquier elemento | Las sombras están fuera. Los bordes están dentro. |
rounded-2xl en cajas | Radio máximo 6–10px o ninguno |
| Coral en cada nodo "importante" | El coral es 1–2 acentos editoriales, no un sistema de señalización |
| Reproducir la disposición del renderizador de Mermaid | Importa espaciado y enrutamiento automáticos en lugar de hacer una disposición editorial |
| Cualquier infracción de las seis reglas de conectores del §6 | Fallo automático: inclinaciones diagonales, etiquetas tocando su trazo, máscaras recortadas por un nodo posterior, rutas superpuestas, puntos de fijación compartidos, tránsito detrás de una caja que no es un punto final |
Los anti-patrones específicos de tipo viven en cada referencia de tipo enlazada en la guía.
5. Sistema de diseño
El sistema de diseño es personalizable. references/style-guide.md es la única fuente de verdad para colores, tipografía, tokens y la paleta predeterminada; este archivo nombra roles semánticos (paper, ink, muted, accent, link, …). Para aplicar una marca, edita style-guide.md o ejecuta el flujo basado en URL en references/onboarding.md.
Cuando las especificaciones a continuación o en referencias de tipo mencionen "ink", "accent", "muted", etc., busca el valor hexadecimal actual en
style-guide.md.
Los fragmentos de referencia de tipo escriben roles como marcadores de posición: {ink}, {ink @ 0.40} para un rol con una opacidad, y {node-name}, {sublabel}, {eyebrow}, {arrow-label}, {title}, {callout} para fuentes. Resuelve cada marcador de posición contra style-guide.md antes de emitir.
Roles semánticos (de un vistazo)
| Rol | Propósito |
|---|---|
paper, paper-2 | Fondo de página y fondo de contenedor |
ink | Texto / trazo primario |
muted, soft | Segundo |
...