Ever asked an AI assistant like Claude Code or Codex to generate a quick architecture diagram, only to be slapped in the face with a generic, eye-searing, neon-purple rounded-box nightmare? 
You know the drill:
Mermaid.js defaults that look like they were rendered in 2005.
30 minutes wasted in Figma just tweaking margins, alignment, and hex codes.- “AI Slop aesthetics” — drop shadows everywhere, terrible line routing, and zero visual hierarchy.
Enter cathrynlavery/diagram-design — a blowing-up open-source GitHub repository (over 33k+ Stars 
) that completely redefines how developers and architects generate visual mental models using AI.
Let’s dive into an architectural breakdown of what makes this repo brilliant, how it works under the hood, and why it belongs in your agentic engineering toolchain! 
What is diagram-design?
Created by Cathryn Lavery (creator, designer, and writer at littlemight.com), diagram-design is an Agent Skill / Plugin built for modern AI coding tools like Claude Code, Codex, Factory Droid, Pi, Kiro, and OpenCode.
Instead of outputting markdown charts or heavy canvas scripts, it instructs your LLM agents to produce 39 publication-ready editorial diagram types in pure, self-contained HTML + SVG.
Core Motto:“No Figma. No generic rounded boxes. No 30-minute color-picking sessions. No Mermaid slop.”
Architectural Core Principles: Why it Looks so Good
As software architects, we evaluate tools based on design constraints and structural opinionatedness. diagram-design wins because of these 4 strict design rules:
┌─────────────────────────┐
│ Target Visual Density │
│ (4 / 10) │
└────────────┬────────────┘
│
┌──────────────────────────┼──────────────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Zero External │ │ 1-2 Accent Focus │ │ Semantic │
│ Dependencies │ │ Rule │ │ Grammars │
│ (Pure HTML+SVG) │ │ (Intentional Ink)│ │ (39 Pure Types) │
└──────────────────┘ └──────────────────┘ └──────────────────┘
1. Zero External Dependencies 
- No JavaScript chart libraries (Chart.js, D3, Recharts) to load or fail at runtime.
- No SVG canvas shadows or filters (
drop-shadoweffects are strictly banned). - Self-Contained Output: Generates flat
.htmlfiles containing inline<svg>and CSS. You can open them in any browser or screenshot them straight into your blog/documentation.
2. The Deletion Principle & Target Density (4/10) 
In software architecture, less is more. Every node and arrow in a diagram must earn its right to exist. The skill enforces a strict visual density score of 4 out of 10 — eliminating noise so readers digest complex topology instantly.
3. The 1–2 Accent Focal Rule
Instead of rainbow-colored nodes, the algorithm restricts bright accent colors to only 1 or 2 high-priority focal points (e.g., an active microservice, a database bottleneck, or a breaking workflow state). The rest of the stack stays neutral (paper, ink, and muted slate).
4. 39 Universal Layout Grammars 
Whether you need to map out a Kubernetes deployment or a distributed transaction saga, diagram-design ships with 39 layout grammars:
| Category | High-Value Diagram Grammars Included |
| System & Cloud | Architecture, High-Level Stack, Deployment Zones, Microservices |
| Data & Storage | ER/Data Model, Database Schema, Medallion Pipeline, Data Flow |
| Logic & Workflows | Flowchart, Sequence, State Machine, Swimlane, Process Map |
| Strategy & Mapping | Wardley Maps , Sankey Flow, Fishbone (Ishikawa), User Journey |
| Structures & Sets | Venn, Layer Stack, Org Chart, Treemap, Dependency Graph |
60-Second Onboarding: Brand Auto-Scraping 
Here is where the magic happens for blog creators and technical writers! 
You don’t need to manually pass Hex codes for your theme. The agent can auto-discover your brand tokens straight from your live website URL!
How the Onboarding Loop Works:
You Agent (Claude / Codex / Pi) Your Website
│ │ │
├────── "onboard diagram-design ───►│ │
│ to https://mysite.com" │ │
│ ├─── HTTP GET / CSS Parse ────►│
│ │◄── Extract Theme Tokens ─────┘
│ │
│ ├── Maps: <body> background ➔ Paper
│ ├── Maps: Primary Text ➔ Ink
│ ├── Maps: CTA Button ➔ Accent Color
│ └── Maps: Body/Code Fonts ➔ Typography
│ │
│◄───── Renders Fidelity Receipt ──┤
│ & Asks for Confirmation │
│ │
├────── "Looks great, apply!" ────►│
│ └── Writes to ~/.diagram-design/profiles/ 
Before saving, it even runs automated WCAG AA contrast checks to guarantee your dark/light modes meet accessibility standards! 
Quick Installation & Hands-On Setup
diagram-design is cross-compatible with almost all modern AI agent frameworks using standard Agent Skill protocols.
1. Claude Code
Bash
2. Codex CLI
Bash
3. Pi Agent
Bash
4. Manual / Local Development (Symlink Setup) 
If you want to modify the design prompt rules locally:
Bash
How to Prompt Your Agent for Best Results 
Once installed, talk to your coding assistant naturally:
- Basic Architecture:
“Draw a system architecture diagram for a Event-Driven Order Processing system using Spring Boot, Kafka, and Postgres.” - Refactoring Existing Mermaid Code:
“Take this messy.mmdsequence diagram and re-render it as a full-editorial Diagram Design HTML.” - Data Engineering Pipelines:
“Create a Medallion Architecture diagram (Bronze -> Silver -> Gold) showing our Spark streaming ingestion pipeline.”
Architecture Verdict & Takeaway 
| Criteria | Traditional Mermaid.js | Figma / Excalidraw | diagram-design Skill |
| AI Native | Yes | Manual | Yes |
| Visual Quality |  Low / Generic |  High |  Editorial Grade |
| Design Effort | Zero | 30+ Minutes | Zero |
| Custom Brand Matching | Hard / Hacky | Manual | Automated in 60s |
| Export Format | Raster / SVG | Vector | Self-Contained HTML+SVG |
Final Word
cathrynlavery/diagram-design is a prime example of Context Engineering done right. By replacing vague general instructions with strict layout constraints, crisp design rules, and automated theme tokenization, it bridges the gap between raw LLM outputs and professional software architecture presentation.
If you produce blog content, write architectural decision records (ADRs), or document complex codebases, this skill is a must-have addition to your developer toolkit! 
Lets try to install this repo in github copilot coding agent and try to create simple UML diagram for our backend springboot java class system.
follow this step religiously
1- Diagram-Design setup.
A:- Clone the repo https://github.com/cathrynlavery/diagram-design.git
B:- Create a folder name as .github and inside that copy the skills folder of the above clone repo in it. Create copilot.instruction.md inside the smae .github folder and paste this code in it.
Repository AI Instruction
Architecture
Treat the repository source code and approved documentation as the source of truth.
Do not invent services, APIs, databases, technologies, dependencies or deployment environments.
Clearly label assumptions and unresolved questions.
Diagram generation
Use the diagram-design Agent Skill for architecture, data-flow, sequence, dependency, deployment, database, process and SDLC diagrams.
Write generated diagrams under, docs/diagrams/.
Use self-contained HTML with embedded SVG.
Prefer static output unless motion is explicitly requested.
Keep diagrams readable and minimize unnecessary nodes.
Include the diagram purpose, scope, assumptions and source files.
Preserve existing branding and terminology.
Do not include credentials, customer data, production endpoints or secrets.
Validation
Validate component names against the repository.
Validate API relationships against controllers, clients and configuration.
Validate database entities against migrations or schema definitions.
Validate deployment components against Docker, Helm or Kubernetes files.
Mark relationships as “unverified” when evidence is insufficient.
C:- Final try to update the settings.json for the vscode so that vscode will be able to get this skills in github copilot chat windows.
“chat.agentSkillsLocations”: {
“.github/skills”: true
},
Now lets try to create a simple UML diagram for the backend system using the belwo given prompt
using diagram design create the uml diagrame for the @file:backend and place it in /backend/uml-diagram folder
Git:- https://github.com/shdhumale/diagram-design.git
No comments:
Post a Comment