a2host/.agents/skills/diagrams-and-data-tables/SKILL.md

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.