agentleFS
humanist96humanist96/deck-design-pack/.claude/skills/diagram-design/SKILL.md

diagram-design

Skill0 starsChanged 2 months agoMITView on GitHub

Diagram design reference library (14 types — architecture, flowchart, sequence, state, ER, timeline, swimlane, quadrant, nested, tree, org chart, layers, venn, pyramid). In ppt-master this is consumed by the Executor when hand-authoring diagram-type SVG pages — it is NOT a standalone HTML generator here. Read for deep per-type layout conventions.

48 other projects use a version of this, 38 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use pretty-mermaid, transitions-dev and 10 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.
  • drafaelSkill

    pretty-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

  • AnasX7Skill

    transitions-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

  • PydanticSkill

    i-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-hubSkill

    overdrive

    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

  • AnasX7Skill

    design-taste-frontend

    Anti-slop frontend skill for landing pages, portfolios, and redesigns. The agent reads the brief, infers the right design direction, and ships interfaces that do not look templated. Real design systems when applicable, audit-first on redesigns, strict pre-flight check.

    Also in 11 projects that use this

  • HK-hubSkill

    delight

    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

  • +2 more from AnasX7

The file

We split this skill into the rules it gives an agent

9 rules. 6 are common, 3 are distinctive, and 0 are very specific to this project.

  • 6

    Common

    Most of the 45 edited versions we read keep these.

  • 3

    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
  1. Common:

    Every node represents a distinct idea.

    line 41
  2. Common:

    Every connection carries information.

    line 42
  3. Common:

    Use for any of the 14 diagram types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.

    line 52
  4. Common:

    Before drawing, ask: *Would the reader learn more from this than from a well-written paragraph?* If no, don't draw.

    line 60
  5. Common:

    If a 3-column table communicates the same thing, pick the table.

    line 86
  6. Distinctive:

    If you're combining two types, pick the dominant axis — don't hybridize grammars.

    line 87
  7. Common:

    If you're past the complexity budget (§7), split into an overview + detail.

    line 88
  8. Distinctive:

    If you exceed, split into two diagrams (overview + detail).

    line 154
  9. Distinctive:

    Run before producing any diagram.

    line 160

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Diagram Design

ppt-master integration note: This skill is vendored as a reference library. In this repo, diagram slides are hand-authored by ppt-master's Executor as SVG pages in svg_output/ — not emitted as standalone HTML. Do NOT run the URL onboarding flow (references/onboarding.md) or the upstream style-guide gate; colors, fonts, and icons always come from the project's spec_lock.md, and the SVG must obey ppt-master's technical constraints (.claude/skills/ppt-master/references/shared-standards.md). The guidance below is upstream context — read it for per-type layout conventions, node/edge discipline, and complexity budgets, then author the page per ppt-master SKILL.md Step 6.

The upstream onboarding / one-time-setup / standalone-HTML-export sections (§0 style-guide gate, §5 Design System skinning, §6 HTML-skin SVG primitives, §7 page layout, §8 summary cards, §10 templates & variants, §11 HTML output) are preserved verbatim in references/diagram-onboarding-legacy.md — upstream provenance record only, never executed in ppt-master.

Fourteen diagram types. One shared design system, complexity budget, and taste gate. Type-specific conventions live in references/ and are loaded only when you pick a type.


1. Philosophy

The highest-quality move is usually deletion.

From .impeccable.md: "Confident restraint. Earn every element. One color accent, two families, a small spacing vocabulary. If removing it wouldn't hurt the page, remove it."

Applied to schematics:

  • Every node represents a distinct idea. Two nodes that always travel together are one node.
  • Every connection carries information. If the relationship is obvious from layout, remove the line.
  • Coral is editorial, not a flag. 1–2 focal nodes per diagram. Using it on 5 nodes erases the signal.
  • The schematic isn't done when everything is added. It's done when nothing can be removed.

Target density: 4/10. Enough to be technically complete. Not so dense it needs a guide. Above 9 nodes, it's probably two diagrams.


2. When to Use

Use for any of the 14 diagram types (§3) when a reader will learn more from a visual than from prose, a table, or a bulleted list.

Don't use for:

  • Quick unicode diagrams → use wiretext.
  • Lists of things → table or bullets.
  • Simple before/after → table.
  • One-shape "diagrams" → just write the sentence.

Before drawing, ask: Would the reader learn more from this than from a well-written paragraph? If no, don't draw.


3. Diagram Types

Selection guide

If you're showing…UseReference
Components + connections in a systemArchitecturetype-architecture.md
Decision logic with branchesFlowcharttype-flowchart.md
Time-ordered messages between actorsSequencetype-sequence.md
States + transitions + guardsState machinetype-state.md
Entities + fields + relationshipsER / data modeltype-er.md
Events positioned in timeTimelinetype-timeline.md
Cross-functional process with handoffsSwimlanetype-swimlane.md
Two-axis positioning / prioritizationQuadranttype-quadrant.md
Hierarchy through containment / scopeNestedtype-nested.md
Parent → children relationshipsTreetype-tree.md
Human/agent/team ownership, reporting, routing, escalationOrg charttype-org-chart.md
Stacked abstraction levelsLayer stacktype-layers.md
Overlap between setsVenntype-venn.md
Ranked hierarchy or conversion drop-offPyramid / funneltype-pyramid.md

Rules of thumb:

  • If a 3-column table communicates the same thing, pick the table.
  • If you're combining two types, pick the dominant axis — don't hybridize grammars.
  • If you're past the complexity budget (§7), split into an overview + detail.

Always load the relevant references/type-*.md before drawing — it contains layout conventions, anti-patterns, and example files for that type.


4. Universal Anti-patterns

These mark "AI slop" schematics of any type:

Anti-patternWhy it fails
Dark mode + cyan/purple glowLooks "technical" without design decisions
JetBrains Mono as blanket "dev" fontMono is for technical content — ports, commands, URLs. Names go in Geist sans.
Identical boxes for every nodeErases hierarchy
Legend floating inside the diagram areaCollides with nodes
Arrow labels with no masking rectBleeds through the line
Vertical writing-mode text on arrowsUnreadable
3 equal-width summary cards as defaultGeneric grid — vary widths
Shadow on any elementShadows are out. Borders are in.
rounded-2xl on boxesMax radius 6–10px or none
Coral on every "important" nodeCoral is 1–2 editorial accents, not a signaling system

Type-specific anti-patterns live in each references/type-*.md.


7. Layout & Spacing

4px grid

All values — font sizes, padding, node dimensions, gaps, x/y coords — divisible by 4. Non-negotiable.

CategoryAllowed values
Font sizes8, 12, 16, 20, 24, 28, 32, 40
Node width / height80, 96, 112, 120, 128, 140, 144, 160, 180, 200, 240, 320
x / y coordinatesmultiples of 4
Gap between nodes20, 24, 32, 40, 48
Padding inside boxes8, 12, 16
Border radius4, 6, 8

Exempt: stroke widths (0.8, 1, 1.2), opacity values, and the 22×22 dot-pattern.

Quick check: if a coordinate ends in 1, 2, 3, 5, 6, 7, 9 — fix it.

Complexity budget (per diagram)

LimitRule
Max nodes9
Max arrows / transitions12
Max coral elements2
Max lifelines (sequence)5
Max lanes (swimlane)5
Max items (quadrant)12
Max entities (ER)8
Max nesting levels (nested)6
Max tree depth4
Max org chart depth4
Max org chart nodes12
Max layers (layer stack)6
Max circles (venn)3
Max layers (pyramid)6
Max annotation callouts2

If you exceed, split into two diagrams (overview + detail).


9. Pre-Output Checklist (Taste Gate)

Run before producing any diagram.

Type fit:

  • Right type for what I'm showing? (§3 selection guide)
  • Would a table / paragraph do the same job? (If yes — don't draw.)
  • Loaded the matching references/type-*.md?

Remove test:

  • Can I remove any node? (Would a reader still understand?)
  • Can I merge any two nodes? (Do they always travel together?)
  • Can I remove any arrow? (Is the relationship obvious from layout?)
  • Can I remove any label? (Does color or shape already signal it?)

Signal:

  • Coral used on ≤2 elements? If more, which actually deserve focal status?
  • Legend covers every type used — and nothing extra?
  • Within the type's complexity budget (§7)?

Technical:

  • Arrows drawn before boxes?
  • Every arrow label has an opaque fill="#f5f5f5" rect behind it?
  • Legend is a horizontal bottom strip, not floating?
  • No vertical writing-mode text?
  • viewBox expanded for the legend strip (~60px)?
  • Every font size, coord, width, height, gap divisible by 4?

Typography:

  • Human-readable names in Geist sans, not Geist Mono?
  • Technical sublabels (ports, commands, URLs) in Geist Mono?
  • Page title in Instrument Serif?
  • Annotation callouts (if any) in italic Instrument Serif? (see primitive-annotation.md)
  • No JetBrains Mono anywhere?

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.