6.3 KiB
6.3 KiB
| name | description |
|---|---|
| diagrams-and-data-tables | Guides the creation, structure, and styling of professional Mermaid diagrams (sequence, flowcharts, ERD, state transitions) and high-density, accessible data tables with glassmorphism, responsive behavior, micro-interactions, and WCAG compliance. Use when designing data representations, documenting architecture, or implementing UI tables. |
Diagrams and Data Tables Skill
This skill enforces best practices for visualizing software architecture through Mermaid diagrams and creating production-grade, accessible data tables across the frontend and technical documentation.
Part 1: Mermaid Diagrams Engineering
Mermaid diagrams provide living documentation of architectural patterns, data flows, and relational schemas.
1. Core Syntax Rules
- Quote Node Labels: Always quote labels containing special characters, brackets, or parentheses:
id["Process (Async)"]. - Avoid HTML in Labels: Use pure Markdown formatting or plain text; avoid
<br/>or raw tags where Mermaid may parse them incorrectly. - Direction & Clean Layout: Use
flowchart TD(top-down) for hierarchical flows orflowchart LR(left-to-right) for sequential pipelines.
2. Common Diagram Patterns
A. Sequence Diagram: WebSocket Client-Server Flow
sequenceDiagram
autonumber
actor User as Usuario / Client
participant UI as React Frontend
participant WS as WebSocket Server (Ratchet)
participant Auth as JWT Guard
participant RAG as RAG / Gemini Engine
participant DB as MySQL Database
User->>UI: Escribe mensaje
UI->>WS: {"action": "chat_message", "token": "jwt..."}
WS->>Auth: Validar token y rol
Auth-->>WS: Rol verificado (e.g. Interno)
WS->>RAG: Consultar Base Conocimiento / Embeddings
RAG->>DB: SELECT cosine_similarity...
DB-->>RAG: Documentos relevantes
RAG-->>WS: Stream chunks de respuesta
WS-->>UI: {"type": "stream_chunk", "chunk": "..."}
UI-->>User: Renderizado progresivo
B. Flowchart: RAG Query & Tool Routing
flowchart TD
A["Entrada del Usuario"] --> B{"¿Consulta de Horarios / Ambientes?"}
B -- "Sí" --> C["Tool: CRONODE API"]
B -- "No" --> D{"¿Búsqueda en Base de Conocimiento?"}
C --> E["Formatear Matriz / Calendario"]
D -- "Sí" --> F["Búsqueda Vectorial (Cosine Similarity)"]
D -- "No" --> G["Generación General Gemini LLM"]
F --> H["Inyectar Contexto RAG"]
H --> I["Generar Respuesta Verificada"]
E --> J["Enviar Payload + Table Data al Cliente"]
I --> J
G --> J
C. Entity-Relationship Diagram (ERD)
erDiagram
usuarios ||--o{ chat_historial : "posee"
usuarios ||--o{ conversaciones : "registra"
roles ||--o{ usuarios : "asigna_a"
categorias ||--o{ temas : "agrupa"
temas ||--o{ preguntas_respuestas : "contiene"
temas ||--o{ documentos : "asocia"
usuarios {
int id PK
string email
string rol
boolean activo
}
categorias {
int id PK
string nombre
text descripcion
}
temas {
int id PK
int categoria_id FK
string nombre
}
preguntas_respuestas {
int id PK
int tema_id FK
text pregunta
text respuesta
}
Part 2: High-Density UI Data Tables
When creating data tables in the frontend (React / Tailwind / Vanilla CSS):
1. Visual Aesthetics & Design System Tokens
- Glassmorphism Base:
<div className="overflow-x-auto custom-scrollbar w-full rounded-2xl border border-black/8 dark:border-white/10 bg-white/70 dark:bg-[rgba(10,22,10,0.75)] backdrop-blur-xl shadow-xs"> <table className="w-full text-left text-xs border-collapse min-w-[600px]"> - Institutional Headers (SENA Palette):
<thead className="bg-[#39A900] dark:bg-[rgba(57,169,0,0.85)] text-white font-semibold text-[11px] sticky top-0 z-10"> <tr> <th scope="col" className="py-2.5 px-3.5 whitespace-nowrap">ID</th> <th scope="col" className="py-2.5 px-3.5 whitespace-nowrap">Nombre</th> </tr> </thead> - Zebra Striping & Hover States:
- Even rows:
even:bg-black/[0.02] dark:even:bg-white/[0.02] - Hover:
hover:bg-[#39A900]/8 dark:hover:bg-lime/8 transition-colors - Subtle cell borders:
border-b border-black/6 dark:border-white/6
- Even rows:
2. Rich Cell Typography & Components
- Status Badges:
- Active / Free:
bg-emerald-500/15 text-emerald-700 dark:text-emerald-400 border border-emerald-500/30 - Inactive / Occupied:
bg-red-500/15 text-red-700 dark:text-red-400 border border-red-500/30 - Pending / Warning:
bg-amber-500/15 text-amber-700 dark:text-amber-400 border border-amber-500/30
- Active / Free:
- Action Buttons: Icon-first buttons with active scale:
p-1.5 rounded-lg bg-black/5 dark:bg-white/5 hover:bg-black/10 dark:hover:bg-white/10 active:scale-95 transition-all - Text Truncation: Use
max-w-[200px] truncatewithtitle={val}on hover to prevent column blowout.
3. Responsive Table Adaptations (Mobile-First)
- Container Scroll: Always wrap tables in
overflow-x-auto custom-scrollbarso mobile viewports swipe horizontally without breaking parent layout boundaries. - Card-View Alternative: For complex administrative views (e.g.,
CrudPage.jsx), provide a toggle between structured table view (viewMode="table") and card grid view (viewMode="card").
Part 3: Markdown Tables Standards for Reports & Artifacts
For Markdown artifacts, technical documentation, and summaries:
-
Alignment Conventions:
- Left-align text / descriptions:
:--- - Center-align statuses, IDs, counts, dates:
:---: - Right-align monetary amounts, latencies, percentages:
---:
- Left-align text / descriptions:
-
Standard Report Table Structure:
| Módulo / Tabla | Registros | Estado | Latencia (p95) | Observaciones |
| :--- | :---: | :---: | ---: | :--- |
| `categorias` | 123 | ✅ Activo | 12 ms | Acceso según permisos de rol |
| `preguntas_respuestas` | 804 | ✅ Indexado | 48 ms | Embeddings vectoriales al 100% |
| `conversaciones` | 0 | 🧹 Limpio | — | Historial en estado inicial |
- Readability Rules:
- Keep column counts under 6 columns in standard markdown to avoid horizontal squishing.
- Use bold markdown for key metrics and inline code formatting for table names or routes.