Diseño de Diagramas
Crea diagramas como archivos HTML autocontenidos con SVG incrustado 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 maquetación.
0. Configuración inicial — puerta de la guía de estilo
Antes de generar tu primer diagrama en un nuevo proyecto, verifica que la guía de estilo se haya personalizado.
No envíes en silencio diagramas con la apariencia predeterminada a 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 esta puerta. Esa referencia es la propietaria de los fallos, el valor protegido por defecto y el comportamiento de guardado.
Abre references/style-guide.md y comprueba los tokens por defecto. Si aún son los valores predeterminados (fondo #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) skill instalado, (c) carpeta local/sistema de diseño, (d) pegar tokens, (e) mantener valores predeterminados, (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 se haya personalizado (o el usuario haya elegido explícitamente los valores predeterminados), 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 significa personalizado-no guardado: omite la puerta y ofrece guardarlo como perfil. Los tokens todos predeterminados sin marcador/encabezado activan la puerta. Después de la incorporación, ofrece guardar como un perfil de cliente con nombre según references/profiles.md.
1. Filosofía
El movimiento de mayor calidad suele ser la eliminación.
Aplicado a los esquemas:
- Cada nodo representa una idea distinta. Dos nodos que siempre viajan juntos son un solo nodo.
- Cada conexión transporta información. Si la relación es obvia por la maquetación, elimina la línea.
- El coral es editorial, no una bandera. 1–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 prosa, una tabla o una lista con viñetas.
No uses para:
- Diagramas rápidos en unicode → una herramienta de texto plano separada como wiretext. Esta skill no incluye una.
- Listas de cosas → tabla o viñetas.
- Antes/después solo de atributos → tabla; cambios de topología → Architecture delta.
- "Diagramas" de una sola forma → simplemente escribe la frase.
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 transmita el significado, primero carga references/semantic-patterns.md y elige un patrón primario. Luego elige el tipo visual más cercano para la maquetació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 | Fan-in queue / bottleneck → Data flow |
| Ranuras repetidas de Pregunta / Entrada / Gobernanza / Salida en todas las etapas | Stage framework with semantic slots → Process |
| Conversación o entrada suelta se convierte en un artefacto duradero estructurado | Unstructured input → structured artifact → Data flow |
| Dos trazas de reglas necesitan pasar/fallar/saltar/no alcanzado y primera divergencia | Paired policy-evaluation traces → Flowchart |
| Límites de confianza más rutas de entrada o despliegue permitidas/prohibidas | Secure paved road → Architecture |
| Controles agrupados por dónde se aplican | Governance / control catalog → Layer stack |
| Las defensas compensan brechas previas y el riesgo residual se propaga | Compensating security layers → Layer stack |
| Descomposición jerárquica direccionable por ID que necesita E/S por bloque, restricciones y un enlace de código | Traceable block decomposition → Tree |
| Un sujeto progresa a través de fases, esperas, reintentos, cancelación y resultados terminales | Lifecycle phase map → State Machine |
El patrón posee los primitivos semánticos y su presupuesto más ajustado; el tipo posee la gramática de maquetación. Usa references/animation.md solo cuando se solicite movimiento o aclare materialmente un cambio ordenado; el 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 de administración vs tráfico anidados | Architecture | type-architecture.md |
| Cambio estructural entre topologías sincronizadas de Antes / Después, con un registro de Cambios | Architecture delta | type-architecture-delta.md |
| Panorama de TI heredado por fase o departamento; muestra el estado anterior | IT current-state | type-it-state.md |
| Lógica de decisión con ramificaciones | Flowchart | type-flowchart.md |
| Mensajes ordenados en el tiempo entre actores | Sequence | type-sequence.md |
| Estados + transiciones + guardas | State machine | type-state.md |
| Entidades + campos + relaciones | ER / data model | type-er.md |
| Eventos posicionados en el tiempo | Timeline | type-timeline.md |
| Proceso multifuncional con traspasos | Swimlane | type-swimlane.md |
| Posicionamiento / priorización en dos ejes | Quadrant | type-quadrant.md |
| Múltiples entidades puntuadas en 3–5 criterios cuantitativos | Radar / Spider | type-radar.md |
| Una serie cuantitativa en categorías cíclicas; ángulo=categoría, radio=magnitud | Polar chart | type-polar.md |
| Ciclo de refuerzo; el último paso alimenta al primero y un centro acumula estado | Loop | type-loop.md |
| Jerarquía a través de contención / alcance | Nested | type-nested.md |
| Relaciones padre → hijos | Tree | type-tree.md |
| Propiedad, informes, enrutamiento, escalado humano/agente/equipo | Org chart | type-org-chart.md |
| Niveles de abstracción apilados | Layer stack | type-layers.md |
| Partes de un objeto separadas a lo largo de un eje: un desmontaje, desempaquetado, orden de ensamblaje | Exploded axonometric | type-exploded.md |
| Un piso o sitio visto desde arriba en ángulo: habitaciones con muebles, edificios por fase | Axonometric plan | type-axonometric-plan.md |
| Superposición entre conjuntos | Venn | type-venn.md |
| Jerarquía clasificada o caída de conversión | Pyramid / funnel | type-pyramid.md |
| Comparación cuantitativa entre categorías | Bar chart | type-bar.md |
| Total inicial puenteado a un total final por contribuciones firmadas (puente presupuestario, cambios de plantilla) | Waterfall | 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 | Heatmap | type-heatmap.md |
| Tendencias continuas en el tiempo, cambio entre exactamente dos estados (slopegraph), una distribución por serie (ridgeline), o movimiento de rango en varias instantáneas (bump) | Line chart | 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 burbuja (tres variables) y beeswarm (una variable, un punto por elemento) | Scatter plot | type-scatter.md |
| Pila de datos de extremo a extremo en un clúster de contenedores | High-Level | type-high-level.md |
| Proceso secuencial multi-actor con traspasos de datos | Process | type-process.md |
| Almacenamiento de datos de múltiples niveles con niveles de calidad y políticas de acceso | Medallion | type-medallion.md |
| Flujo de datos con alcance de roles: quién hace qué en cada paso de la canalización | Data flow | type-data-flow.md |
| Topología de integración de una plataforma de datos — fuentes → núcleo → consumidores | DP integration | type-dp-integration.md |
| Matriz de permisos de acceso por rol / por componente | DP security matrix | 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) | Fishbone | type-fishbone.md |
| Cadena de valor contra evolución — qué construir, comprar y qué se mueve | Wardley map | type-wardley.md |
| Trabajo en curso 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 | User journey | 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 | Service blueprint | type-service-blueprint.md |
| Dónde se ejecuta el software — zonas, hosts, artefactos, réplicas, puertos | Deployment | type-deployment.md |
| Qué depende de qué, con fan-in y ciclos que un árbol no puede expresar | Dependency graph | type-dependency.md |
| Clases con operaciones, herencia, composición (otras rutas UML en otra parte) | UML class | type-uml-class.md |
| Columna vertebral narrativa dividida en versiones, con la línea de corte | Story map | type-story-map.md |
| Tablas físicas: tipos SQL, restricciones, índices, FK a nivel de columna | Database schema | type-db-schema.md |
Reglas prácticas:
- 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 añadir primitivos específicos del comportamiento, no una segunda gramática de maquetación.
- Si has superado el presupuesto de complejidad (§7), divide en una visión general + detalle.
Carga siempre la referencia del tipo elegido enlazada en la guía antes de dibujar. Cuando se enruta arriba, carga también semantic-patterns.md; cuando se elige animación, carga animation.md.
Confirma 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 preajuste de tamaño y cualquier cosa que el presupuesto de complejidad (§7) fuerce a excluir. Si el usuario está disponible, deja que redirija antes de dibujar; si no, procede y anota las suposiciones junto al entregable. Omite la pausa solo cuando la solicitud ya especifique exactamente el tipo, tamaño y contenido.
4. Anti-patrones Universales
Estos marcan esquemas "basura 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" general | 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 máscara | Se filtra a través de la línea |
Texto vertical con writing-mode en flechas | Ilegible |
| 3 tarjetas de resumen de igual ancho como valor 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 es 1–2 acentos editoriales, no un sistema de señalización |
| Reproducir la maquetación del renderizador de Mermaid | Las importaciones usan espaciado y enrutamiento automáticos en lugar de hacer una maquetación editorial |
| Cualquier infracción de las seis reglas de conectores del §6 | Falla automática: 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 el 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 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.
Roles semánticos (de un vistazo)
| Rol | Propósito |
|---|---|
paper, paper-2 | Fondo de página y fondo de contenedor |
ink | Texto primario / trazo |
muted, soft | Texto secundario, flechas predeterminadas, subetiquetas |