164 lines
6.3 KiB
Markdown
164 lines
6.3 KiB
Markdown
---
|
|
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 `<br/>` 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
|
|
<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)**:
|
|
```html
|
|
<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`
|
|
|
|
### 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.
|