diagram-design
Skill8 starsChanged 3 days agoMITView on GitHub
use this when creating explainer diagrams (architecture, sequence, process, cards for posts) as HTML/SVG/PNG so they are branded and not ranking-dashboard slop
48 other projects use a version of this.
Adopted by
Most recently taken up by
- sugatoray/aiskillstheir own version, first seen Nov 15, 2026
- baekenough/oh-my-customcodetheir own version, first seen Nov 14, 2026
- EricGrill/agents-skills-pluginstheir own version, first seen Nov 8, 2026
- apattichis/agentic-research-toolkittheir own version, first seen Nov 8, 2026
- hamzzaqureshi/gravidextheir own version, first seen Nov 8, 2026
- tsukhani/jclawtheir own version, first seen Nov 5, 2026
Used with
Projects with it also use pretty-mermaid, transitions-dev and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
drafaelSkillpretty-mermaid
Render beautiful Mermaid diagrams as SVG or ASCII art using the beautiful-mermaid library. Supports 15+ themes, 5 diagram types (flowchart, sequence, state, class, ER), and ultra-fast rendering.
Also in 3 projects that use this
AnasX7Skilltransitions-dev
Production-ready CSS transitions for web apps. Use when implementing notification badges, dropdowns, modals, panel reveals, page transitions, card resizes, number pop-ins, text swaps, icon swaps, success checks, avatar group hovers, error state shakes, search/input clear, skeleton loaders, shimmer text, sliding tabs, tooltips, staggered text reveals, card hover tilt, plus-to-menu morph, accordions, toasts, like buttons, learn-more hovers, checkbox checks, spinning counters, toggles, AI thinking states, reasoning streams, streaming text, matrix dot loaders, or banner stacking. Triggers on "add a transition", "animate the dropdown", "make the modal open smoothly", "swap icon", "page slide", "stagger animation", "open / close transition", "make it animate", "fade between", "success animation", "form error", "shake on invalid", "hover lift", "avatar stack hover", "clear the search", "skeleton loader", "loading shimmer", "shimmer text", "sliding tabs", "segmented control", "tooltip", "reveal text", "tilt card", "3D hover tilt", "cursor glare", "plus to menu", "FAB morph", "accordion", "collapsible", "expand / collapse", "disclosure", "toast", "snackbar", "like button", "heart animation", "learn more arrow", "checkbox", "check animation", "spinning counter", "odometer", "slot machine digits", "toggle", "switch", "thinking states", "AI status line", "agent reasoning", "reasoning stream", "streaming text", "stream words in", "matrix loader", "dot loader", "banner stack", "stacked toasts". Also "motion tokens", "scan for ad-hoc transitions", "replace hardcoded durations with motion tokens", "tokenize my animations", and the commands transitions reveal, transitions review, transitions apply, transitions refine.
Also in 3 projects that use this
PydanticSkilli-have-adhd
Shape every response for an ADHD reader who reviews the work but does not do the coding — the agent does. Use whenever responding to ANY message — coding, debugging, planning, casual. Lead with the result or the decision. Surface anything needing the user's input as a structured question, never buried in prose they'll skim past. No preamble, no recap, no closers. State errors matter-of-factly. Make finished work visible. Trigger even on casual messages and even when brevity wasn't requested.
Also in 4 projects that use this
HK-hubSkilloverdrive
Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary.
Also in 3 projects that use this
HK-hubSkilldelight
Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.
Also in 3 projects that use this
cal1888Skillpick-ui-library
Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.
Also in 3 projects that use this
Other versions48 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 48
- cathrynlavery/diagram-design★ 67ksame name
- kdlbs/kandev★ 1.1ksame name
- chenjackle45/html-visualizer★ 95same name
- microsoft/devsquad-copilot★ 50same name
- baekenough/oh-my-customcode★ 42same name
- tsukhani/jclaw★ 42same name
- spmtitsolution/OpenBA-Kit★ 38same name
- Fioooooooo/FylloCode★ 29same name
- EricGrill/agents-skills-plugins★ 21same name
- ivanrvpereira/.agents★ 19same name
38 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository28 other files it gives its agents.
- whetstone-signalSkill
- design-a-grok-botSkill
- make-bot-uiSkill
- overheard-setupSkill
- overheardSkill
- routine-healthcheckSkill
- transcript-healthcheckSkill
- design-taste-frontendSkill
- motion-pickerSkill
- redesign-existing-projectsSkill
- engineering-playbookSkill
- show-meSkill
- chatgpt-images-browser-playbookSkill
- aeo-geo-siteSkill
- ai-citation-sourcesSkill
- ai-search-gap-loopSkill
- exact-match-intent-seoSkill
- markdown-twinSkill
- shorts-reframeSkill
- coachSkill
- draftSkill
- no-ai-slopSkill
- outlineSkill
- social-copywritingSkill
- source-checkSkill
- top-editSkill
- x-articleSkill
- youtube-niche-reportSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 45 edited versions we read keep these.
4
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Write the caption first: one sentence the diagram proves.
- Distinctive: line 25
Every box gets a short label and, if needed, a few words on what it does.
- Distinctive: line 30
Remove anything that adds ink but no information: background textures, 3D, icons that repeat the label, gradients.
- Distinctive: line 56
Follow the motion-picker rules: one moment on the page, and for the recording, short moving clips joined with fades, no held still, no …
“Common” is measured: kept by at least 6 in 10 of the 45 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagram design
Make one diagram that teaches one thing: architecture, a sequence, a process, a loop, a layer stack, or a still card for a post. Output is a self-contained HTML file with inline SVG, exported to PNG when it's going on social or into an ad. Works on its own; if Cathryn Lavery's diagram pack is installed, use its type references for layout detail.
Should this be a diagram?
Draw only when space carries meaning: order, flow, containment, or connection. If a short paragraph or a small table says it as well, write that instead. Never draw a one-box "diagram".
Plan before drawing
- Write the caption first: one sentence the diagram proves. If you can't, you don't know what to draw yet.
- Pick the type that matches the relationship: flow (process, pipeline), time (sequence, timeline), structure (layers, nesting, tree), or cycle (loop). One level of detail per diagram; zoom levels go in separate diagrams.
- List the nodes. Merge any two that always appear together. Past about nine nodes or twelve arrows, split into an overview and a detail.
- Get the brand: colors, fonts, and spacing from the live site or the user's saved profile. Ask once if neither exists. Never ship a default palette into a branded project.
Drawing rules
- Every box gets a short label and, if needed, a few words on what it does. Every arrow has a direction; label it when the relationship isn't obvious.
- One accent color for the one or two nodes the caption is about. Everything else stays neutral.
- Borders, not shadows. Flat fills. Text large enough to read on a phone at post size.
- Align to a grid. Even spacing. Lines don't cross unless they must.
- A title that says what and what scope. A legend only when shapes or colors carry meaning, as a single strip at the bottom.
- Remove anything that adds ink but no information: background textures, 3D, icons that repeat the label, gradients.
Never ship
- Ranking dashboards, two-column scorecards, or three equal summary cards as the default answer.
- Dark background with neon cyan or purple glow.
- An accent on every "important" node.
- Identical boxes for things that are different kinds (a person, a service, a database).
- Mermaid's auto-layout pasted as a final design. Mermaid is fine for drafts and inside PRs.
Social and ad stills
1200×675 (16:9) unless the platform asks for something else. One idea, big type, no legend. Run the caption through no-ai-slop.
Output
- A single HTML file with inline SVG and CSS, no external requests.
- SVG has a
<title>and<desc>for screen readers. - PNG export at 2x for posts and ads. Open the PNG and look at it before handing it over. That still is the default. Do not commit a rendered png, or any gif, mp4, or webm.
Optional line-draw clip
Skip this unless the user asks for motion. The PNG stays the default path.
- Animate the inline SVG as a line-draw. Prefer CSS so the timing matches a preset from motion-picker exactly. calm is the default. Measure each path (SVGGeometryElement.getTotalLength() works) and store the length in a custom property. Set
stroke-dasharrayandstroke-dashoffsetto that length, then animatestroke-dashoffsetto 0 over the preset duration and cubic-bezier. Whenprefers-reduced-motionis reduce, do not animate; leave the stroke fully drawn and ship the PNG only. - Vivus is the other option (readme). Its duration option counts frames, not milliseconds, so do not drop the preset's millisecond number straight into that option. Convert with frames ≈ milliseconds ÷ 1000 × the capture frame rate, and write down the frame count you passed. At 60fps the calm row is about 25 frames. Vivus follows strokes on path elements and does not draw a fill. Convert real outlines to paths, or stay with the CSS method.
- Follow the motion-picker rules: one moment on the page, and for the recording, short moving clips joined with fades, no held still, no zoom-in, and no push-in. The timing numbers stay the presets.
- Record a short clip with a headless browser, as webm or mp4. Keep that file outside git, along with any gif or rendered png.
@media (prefers-reduced-motion: no-preference) {
.draw {
stroke-dasharray: var(--len);
stroke-dashoffset: var(--len);
animation: draw 420ms cubic-bezier(0.33, 0, 0.2, 1) forwards;
}
}
@keyframes draw {
to { stroke-dashoffset: 0; }
}The 420ms curve is the calm row. If you switch preset, copy the new row from motion-picker. Do not invent a third duration.
Inspired by
- Cathryn Lavery, diagram-design (MIT). Does well: "deletion is the best move", one or two focal accents, a per-type complexity budget, and a style-guide gate before drawing. Missing: about 580 lines plus a required reference pack, so the skill cannot run without installing it first.
- C4 model, Notation (CC BY 4.0). Does well: every diagram gets a title with type and scope, a key, and labeled elements and relationships, so it stands alone. Missing: covers software architecture only and leaves visual style open.
- Edward Tufte's chartjunk idea, via Wikipedia. Does well: names decoration that adds ink without information. Missing: written about data graphics, with no steps for building a schematic.
What this version adds
- Standalone: works without the upstream pack, and uses it when present.
- Caption-first planning and a "should this be a diagram?" test.
- Dani's never-ship list, social still sizes, and accessible SVG plus a look-at-the-PNG check.
- An optional line-draw clip (CSS stroke offset, or Vivus) timed by the motion-picker presets. The PNG stays the default. The clip stays out of git.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

