jb/diagram-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add native Pi package support

Browse Source
This commit is contained in:
Daan Balm
2026-08-11 16:15:13 +02:00
parent c5805a0c7f
commit 81cb965267
4 changed files with 122 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+78 -53
View File
@@ -8,7 +8,7 @@
*New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.* *New in 2.0 — the Loop: flywheels with a shared-memory hub. The dashed lines are the write-backs.*
27 types. One Claude Code skill. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram. 27 types. One agent skill for Claude Code, Codex, and Pi. Your brand in 60 seconds — the skill reads your website and maps colors + fonts to every diagram.
No Figma. No generic rounded boxes. No 30-minute color-picking sessions. No Figma. No generic rounded boxes. No 30-minute color-picking sessions.
@@ -87,19 +87,13 @@ All 27 diagrams ship in three variants: minimal light, minimal dark, and full-ed
## Install ## Install
**Pi:**
```bash ```bash
# Clone the repo somewhere, then symlink the inner skill into Claude Code's skills dir pi install https://github.com/cathrynlavery/diagram-design
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
``` ```
The real skill lives at `skills/diagram-design/` inside the repo (so the same tree works as a Claude Code plugin, a Codex plugin, and a standalone skill). The symlink points Claude Code at that inner directory. Run `/reload` in an open Pi session. The skill activates automatically for diagram requests; use `/skill:diagram-design` to invoke it explicitly. Pi also loads the `/export-diagram` prompt template.
Restart Claude Code. The skill registers as `diagram-design` and activates whenever you ask Claude to make a diagram.
### Alternative: install as a plugin
Quicker to install — but the skill lives in the plugin cache, so edits to `references/style-guide.md` don't survive plugin updates. Pick this if you just want to try it out; use the clone route above if you plan to customize the style guide by hand.
**Claude Code:** **Claude Code:**
@@ -116,6 +110,22 @@ Quicker to install — but the skill lives in the plugin cache, so edits to `ref
npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design
``` ```
### Editable install
Managed installs are convenient, but changes to `references/style-guide.md` may be replaced by package updates. Clone the repo and install the local path if you plan to customize the style guide:
```bash
git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
# Pi: register the checkout as a local package
pi install ~/code/diagram-design
# Claude Code: symlink the inner skill
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design
```
The shared skill lives at `skills/diagram-design/`. Pi discovers it through the repo's standard `skills/` package directory; Claude Code, Codex, and other Agent Skills-compatible tools use the same files.
--- ---
## Onboarding — make it look like *your* brand ## Onboarding — make it look like *your* brand
@@ -128,7 +138,7 @@ Out of the box, diagrams render in a clean **jet-black + atomic-tangerine** pale
``` ```
You: "onboard diagram-design to https://yoursite.com" You: "onboard diagram-design to https://yoursite.com"
Claude: → fetches the homepage Agent: → fetches the homepage
→ extracts the dominant palette + font stack → extracts the dominant palette + font stack
→ maps detected values to semantic roles: → maps detected values to semantic roles:
paper, ink, muted, accent, link paper, ink, muted, accent, link
@@ -173,29 +183,40 @@ See [`skills/diagram-design/references/onboarding.md`](skills/diagram-design/ref
## Quickstart ## Quickstart
```bash ```bash
# Open the gallery to see all 27 diagrams # From a cloned checkout, open the gallery to see all 27 diagrams
open ~/.claude/skills/diagram-design/assets/index.html open skills/diagram-design/assets/index.html # macOS
xdg-open skills/diagram-design/assets/index.html # Linux
# In Claude Code, just ask: # In Claude Code, Codex, or Pi, ask:
# "Make me an architecture diagram of my app: frontend, backend, database, Redis cache." # "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
# "I need a quadrant showing Q2 projects by impact vs effort." # "I need a quadrant showing Q2 projects by impact vs effort."
# "Give me a sequence of a bearer call with token refresh on 401." # "Give me a sequence of a bearer call with token refresh on 401."
# (branching refresh uses the ALT combined-fragment grammar in type-sequence.md; # (branching refresh uses the ALT combined-fragment grammar in type-sequence.md;
# see assets/example-sequence-oauth.html — not a full authorize-code handshake) # see skills/diagram-design/assets/example-sequence-oauth.html — not a full authorize-code handshake)
``` ```
Claude will pick the right type, build the HTML, and save it. You can also start from a template directly: Your agent will pick the right type, build the HTML, and save it. You can also start from a template directly:
```bash ```bash
cp assets/template.html my-diagram.html # minimal light cp skills/diagram-design/assets/template.html my-diagram.html # minimal light
cp assets/template-full.html my-diagram.html # editorial with summary cards cp skills/diagram-design/assets/template-full.html my-diagram.html # editorial with summary cards
``` ```
--- ---
## Export to PNG / SVG ## Export to PNG / SVG
Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command: Diagrams ship as self-contained HTML, but you can export the diagram itself for Figma, slides, or social cards. Use the slash command for your agent:
**Pi:**
```
/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3
```
**Claude Code:**
``` ```
/diagram-design:export path/to/diagram.html /diagram-design:export path/to/diagram.html
@@ -219,42 +240,46 @@ Both formats are diagram-only — editorial cards and headers from `-full` varia
## Architecture ## Architecture
Progressive disclosure. `SKILL.md` is a lean index — it tells Claude how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant. Progressive disclosure. `SKILL.md` is a lean index — it tells the agent how to pick a type and where to look for detail. Every type lives in its own reference file, loaded only when relevant.
``` ```
diagram-design/ diagram-design/
├── SKILL.md — top-level: philosophy, selection guide, checklist ├── prompts/
├── references/ — loaded only when a type or primitive is chosen │ └── export-diagram.md — Pi `/export-diagram` prompt template
│ ├── style-guide.md — single source of truth for colors + fonts ├── skills/
│ ├── onboarding.md — the URL-to-tokens flow │ └── diagram-design/
│ ├── type-architecture.md │ ├── SKILL.md — philosophy, selection guide, checklist
│ ├── type-flowchart.md │ ├── references/ — loaded only when a type or primitive is chosen
│ ├── type-sequence.md │ │ ├── style-guide.md — single source of truth for colors + fonts
│ ├── type-state.md │ │ ├── onboarding.md — the URL-to-tokens flow
│ ├── type-er.md │ │ ├── type-architecture.md
│ ├── type-timeline.md │ │ ├── type-flowchart.md
│ ├── type-swimlane.md │ │ ├── type-sequence.md
│ ├── type-quadrant.md │ │ ├── type-state.md
│ ├── type-nested.md │ │ ├── type-er.md
│ ├── type-tree.md │ │ ├── type-timeline.md
│ ├── type-org-chart.md │ │ ├── type-swimlane.md
│ ├── type-layers.md │ │ ├── type-quadrant.md
│ ├── type-venn.md │ │ ├── type-nested.md
│ ├── type-pyramid.md │ │ ├── type-tree.md
│ ├── primitive-annotation.md — italic-serif editorial callouts │ │ ├── type-org-chart.md
│ ├── primitive-sketchy.md — hand-drawn SVG filter variant │ │ ├── type-layers.md
│ └── primitive-terminal.md — charcoal-black CLI-window variant │ │ ├── type-venn.md
├── assets/ │ │ ├── type-pyramid.md
│ ├── index.html — live gallery, tabbed │ │ ├── primitive-annotation.md
│ ├── template*.html — scaffolds for new diagrams │ │ ├── primitive-sketchy.md
│ ├── example-<type>.html — 3 variants × 27 types │ │ └── primitive-terminal.md
│ ├── example-loop-terminal.html — terminal-variant flagship │ └── assets/
│ ├── example-quadrant-consultant.html — consultant-special 2×2 scenario matrix │ ├── index.html — live gallery, tabbed
│ └── example-sequence-oauth*.html — sequence special: bearer + ALT refresh │ ├── template*.html — scaffolds for new diagrams
└── docs/screenshots/ — the images in this README │ ├── example-<type>.html — 3 variants × 27 types
│ ├── example-loop-terminal.html
│ ├── example-quadrant-consultant.html
│ └── example-sequence-oauth*.html
└── docs/screenshots/ — images used in this README
``` ```
This keeps Claude's working context tight (only load what you need) and makes the skill easy to extend — drop a new `type-<name>.md` and wire it into the selection guide. The skill ships with 34 reference files covering every diagram type, primitive, and utility. This keeps the agent's working context tight (only load what you need) and makes the skill easy to extend — drop a new `type-<name>.md` and wire it into the selection guide. The skill ships with 34 reference files covering every diagram type, primitive, and utility.
### Contributing / skin lint ### Contributing / skin lint
@@ -265,7 +290,7 @@ The repository-wide check `python3 scripts/lint-skin.py --all --baseline` must s
The top-level `SKILL.md` is always in context. Everything else is pulled in only when relevant — this is what keeps the skill fast even with 34 reference files. The top-level `SKILL.md` is always in context. Everything else is pulled in only when relevant — this is what keeps the skill fast even with 34 reference files.
| You ask for… | Claude loads | | You ask for… | Agent loads |
|---|---| |---|---|
| "Make me a flowchart" | `SKILL.md` + `references/type-flowchart.md` | | "Make me a flowchart" | `SKILL.md` + `references/type-flowchart.md` |
| "Build an architecture diagram" | `SKILL.md` + `references/type-architecture.md` | | "Build an architecture diagram" | `SKILL.md` + `references/type-architecture.md` |
@@ -275,7 +300,7 @@ The top-level `SKILL.md` is always in context. Everything else is pulled in only
| "Give me a terminal / CLI-window version" | `SKILL.md` + `references/primitive-terminal.md` | | "Give me a terminal / CLI-window version" | `SKILL.md` + `references/primitive-terminal.md` |
| Routine diagram-making (any of the 27 diagrams) | Only `SKILL.md` + that one type's reference | | Routine diagram-making (any of the 27 diagrams) | Only `SKILL.md` + that one type's reference |
No matter how many types exist, Claude only reads the one you need. Add a new type tomorrow and nothing else changes. No matter how many types exist, the agent only reads the one you need. Add a new type tomorrow and nothing else changes.
--- ---
prompts/export-diagram.md
+30
View File
@@ -0,0 +1,30 @@
---
description: Export a diagram-design HTML file to SVG and PNG
argument-hint: "<html-file> [--svg-only|--png-only] [--scale=N] [--output=<path>]"
---
Export diagram HTML at `$1` to `.svg` or `.png`, following `skills/diagram-design/references/export.md` from installed diagram-design package. Read that reference first; treat it as source of truth.
Full argument string: `$ARGUMENTS`
## Defaults
- Produce both `.svg` and `.png` next to source (for example, `diagram.html` → `diagram.svg` + `diagram.png`).
- Render PNG at `device_scale_factor=2`.
## Flags
- `--svg-only` — emit SVG only. Skip Playwright.
- `--png-only` — emit PNG only.
- `--scale=1`, `--scale=2`, or `--scale=3` — override PNG device scale factor.
- `--output=<path>` — override output base path; append format extension.
## Required behavior
1. No source path → ask user which `.html` file to export. Do not guess.
2. Source is `assets/index.html` → refuse; ask for specific diagram file.
3. Source lacks `<svg>` → refuse; write nothing.
4. PNG requested without Playwright → show install instruction from reference verbatim; stop. Do not auto-install.
5. `--scale` outside {1, 2, 3} → reject.
After export, report output paths plus sizes.
skills/diagram-design/SKILL.md
+1 -1
View File
@@ -192,7 +192,7 @@ Universal building blocks. Type-specialized primitives (lifeline, activation bar
- Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md) - Editorial callouts → [primitive-annotation.md](references/primitive-annotation.md)
- Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md) - Hand-drawn variant → [primitive-sketchy.md](references/primitive-sketchy.md)
- Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](../assets/icons.html). - Icon set (laptop, server, DB, K8s, Docker, AWS, …) → [primitive-icons.md](references/primitive-icons.md). Browse the gallery at [`assets/icons.html`](assets/icons.html).
- Terminal / CLI-window variant → [primitive-terminal.md](references/primitive-terminal.md) - Terminal / CLI-window variant → [primitive-terminal.md](references/primitive-terminal.md)
### Background ### Background
skills/diagram-design/references/onboarding.md
+13 -6
View File
@@ -7,7 +7,7 @@ Takes about 60 seconds.
Three source methods are supported. Jump to the relevant section: Three source methods are supported. Jump to the relevant section:
- [§ URL](#url) — fetch a live website - [§ URL](#url) — fetch a live website
- [§ Skill](#skill) — read an installed Claude Code skill that carries design tokens - [§ Skill](#skill) — read an installed Agent Skill that carries design tokens
- [§ Folder](#folder) — read a local design-system directory (CSS, JSON, Markdown) - [§ Folder](#folder) — read a local design-system directory (CSS, JSON, Markdown)
--- ---
@@ -128,7 +128,7 @@ Write the new tokens to `style-guide.md`. Suggest running the `/regenerate-examp
After onboarding, the user should: After onboarding, the user should:
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 26 types. 1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 27 types.
2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`). 2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
--- ---
@@ -144,7 +144,7 @@ After onboarding, the user should:
## § Skill ## § Skill
Extract tokens from an installed Claude Code skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill). Extract tokens from an installed Agent Skill that carries its own design system (e.g. a `brand-design` or `ui-kit` skill).
### Invocation ### Invocation
@@ -154,13 +154,20 @@ Or the gate offers this as option (b) and the user names the skill.
### Step 1 — locate the skill ### Step 1 — locate the skill
Search for the skill in order: Use the installed-skill location exposed by the current agent when available. Otherwise search locations for the active harness:
**Pi:**
1. `~/.pi/agent/skills/<skill-name>/` and `~/.agents/skills/<skill-name>/` (user installs)
2. `.pi/skills/<skill-name>/` and `.agents/skills/<skill-name>/` from the current directory through the repo root (project installs)
3. Package paths listed in `~/.pi/agent/settings.json` or `.pi/settings.json`; managed packages live under `~/.pi/agent/git/`, `~/.pi/agent/npm/`, `.pi/git/`, or `.pi/npm/`
**Claude Code:**
1. `~/.claude/skills/<skill-name>/` (user install) 1. `~/.claude/skills/<skill-name>/` (user install)
2. `.claude/skills/<skill-name>/` (project install) 2. `.claude/skills/<skill-name>/` (project install)
3. Any path the user provides explicitly
If not found, ask the user to confirm the skill name or provide the path. Finally, check any path the user provides explicitly. If the skill is still not found, ask the user to confirm the name or provide its path.
### Step 2 — read token sources ### Step 2 — read token sources