niopd-vis-visualizer - SKILL.md Agent Skill

name: niopd-vis-visualizer description: A universal visualization engine supporting Flowcharts, Sequence Diagrams, C4 Architecture, Mindmaps, Timing Diagrams, Entity-Relationship (ER) Diagrams, Gantt Charts, and Freeform Sketches. Intelligently selects between Mermaid, Excalidraw, PlantUML, D2, Markmap, and WaveDrom.

Universal Visualizer Skill (Ultra SOTA)

This skill is the Central Visualization Engine for NioPD. It intelligently selects the best diagramming tool based on user intent and content type, then generates industry-standard visualizations with strict syntax validation and semantic styling.

1. Engine Selection Logic (The "Brain")

Analyze the user's request and content to select the best engine:

Engine	Primary Strength	Use Case
Excalidraw	Creative/Presentation	High-end reports, Pitch decks, UI/UX, hierarchies, "Visual First"
Mermaid	Logic/Workflow	PRD flows, Sequence maps, State diagrams, Quick technical docs
PlantUML	Architecture (C4)	C4 Models (System/Container), Complex Enterprise UML
D2	Modern Clarity	Cloud Architecture, Entity Relationship, complex layouts (`tala`)
Markmap	Rapid Hierarchy	Brainstorming, Taxonomy, Content breakdown
WaveDrom	Timing/Hardware	API Latency, Protocol Handshake, Hardware flows

Selection Heuristics:

"Story/Pitch/Concept" OR "Excalidraw" → Excalidraw
"Architecture/C4/System" → PlantUML (or Mermaid C4 if simple)
"Workflow/Logic/Sequence" → Mermaid
"Brainstorming/Structure" → Markmap
"Timing/Latency" → WaveDrom
"Complex Topology" → D2

2. Mermaid Workflow (Logic & Process)

Reference: mermaid-rules.md

2.1 Diagram Types & Configuration

Choose diagram type based on content:

Type	Best For	Configuration Options
Process Flow (`graph TB/LR`)	Workflows, decision trees, sequential steps	`layout`: "vertical" (TB) or "horizontal" (LR) `style`: "professional"
Circular Flow (`graph TD`)	Cyclic processes, feedback loops	Use curved connection lines
Comparison (`graph TB`)	A vs B analysis, before/after	Parallel subgraphs
Mindmap (`mindmap`)	Hierarchical breakdowns	Radial layout
Sequence (`sequenceDiagram`)	Interactions over time, API calls	`autonumber`
State (`stateDiagram`)	Lifecycle stages, status transitions	State nodes

Configuration Parameters:

Layout: direction (TB/LR/RL/BT), aspect (portrait/landscape).
Detail Level: simple (core steps), standard (balanced), detailed (full annotations).
Style: professional (Semantic colors), minimal (Monochrome), colorful (Vibrant).

2.2 Critical Syntax Rules (Error Prevention)

Always follow these rules to prevent parsing errors:

List Syntax Conflict: [1. Perception] triggers list parser.
- ✅ RIGHT: [1.Perception], [① Perception], [(1) Perception], [Step 1: Perception].
Subgraph Naming: Spaces break rendering.
- ✅ RIGHT: subgraph agent["AI Agent Core"].
Node References: ALWAYS use IDs.
- ✅ RIGHT: A --> B. ❌ WRONG: "Start" --> "End".
Special Characters:
- Quotes: 『』. Parentheses: 「」.

2.3 Semantic Color Scheme (Standard Professional Palette)

Green (#d3f9d8/#2f9e44): Input, perception, start states
Red (#ffe3e3/#c92a2a): Planning, decision points, risks
Purple (#e5dbff/#5f3dc4): Processing, reasoning, AI logic
Orange (#ffe8cc/#d9480f): Actions, tool usage
Blue (#e7f5ff/#1971c2): Metadata, definitions, titles

3. Excalidraw Workflow (Visuals & Presentation)

Reference: excalidraw-rules.md

3.1 Diagram Types & Selection Guide

Type	Use Case	Implementation Strategy
Flowchart	Workflows, Steps	Connect rectangles with arrows (Sticky mode)
Mind Map	Brainstorming, Ideas	Central ellipse with radiating lines
Hierarchy	Org Charts, Structure	Top-down tree structure
Relationship	Dependencies	Connected clusters or shapes
Comparison	A/B Analysis	Two columns (Frames) or side-by-side
Timeline	Roadmaps	Horizontal axis with milestones
Matrix	Strategy/Priority	2x2 Quadrants (Frames)
Freeform	Sketches	Unrestricted placement

3.2 Design Rules & Element Template

Strict Design Rules:

Font: fontFamily: 5 (Excalifont) is MANDATORY.
Text: Replace " with 『』, () with 「」.
Sizes: Title 24-28px, Subtitle 18-20px, Body 14-16px.
Layout: Keep elements within 0-1200 x 0-800.

Element Template (Required Fields):

{
  "id": "unique-id", "type": "rectangle",
  "x": 100, "y": 100, "width": 200, "height": 50,
  "strokeColor": "#1e40af", "backgroundColor": "#dbeafe",
  "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
  "roughness": 1, "opacity": 100, "groupIds": [], "roundness": {"type": 3},
  "seed": 123456789, "version": 1, "isDeleted": false, "boundElements": []
}

3.3 Strict Output Format (Obsidian Compatible)

You MUST strictly follow this structure without modification:

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
%%
## Drawing
```json
{ ... JSON DATA ... }


### 3.4 Auto-Save & User Feedback Workflow
1. **Filename**: Generate meaningful name `[Topic].[Type].md`.
2. **Save**: `write_to_file` to current directory.
3. **Notify User (Strict Template)**:
   ```markdown
   ✅ Excalidraw diagram generated!
   
   📍 Saved to:
   [Filename]
   
   🎨 Design Choice:
   I selected "[Type]" to visualize...
   
   📖 How to View:
   1. Open in Obsidian
   2. Menu -> "Switch to EXCALIDRAW VIEW"

4. Other Engines (Specialized)

4.1 PlantUML (C4 Architecture)

Reference: plantuml-rules.md

Use for: Detailed C4 System/Container diagrams.
Rule: Include C4 URLs (!include .../C4_Context.puml).

4.2 D2 (Complex Layouts)

Reference: d2-rules.md

Use for: Auto-layout of messy graphs (layout: tala).
Rule: Nesting with {}.

4.3 Markmap (Mindmaps)

Reference: markmap-rules.md

Use for: Instant text-to-map.
Rule: Standard Markdown headers # and list items -.

4.4 WaveDrom (Timing)

Reference: wavedrom-rules.md

Use for: Hardware/API Timing.
Rule: Valid JSON signal object.

5. Quality Checklist

Engine Selection: Correct engine chosen for the use case?
Mermaid Syntax: No "number. space" lists? IDs used for links?
Excalidraw Format: Strict Markdown wrapper? fontFamily: 5?
Data Safety: Quotes/Parentheses escaped?
Semantics: Colors match the NioPD standard?