--- name: diagrams-and-data-tables description: >- 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 `
` or raw tags where Mermaid may parse them incorrectly. - **Direction & Clean Layout**: Use `flowchart TD` (top-down) for hierarchical flows or `flowchart LR` (left-to-right) for sequential pipelines. ### 2. Common Diagram Patterns #### A. Sequence Diagram: WebSocket Client-Server Flow ```mermaid 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 ```mermaid 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) ```mermaid 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**: ```html
``` - **Institutional Headers (SENA Palette)**: ```html ``` - **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` ### 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` - **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] truncate` with `title={val}` on hover to prevent column blowout. ### 3. Responsive Table Adaptations (Mobile-First) - **Container Scroll**: Always wrap tables in `overflow-x-auto custom-scrollbar` so 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: 1. **Alignment Conventions**: - Left-align text / descriptions: `:---` - Center-align statuses, IDs, counts, dates: `:---:` - Right-align monetary amounts, latencies, percentages: `---:` 2. **Standard Report Table Structure**: ```markdown | 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 | ``` 3. **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.
ID Nombre