Diseño de Diagramas
Si la solicitud es en coreano, todo el texto dentro del diagrama (títulos, etiquetas, descripciones auxiliares, leyendas) se escribe en coreano, dejando solo los nombres propios necesarios en inglés como etiquetas auxiliares. Si se pregunta por el estilo de marca, se procede directamente con el estilo predeterminado si el usuario no lo ha definido. (Versión en coreano: 방구석프로 bangpro.ai.kr · Original: github.com/cathrynlavery/diagram-design, licencia MIT)
Crea diagramas como archivos HTML auto-contenidos con SVG en línea y un sistema de diseño editorial.
Cuarenta y cinco tipos visuales. Los patrones semánticos describen el comportamiento; las referencias de tipo describen la disposición.
0. Configuración inicial — control 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 diagramas con la apariencia predeterminada en un proyecto con marca.
Primero, resuelve cualquier marcador .diagram-design del proyecto según references/profiles.md; un marcador resuelto correctamente selecciona su perfil y omite este control. Esa referencia se encarga de los fallos, el perfil protegido predeterminado y el comportamiento de guardado.
Abre references/style-guide.md y verifica los tokens predeterminados. Si aún son los predeterminados de serie (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/sistema de diseño local, (d) pegar tokens, (e) mantener predeterminado, (f) cargar perfil guardado."
Luego, ramifica 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 la predeterminada), omite este control en ejecuciones posteriores. Un encabezado de perfil principal indica el perfil activo copiado. Sin encabezado, cualquier valor de rol semántico o familia tipográfica que difiera de los valores predeterminados de serie significa personalizado-no guardado: omite el control y ofrece guardarlo como perfil. Todos los tokens predeterminados sin marcador ni encabezado activan el control. Después de la incorporación, ofrece guardar como un perfil de cliente con nombre según references/profiles.md.
1. Filosofía
La acción 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 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 o 2 nodos focales por diagrama. Usarlo en 5 nodos elimina 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 visual que de un texto, una tabla o una lista con viñetas.
No usar 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; los cambios de topología → Delta de arquitectura.
- "Diagramas" de una sola forma → solo escribe la frase.
Antes de dibujar, pregunta: ¿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, el estado, la aplicación o el riesgo transmiten 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.
| Desencadenante de comportamiento | Patrón semántico → tipo más cercano |
|---|---|
| Abanico de entrada, profundidad de cola, capacidad finita, cuello de botella | Cola de abanico de entrada / cuello de botella → Flujo de datos |
| Pregunta/Entrada/Gobernanza/Salida repetida a través de etapas | Marco de etapas con ranuras semánticas → Proceso |
| Conversación o entrada informal se convierte en un artefacto estructurado y duradero | Entrada no estructurada → artefacto estructurado → Flujo de datos |
| Dos trazas de reglas necesitan aprobado/fallido/saltado/no alcanzado y primera divergencia | Trazas de evaluación de políticas emparejadas → Flujograma |
| Límites de confianza más rutas de ingreso/implementación permitidas/prohibidas | Camino pavimentado seguro → Arquitectura |
| Controles agrupados por dónde se aplican | Gobernanza / catálogo de controles → Pila de capas |
| Las defensas compensan las brechas anteriores 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 bloques 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 primitivas semánticas 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; el estático sigue siendo el 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 Antes/Después, con un registro de Cambios | Delta de arquitectura | 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 ramas | Flujograma | type-flowchart.md |
| Mensajes ordenados en el tiempo entre actores | Secuencia | type-sequence.md |
| Estados + transiciones + guardias | Máquina de estados | type-state.md |
| Entidades + campos + relaciones | ER / modelo de datos | type-er.md |
| Eventos posicionados en el tiempo | Cronograma | type-timeline.md |
| Proceso multifuncional con traspasos | Carriles | type-swimlane.md |
| Posicionamiento/priorización en dos ejes | Cuadrante | type-quadrant.md |
| Múltiples entidades puntuadas en 3–5 criterios cuantitativos | Radar / Telarañ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 → hijos | Árbol | type-tree.md |
| Propiedad humana/agente/equipo, informes, 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: desmontaje, unboxing, orden de montaje | Axonométrica explosionada | 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 conectado a un total final mediante contribuciones firmadas (puente presupuestario, deltas de plantilla) | 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 (gráfico de pendiente), una distribución por serie (gráfico de crestas) o movimiento de rango en varias instantáneas (gráfico de baches) | 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; variantes de burbuja (tres variables) y enjambre de abejas (una variable, punto por elemento) | 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 multinivel con niveles de calidad y políticas de acceso | Medallón | type-medallion.md |
| Flujo de datos con alcance de rol: quién hace qué en cada paso del pipeline | 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/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, qué comprar y qué se mueve | Mapa de Wardley | type-wardley.md |
| Trabajo en progreso por estado, con límites 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 de 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 abanico de entrada y ciclos que un árbol no puede expresar | Grafo de dependencias | type-dependency.md |
| Clases con operaciones, herencia, composición (otras rutas UML en otro lugar) | Clase UML | type-uml-class.md |
| Columna vertebral narrativa dividida en lanzamientos, con la línea de corte | Mapa de historia | 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 primitivas específicas del comportamiento, no una segunda gramática de disposición.
- Si estás más allá del presupuesto de complejidad (§7), divide en una visión general y un detalle.
Siempre carga la referencia del tipo elegido vinculada 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 se enrutó), el tamaño preestablecido y cualquier cosa que el presupuesto de complejidad (§7) fuerce a excluir. Si el usuario está disponible, permítele redirigir antes de dibujar; si no, continúa y anota las suposiciones junto al entregable. Omite la pausa solo cuando la solicitud ya especifique exactamente el tipo, el tamaño y el contenido.
4. Anti-patrones universales
Estos marcan esquemas "slop de IA" de cualquier tipo:
| Anti-patrón | Por qué falla |
|---|---|
| Modo oscuro + brillo cian/púrpura | Parece "técnico" sin decisiones de diseño |
| JetBrains Mono como fuente "dev" genérica | Mono es para contenido técnico: puertos, comandos, URLs. 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 con writing-mode vertical 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" | Coral son 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 violación de las seis reglas de conexión §6 | Fallo automático: inclinaciones diagonales, etiquetas que tocan su trazo, máscaras recortadas por un nodo posterior, rutas superpuestas, puntos de unión compartidos, tránsito detrás de una caja que no es punto final |
Los anti-patrones específicos de tipo se encuentran en cada referencia de tipo vinculada en la guía.
5. Sistema de diseño
El sistema de diseño es personalizable. references/style-guide.md es la fuente única 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 las 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.