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

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 or flowchart 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

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:

| 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 |
  1. 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.