The Problem

Design teams waste time converting generic diagram templates into brand‑compliant visuals. Existing tools (Figma, Mermaid) either require manual styling or produce rounded‑box graphics that clash with a site’s visual language. The result is inconsistent documentation and extra engineering effort.

What This Does

diagram‑design ships 27 editorial‑style diagram types as pure HTML + SVG files. Each type is provided in three variants (light, dark, full‑editorial) and can be opened directly in a browser—no build step, no JavaScript, no external assets. The skill lives under skills/diagram‑design/ and its public entry point is skills/diagram‑design/assets/index.html. Supporting scripts in scripts/ generate the SVG icon library (scripts/build-icons.py) and perform linting/fix‑encoding tasks, but they are not required for runtime rendering.

How It Is Wired

  1. Entry point – A user (or Claude Code) loads skills/diagram‑design/assets/index.html. The HTML references local SVG files located in the same folder hierarchy, e.g., example‑architecture.html → <svg> elements that embed icons from scripts/vendor/icons/….
  2. Static asset serving – No server‑side code runs; the browser reads the HTML and SVG files from the repository checkout.
  3. Icon generation – scripts/build-icons.py pulls remote icon sets (via requests.get) and writes them into scripts/vendor/icons/. This script is the only place the code makes outbound network calls; it has no timeout (see health issue).
  4. Tooling – scripts/fix-mojibake.py and scripts/lint-skin.py operate on the SVG assets locally; they do not import or depend on each other. The import graph shows three Python modules with zero import edges, confirming complete isolation.
  5. No runtime side‑effects – Rendering the HTML does not touch a database, external services, or the file system beyond the static reads.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/diagram-design
cd diagram-design

# Open a diagram in a browser (example)
open skills/diagram-design/assets/example-architecture.html
# or on Linux/macOS:
xdg-open skills/diagram-design/assets/example-architecture.html

No build tools, package managers, or environment variables are required. To regenerate the icon set (optional):

python3 scripts/build-icons.py   # note: see Code Health & Issues for a required fix

Real‑World Use

A SaaS product can embed the pre‑styled HTML snippets directly into its help centre or marketing site. For example, a CI pipeline could copy the desired example‑flowchart.html into a static site generator’s assets folder, guaranteeing brand‑consistent diagrams without a design hand‑off.

# Example CI step (pseudo‑code)
- name: Deploy diagrams
  run: |
    cp skills/diagram-design/assets/example-flowchart.html public/diagrams/

Code Health & Issues

  • Medium – Missing request timeout – scripts/build-icons.py makes outbound HTTP calls without a timeout= argument, risking hangs if a remote host stalls. The static analysis recommends adding a timeout or using a pre‑configured requests.Session.
  • CI/CD – No CI configuration (.github/, Jenkinsfile, etc.) is present, so automated testing or linting is not enforced.
  • Tests – One test file exists, but coverage is unclear; additional unit tests would improve confidence.
  • License – LICENSE is included, satisfying legal distribution requirements.
  • Secrets – No committed secrets were detected.

The Bottom Line

diagram‑design delivers ready‑to‑use, brand‑consistent diagrams with minimal friction: just clone and open HTML files. It is well‑structured for static consumption, but the supporting Python scripts lack robustness (missing timeout) and the repo has no CI pipeline or extensive test suite. It is suitable for teams that need quick, high‑quality diagrams and are comfortable handling the minor tooling gaps themselves.