diagram-design

Product Introduction

1. Definition: Diagram-design is a comprehensive, open-source library of 29 self-contained HTML and SVG diagram components, designed as a skill/plugin for Claude Code and AI workflows. It is a technical documentation tool that generates clean, editorial-style visualizations.
2. Core Value Proposition: It exists to solve the problem of cluttered, visually inconsistent, and overly complex technical diagrams (like those generated by Mermaid.js) by providing a system for creating professional, maintainable, and brand-aligned visual documentation for code, system architecture, and AI workflows without requiring design software.

Main Features

1. 27 Editorial Diagram Types: The library includes a wide range of specific diagram types such as Architecture, Flowchart, Sequence, State Machine, ERD, Timeline, Swimlane, Quadrant (2x2), Tree, Org Chart, Layer Stack, Venn, Pyramid, Radar, Loop (flywheel), and various data charts (Bar, Line, Gantt, Scatter). Each is a pure HTML/SVG file with no external dependencies or JavaScript.
2. Automated Brand Onboarding: The Claude Code skill can extract a brand's color palette and typography directly from a provided website URL. It fetches the homepage, analyzes the dominant colors and font stack, maps them to semantic roles (paper, ink, accent, muted), performs WCAG AA contrast checks, and writes the tokens to a central style-guide.md file, applying the brand across all diagrams automatically.
3. Self-Contained Export Workflow: Diagrams can be exported to standalone SVG and PNG formats. The /diagram-design:export command extracts the SVG node, injects necessary Google Fonts for portability, and can rasterize to PNG using Playwright (Chromium) for high-resolution output, ideal for embedding in presentations, Figma, or documentation.

Problems Solved

1. Pain Point: Eliminates the time-consuming and inconsistent process of creating technical diagrams, where developers and writers often resort to generic, unaesthetic tools or spend excessive time in design applications like Figma to achieve a professional look that matches their project's branding.
2. Target Audience: Primary users are AI Engineers, Developers, and Technical Writers who need to document Claude Code projects, system architectures, and API workflows. Secondary users include Product Managers and Consultants who require clear, strategic visuals like quadrants and flowcharts for planning and communication.
3. Use Cases: Essential for generating architecture diagrams for a microservices app, creating sequence diagrams for OAuth token refresh flows, visualizing data pipeline steps, mapping organizational structures, planning product roadmaps on an impact/effort quadrant, and documenting state machines for application logic.

Unique Advantages

1. Differentiation: Unlike Mermaid.js (which produces generic, often cluttered diagrams) or manual design in Figma (which is time-intensive), diagram-design offers a curated, opinionated design system focused on editorial clarity. It is integrated directly into the AI coding workflow (Claude Code) and automatically adopts project branding.
2. Key Innovation: Its "progressive disclosure" architecture for the Claude skill ensures only the relevant diagram type reference file is loaded into context, keeping the AI's working memory efficient despite the library's breadth (34+ reference files). The design system enforces strict typographic hierarchy (Instrument Serif, Geist Sans, Geist Mono), a single accent color for focus, and a 4px grid system for all coordinates to ensure visual consistency.

Frequently Asked Questions (FAQ)

1. How do I install the diagram-design skill in Claude Code? You can install it via the plugin marketplace (/plugin marketplace add cathrynlavery/diagram-design) or by cloning the GitHub repository and creating a symlink from ~/.claude/skills/diagram-design to the inner skills/diagram-design directory for full customization.
2. Can I use diagram-design without Claude AI or an AI coding assistant? Yes, the core diagram components are standard HTML and SVG files that can be opened directly in any web browser and edited manually. The library can be used as a standalone design system, though the automated branding and Claude Code integration are key value-adds.
3. What is the license for the diagram-design library and icons? The main code is under the MIT License. It includes stroked icons from Tabler Icons (MIT) and brand silhouettes from Simple Icons (CC0), as detailed in the THIRD_PARTY_LICENSES.md file.
4. How does the brand color extraction and onboarding process work? The skill fetches the target website's HTML, analyzes the CSS to find the <body> background (paper), primary text color (ink), secondary color (muted), and prominent brand/CTA color (accent). It also captures font families for titles and body text, then proposes a token mapping to style-guide.md after validating contrast ratios.
5. What are the "primitive" components in diagram-design? Primitives are reusable visual modifiers: the Annotation primitive adds italic-serif callouts with dashed Bézier leaders; the Sketchy primitive applies an SVG filter for a hand-drawn aesthetic; the Terminal primitive styles diagrams to look like a CLI window; and the Icons primitive provides 55 monochrome IT/cloud icons that inherit the current color scheme.