Estilo y accesibilidad de los diagramas
Todos los diagramas Mermaid de este repositorio usan la misma paleta monocroma. El blanco, el hielo, el gris y el negro deben seguir siendo legibles tanto en el sitio oscuro como en un documento impreso. El color por sí solo nunca transmite una decisión, un fallo ni una responsabilidad.
Paleta
| Token | Color | Uso |
|---|---|---|
| Papel | #ffffff |
Lienzo del diagrama, fondos de etiquetas |
| Hielo | #f5f5f5 |
Nodos principales, notas, filas impares de tablas |
| Gris claro | #e0e0e0 |
Nodos secundarios, participantes, filas pares |
| Gris medio | #bdbdbd |
Nodos terciarios, activaciones |
| Gris de límites | #999999, #777777, #666666, #555555 |
Bordes de grupos y nodos |
| Carbón | #444444, #333333 |
Relaciones, señales |
| Tinta | #111111, #000000 |
Texto y énfasis |
El tema canónico se mantiene en mermaid-theme.json. Cada bloque incluye esa configuración en el frontmatter del diagrama de Mermaid, por lo que la representación en GitHub no depende del CSS del sitio Jekyll.
Elige un diagrama que responda a una pregunta
| Pregunta | Diagrama | Qué no debe implicar |
|---|---|---|
| ¿Qué pasos y puntos de control siguen? | flowchart |
Una flecha no demuestra que se haya ejecutado una herramienta |
| ¿Quién llama a quién y qué se devuelve? | sequenceDiagram |
Un retorno discontinuo no es otra solicitud |
| ¿Qué transiciones de estado son válidas? | stateDiagram-v2 |
Un nombre de estado no es un recurso desplegado |
| ¿Cómo se relacionan los registros? | erDiagram |
Una clave conceptual no crea una restricción de base de datos |
| ¿Qué interfaces dependen de qué tipos? | classDiagram |
Una dependencia no implica necesariamente herencia |
Usamos sintaxis estable compatible con la versión fijada de Mermaid del sitio. GitHub controla su propia versión del renderizador: comprueba el renderizador real antes de adoptar un nuevo tipo de diagrama. Los tipos beta y los motores de disposición de terceros no son necesarios para los laboratorios.
Cada diagrama necesita cuatro elementos
- Un bloque delimitado de Mermaid que use el tema canónico
basey la aparienciaclassic. accTitleyaccDescrque describan este diagrama, no etiquetas genéricas.- Un párrafo adyacente Leyenda. que explique formas, flechas, límites y abreviaturas. Explica por separado las flechas continuas y discontinuas cuando existan ambas.
- Un párrafo adyacente Explicación. que interprete el diagrama y la lección que apoya. Incluye la limitación: por ejemplo, un grafo es un diseño, no evidencia de que se haya producido una ejecución distribuida.
Mantén las etiquetas cortas, evita los grafos decorativos y no dependas de pasar el cursor ni de nodos pulsables para transmitir instrucciones esenciales. El texto y las tablas siguen siendo la fuente de los requisitos.
Validación
node scripts/check-diagrams.js
Esto comprueba la configuración de la paleta y la documentación, no la corrección de un modelo de negocio. Representa también los diagramas nuevos en la vista previa compatible o en el sitio publicado; los fallos de análisis o representación deben corregirse antes de publicar.