Manual de Identidad Visual¶

Diagramas del libro "Arquitectura Web Moderna — De cero a una infraestructura profesional para Internet"¶

Versión: 1.0 Alcance: 150+ diagramas, ~1,000 páginas Formato base: SVG puro, tokens CSS, compatible MkDocs/GitHub/PDF, modo claro y oscuro

0. Principio rector¶

Un solo diseñador invisible. Si dos diagramas se ven hechos por personas distintas, el sistema falló. Cada regla de este manual existe para eliminar una decisión ad-hoc futura. Antes de dibujar cualquier diagrama nuevo, se consulta este documento — no se improvisa.

1. Filosofía del diseño¶

Dirección: documentación técnica de infraestructura, no ilustración. El diagrama es una herramienta de lectura rápida, no una pieza decorativa.

Principios:

Minimalismo funcional: cada elemento visual comunica algo. Si se puede quitar sin perder información, se quita.
Densidad controlada: preferir varios diagramas simples sobre uno saturado. Un diagrama no debe requerir más de 5-7 segundos para ser comprendido en su estructura general.
Planitud absoluta: cero profundidad simulada (sin 3D, sin degradados, sin sombras dramáticas). La jerarquía se logra con color, tamaño y posición, no con efectos.
Geometría predecible: ángulos de 90° y 45° únicamente. Nada de curvas orgánicas libres.
Silencio visual donde no hay información: espacio en blanco (o "negro" en modo oscuro) generoso; no rellenar vacíos con decoración.

Referencias de tono (no de copia literal): Cloudflare Docs y Vercel Docs por su limpieza de retícula; Stripe Docs por la precisión tipográfica; Linear por el minimalismo de color; GitHub Docs y AWS/GCP Docs por la claridad jerárquica en diagramas de arquitectura.

Lo que nunca se hace: iconos caricaturescos, gradientes decorativos, sombras suaves tipo "neumorphism", tipografías redondeadas informales, colores saturados al máximo, mascotas o personajes.

2. Paleta de colores — Sistema de doble capa anti-colisión¶

Dado el volumen del libro (150+ diagramas, decenas de entidades distintas coexistiendo), se usa un sistema de dos capas para evitar colisión semántica de color:

Capa 1 — Colores de Sistema (estado/función): advertencia, éxito, error, neutro/estructura.
Capa 2 — Colores de Entidad (identidad de marca/concepto): Internet, Cloudflare, AWS, Firebase, GitHub, DNS, Bases de Datos, Usuarios, APIs, Seguridad, IA.

Las dos capas nunca comparten matiz base. Esto permite que, por ejemplo, un error dentro de un bloque de AWS se distinga inmediatamente del naranja de AWS porque el rojo de error está en una familia cromática reservada exclusivamente al Sistema.

2.1 Colores de Sistema¶

Token	Uso	HEX (claro)	HEX (oscuro)
`--color-bg`	Fondo de lienzo	`#FFFFFF`	`#0B0E14`
`--color-surface`	Fondo de tarjeta/nodo	`#F6F8FA`	`#161B22`
`--color-border`	Bordes de contenedores	`#D0D7DE`	`#30363D`
`--color-text-primary`	Texto principal	`#1B1F24`	`#E6EDF3`
`--color-text-secondary`	Texto secundario/labels	`#57606A`	`#8B949E`
`--color-warning`	Advertencias	`#9A6700`	`#D29922`
`--color-success`	Éxito/OK	`#1A7F37`	`#3FB950`
`--color-error`	Error/fallo	`#CF222E`	`#F85149`
`--color-accent`	Énfasis genérico, flujo activo	`#0969DA`	`#58A6FF`

2.2 Colores de Entidad (tokens CSS custom properties)¶

:root {
  --entity-internet:   #0B6E99;
  --entity-cloudflare:  #F38020;
  --entity-aws:         #B7791F; /* ámbar tierra, distinto del warning */
  --entity-firebase:    #D97706; /* cálido, separado de aws por saturación/valor */
  --entity-github:      #24292F;
  --entity-dns:         #2563EB;
  --entity-database:    #6D28D9; /* violeta */
  --entity-users:       #0E7490;
  --entity-api:         #15803D;
  --entity-security:    #B91C1C;
  --entity-ia:          #4F46E5; /* índigo */
}

Nota de refinamiento violeta/índigo (decisión vigente): Base de Datos (#6D28D9, violeta) e IA (#4F46E5, índigo) quedan deliberadamente emparejadas en la misma familia fría-púrpura porque conceptualmente coexisten con frecuencia (RAG, vector stores, embeddings). Se diferencian por: - Matiz: violeta (BD) vs. índigo (IA) — separación de ~30° en el círculo cromático. - Textura de icono: BD usa outline consistente; IA usa relleno sólido parcial en el núcleo del ícono (ver sección 4). - Nunca deben usarse adyacentes sin un separador de label o borde de 2px en --color-border.

Cuando AWS y Firebase aparecen en el mismo diagrama (frecuente: backend en Firebase, CDN/storage en AWS), revisar contraste manualmente; si chocan, Firebase puede desaturarse 10% vía color-mix(in srgb, var(--entity-firebase) 90%, white).

2.3 Regla de aplicación¶

Un color de entidad se usa solo para el borde superior (4px) y el ícono de la tarjeta que representa esa entidad. El cuerpo de la tarjeta siempre es --color-surface.
Los colores de sistema se usan solo para flechas/estado, nunca para rellenar un nodo de entidad.
Máximo 4 colores de entidad distintos visibles simultáneamente en un mismo diagrama. Si se requieren más, se agrupan en un contenedor "cluster" neutro con una sola etiqueta de texto.

3. Tipografía¶

Uso	Fuente	Peso	Tamaño base	Tracking
Títulos de diagrama (si aplica)	Inter	600 (SemiBold)	16px	0
Nombre de nodo/entidad	Inter	600	13px	0
Descripción secundaria dentro de nodo	Inter	400	11px	0
Labels de flecha / protocolo / código	JetBrains Mono	500 (Medium)	10.5px	+0.2px
Etiquetas de puerto, método HTTP, status code	JetBrains Mono	700 (Bold)	10px	0
Notas al pie / leyenda	Inter	400	10px	0

Reglas:

JetBrains Mono se reserva exclusivamente para contenido técnico literal: nombres de servicios con sintaxis (GET /api/v1), variables, códigos de estado, rutas de archivo, comandos. Nunca para nombres descriptivos en prosa.
Mayúsculas: solo para badges cortos de categoría (≤3 palabras), ej. EDGE, CDN, READ-ONLY. Nunca en frases.
Sin cursivas. Sin subrayado (el subrayado se reserva para indicar hyperlink en versión digital).
Interlineado: 1.3 para bloques de texto, 1.0 para una sola línea de label.
Texto siempre --color-text-primary sobre --color-surface, nunca color de entidad (el color de entidad nunca lleva texto encima por contraste impredecible).

4. Iconografía¶

Estilo base: outline, grosor de trazo constante 1.5px a tamaño 24×24px (escala proporcional en otros tamaños). Esquinas con stroke-linejoin: round sutil (radio de unión, no relleno).

Cuándo usar sólido en vez de outline: - Únicamente para el núcleo/centro de íconos de IA (ver nota de la sección 2.2) y para indicadores de estado puntual (punto de "activo", check de éxito, X de error). Regla dura: un ícono nunca es 100% sólido salvo los indicadores de estado (círculos de 6-8px).

Guía de representación por elemento:

Elemento	Forma base	Detalle distintivo
Servidor	Rectángulo vertical con 2-3 líneas horizontales internas	Línea base con pequeño LED (círculo sólido `--color-success`)
Base de datos	Cilindro (elipse superior + cuerpo recto + elipse inferior)	Siempre outline violeta `--entity-database`
Internet	Globo con líneas de longitud/latitud	Nunca relleno, solo trazo
Usuario	Círculo (cabeza) + arco (hombros), simplificado	Sin rostro, sin género marcado
Nube	Forma de nube estándar de 3 lóbulos	Outline; relleno solo si representa un proveedor específico (entonces usa el color de esa entidad al 10% de opacidad como fondo)
Router	Rectángulo horizontal bajo + 2 antenas cortas en ángulo	—
Firewall	Rectángulo con patrón de ladrillos simplificado (3 filas)	Color `--entity-security`
API	Llave inglesa simplificada o `{ }` tipográfico en Mono	Preferir `{ }` para ahorrar espacio en diagramas densos
DNS	Globo + etiqueta de texto `A` / `CNAME` en Mono debajo	—
GitHub	Octocat simplificado NO se usa (marca registrada) → usar rama de Git (3 nodos + 2 líneas)	Color `--entity-github`
Cloudflare	Nube + rayo pequeño superpuesto	Color `--entity-cloudflare`
Firebase	Llama estilizada simplificada (triángulo curvo)	Color `--entity-firebase`
AWS	Caja/cubo isométrico simplificado (sin isometría real, vista frontal con líneas indicando profundidad)	Color `--entity-aws`
Correo	Sobre rectangular con solapa triangular	—
IA	Nodo de red neuronal simplificado: 3 puntos conectados, núcleo central sólido	Color `--entity-ia`, núcleo sólido (ver sección 2.2)
Archivos	Rectángulo vertical con esquina superior derecha doblada	—
Carpetas	Trapecio con pestaña superior	—
Código	`< / >` tipográfico en Mono	—
Variables	`{x}` o símbolo `$` en Mono	—
Seguridad	Candado cerrado, cuerpo rectangular + arco	Color `--entity-security`
HTTPS	Candado pequeño + `S` en badge Mono junto a "HTTP"	—
CDN	Nodo central con 3-4 nodos satélite conectados (representando edge locations)	—
Workers	Engranaje simplificado de 6 dientes	Color `--entity-cloudflare`
Pages	Rectángulo tipo "documento" con línea de navegador arriba	Color `--entity-cloudflare`
R2	Cubo de almacenamiento (cilindro corto y ancho)	Color `--entity-cloudflare`
D1	Cilindro de base de datos pequeño con borde `--entity-cloudflare`	—
KV	Llave + valor: ícono de llave simple	Color `--entity-cloudflare`
Queues	3 rectángulos pequeños en fila con flecha direccional	—
Vectorize	Puntos dispersos conectados por líneas finas (espacio vectorial 2D)	—
Analytics	Barras ascendentes simples (3 barras)	—

Tamaño estándar de ícono dentro de nodo: 20×20px. Nunca mezclar dos grosores de trazo en el mismo diagrama.

5. Diagramas — Reglas estructurales¶

Flechas: - Trazo 1.5px, punta de flecha cerrada simple (triángulo sólido pequeño, no "V" abierta). - Color: --color-text-secondary para flujo neutro; --color-accent para flujo activo/destacado; --color-error solo para indicar fallo/excepción. - Líneas punteadas (stroke-dasharray: 4 3) reservadas exclusivamente para conexiones asíncronas o opcionales. Conexión síncrona = línea continua siempre.

Conectores: - Ángulos ortogonales (90°) para arquitecturas de sistema (jerárquico, top-down o left-right). - Líneas rectas diagonales permitidas solo en diagramas de red/topología donde la posición geográfica/lógica de nodos lo amerite. - Nunca curvas Bézier libres; si se requiere esquinar una ortogonal, usar radio de esquina fijo de 6px.

Distancias: grid base de 8px. Separación mínima entre nodos: 32px (4 unidades de grid). Separación entre grupos/clusters: 48px.

Bordes y esquinas: radio de esquina de tarjeta = 8px. Borde de 1px --color-border en todo nodo; borde superior de 4px en el color de entidad correspondiente (ver 2.3).

Sombras: ninguna por defecto. Excepción única: elevación de un nodo "activo/seleccionado" en diagramas interactivos, con box-shadow de 1 nivel (offset 0 2px, blur 4px, opacidad 8%) — nunca sombras dramáticas.

6. Componentes¶

Componente	Especificación
Tarjeta	`--color-surface`, borde 1px `--color-border`, radio 8px, borde superior 4px color de entidad, padding 12px
Contenedor/Cluster	Borde punteado 1px `--color-border`, sin relleno (o relleno 4% del color de entidad dominante), label en esquina superior izquierda en Mono mayúsculas pequeñas
Bloque	Igual que tarjeta pero sin ícono, usado para texto/anotación
Nodo	Forma mínima (círculo o rectángulo pequeño 40×40px) para diagramas de red de muchos puntos
Servicio	Tarjeta + ícono + nombre + (opcional) badge de estado en esquina superior derecha
Agrupación/Cluster lógico	Ver Contenedor; usar para "Frontend", "Backend", "Edge", "Región us-east-1", etc.
Banner	Franja horizontal de ancho completo, usado solo para separar fases/etapas en diagramas de proceso largo
Etiqueta (badge)	Rectángulo pequeño radio 4px, Mono 10px, color de fondo = color de sistema correspondiente al 12% opacidad, texto en el color de sistema sólido
Nota	Ícono de "i" en círculo + texto Inter 10px, color `--color-text-secondary`
Advertencia	Triángulo con `!`, fondo `--color-warning` al 10%, borde `--color-warning` 1px

7. Diagramas de arquitectura¶

Reglas de representación uniforme:

Internet siempre en el borde superior o izquierdo del diagrama (punto de entrada del flujo).
Usuario siempre como el nodo más a la izquierda o arriba — nunca al centro.
Cloudflare/AWS/Firebase/GitHub representados como "cluster" con su color de borde de entidad envolviendo sus servicios internos (Workers, Pages, R2 dentro del cluster Cloudflare, por ejemplo).
Servidor / API / Base de datos se posicionan en orden de profundidad de izquierda a derecha (edge → compute → data), reflejando el flujo real de una petición.
Storage siempre con ícono de cubo/archivo, nunca con ícono de base de datos (evitar ambigüedad).
CDN/Edge se dibuja como capa horizontal delgada que atraviesa el diagrama, no como nodo único.
Dominios/DNS aparecen siempre antes (a la izquierda) del primer punto de Cloudflare/hosting.

Toda arquitectura sigue flujo de lectura izquierda→derecha o arriba→abajo. Nunca ambas direcciones mezcladas en un mismo diagrama.

8. Diagramas de proceso¶

Secuencias/peticiones/respuestas: formato de diagrama de secuencia clásico (líneas de vida verticales, mensajes horizontales con flecha), actor a la izquierda siempre es el iniciador (Usuario/Cliente).
Flujos HTTP: método y status code siempre en Mono sobre la flecha (GET, 200 OK).
DNS: secuencia con pasos numerados en badges circulares Mono.
Autenticación: uso obligatorio del color --entity-security en cualquier paso de validación/token.
Despliegues / CI/CD / Git: representar como timeline horizontal con commits como nodos circulares pequeños sobre una línea continua; ramas como líneas paralelas que convergen.
Workers: representar como nodo en el borde (edge) del diagrama, nunca en el centro — refuerza el concepto de ejecución en el edge.

9. Diagramas de comparación¶

Formato tabla siempre que sea posible (más legible en impresión y accesible).
Ventajas: ícono de check --color-success. Desventajas: ícono X --color-error. Nunca texto narrativo dentro de la celda para esto — solo ícono + frase corta (máx 6 palabras).
Escalas (ej. rendimiento, costo): barra horizontal simple de 0-100%, color --color-accent, nunca semáforo de 3 colores (genera ambigüedad de "malo/medio/bueno" no siempre aplicable).
Costos: siempre en Mono, formato $XX/mes o $XX/1M req, alineado a la derecha de la celda.

10. Estilo SVG técnico¶

SVG puro, viewBox definido siempre, sin tamaños fijos en px en el propio SVG (escalable).
Sin <filter> para sombras complejas, sin <linearGradient>/<radialGradient> decorativos (excepción: gradiente de 2 paradas idéntico en todo el libro únicamente si se aprueba un caso de uso específico de "flujo activo animado" — no por defecto).
Todos los colores como variables CSS (var(--entity-aws)) embebidas en un <style> dentro del propio SVG, para que el cambio de tema claro/oscuro sea automático vía prefers-color-scheme o clase del contenedor MkDocs.
Texto como <text> real (no convertido a path) para mantener accesibilidad y selección de texto en PDF.
Compatibilidad verificada en: MkDocs (Material), render directo en GitHub markdown, exportación a PDF (sin recortes de viewBox), modo claro y oscuro vía variables.

11. Responsive¶

Diagramas diseñados sobre grid de 8px con viewBox proporcional 16:9 o 4:3 según contenido — nunca tamaño absoluto.
En diagramas complejos (>10 nodos), proveer también una versión "stack vertical" para móvil cuando el viewBox se reescale por debajo de 480px de ancho aparente (criterio: si el texto cae bajo 9px aparente, se reorganiza en columna).
PDF usa siempre la versión horizontal completa (no hay restricción de ancho en impresión a doble página).

12. Accesibilidad¶

Contraste mínimo texto/fondo: AA (4.5:1) en todos los textos de cuerpo; AAA preferido para labels críticos.
Ningún par de colores de entidad depende solo del matiz para distinguirse de otro adyacente: siempre hay diferencia de forma de ícono o texto de etiqueta (relevante para daltonismo rojo-verde y azul-violeta — crítico para el par BD/IA de la sección 2.2).
Tamaño mínimo de texto: 10px a escala 100%; nunca menor.
Toda información codificada por color tiene un respaldo textual o de forma (ej. error no es "solo rojo": lleva ícono X + label).

13. Ejemplos de referencia (descripción textual de composición)¶

Un flujo (request→response): Usuario (izq) → flecha continua GET /api/users (Mono sobre flecha) → API (cluster verde --entity-api) → flecha continua → Base de datos (violeta) → flecha de retorno punteada con 200 OK (Mono) hasta Usuario.
Una arquitectura (stack completo): Internet (arriba-izq) → DNS (azul) → Cloudflare cluster (naranja, conteniendo Workers + Pages) → Firebase cluster (ámbar cálido, conteniendo Auth + Firestore) → todo en flujo izquierda→derecha, con CDN como franja delgada superior atravesando Cloudflare y Firebase.
Una jerarquía (org/roles): Nodo raíz arriba centrado, ramas ortogonales hacia abajo, sin colores de entidad (usar solo --color-text-secondary para conectores), tarjetas idénticas en tamaño por nivel.
Una red (topología): Nodos pequeños (40×40px) conectados por líneas diagonales permitidas, sin clusters, layout de fuerza simulada pero fijado manualmente para consistencia entre ediciones del libro.
Una API: Tarjeta única con ícono { }, borde verde --entity-api, listado interno de endpoints en Mono (GET /users, POST /users), badges de status code a la derecha de cada línea.
Un CDN: Mapa simplificado con nodo central (origen) y 4-5 nodos satélite (edge locations) conectados por líneas punteadas cortas (asíncrono/cache), cada satélite con ícono de "rayo" pequeño indicando velocidad.
Un DNS: Secuencia horizontal: Usuario → Resolver → Nameserver autoritativo → respuesta tipo A/CNAME en badge Mono, pasos numerados en círculos pequeños sobre la línea de flujo.
Una base de datos: Cilindro violeta con líneas internas representando tablas/colecciones, badge Mono debajo con el motor (Firestore, PostgreSQL), conexiones entrantes siempre desde la derecha (consistente con el flujo edge→compute→data de la sección 7).

Checklist de verificación antes de publicar un diagrama nuevo¶

[ ] ¿Usa únicamente los tokens de color definidos en la sección 2?
[ ] ¿El grosor de íconos es 1.5px constante?
[ ] ¿JetBrains Mono solo en contenido técnico literal?
[ ] ¿Ángulos de 90°/45° respetados según el tipo de diagrama?
[ ] ¿Sin sombras, sin gradientes decorativos, sin 3D?
[ ] ¿Funciona en modo claro y oscuro sin tocar el SVG (solo variables)?
[ ] ¿Pasa el contraste AA?
[ ] ¿Máximo 4 colores de entidad simultáneos?
[ ] ¿BD e IA, si coexisten, llevan separador de borde/label?