git:20261010.3ba1fbe to git:20261113.8af5195

40 added, 19 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: diagram-design
description: >-
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
---
# Diagram design
- Based on [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) (skills.sh). This skill requires the upstream pack and its reference files. Locate its installed directory in your environment. If it is missing, ask the user to install it before continuing. Read its `SKILL.md` and the matching `references/type-*.md` before drawing. Resolve all reference paths below from that directory.
+ 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.
- Use this for explainer diagrams (architecture, sequence, process, layer stack, loop, and the other types in that pack) as standalone HTML/SVG/PNG. Not for a paragraph that already does the job, not for a 3-column table, not for one-shape "diagrams."
+ ## Should this be a diagram?
- ## Philosophy
+ 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".
- The highest-quality move is deletion. Every node is a distinct idea. Target density 4/10. Above 9 nodes, split into two diagrams. One focal accent, not a traffic light.
+ ## Plan before drawing
- ## Do not ship these
+ 1. Write the caption first: one sentence the diagram proves. If you can't, you don't know what to draw yet.
+ 2. 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.
+ 3. List the nodes. Merge any two that always appear together. Past about nine nodes or twelve arrows, split into an overview and a detail.
+ 4. 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.
- - Ranking dashboards, two-column scorecards, or three equal summary cards as the default
- - Dark mode + cyan/purple glow
- - Tiny type
- - Shadows; borders instead
- - Accent on every "important" node (1–2 max)
- - Identical boxes for every node
- - Reproducing Mermaid's automatic layout
+ ## Drawing rules
- ## Before you draw
+ - 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.
- 1. Ask whether a well-written paragraph would teach more. If yes, don't draw.
- 2. Name the visual type and load `references/type-<name>.md`.
- 3. Skin from `references/style-guide.md`. Do not silently ship the default tangerine skin into a branded project. Pull tokens from the live brand or a saved profile first.
- 4. For a 16:9 social or ad still (1200×675), one idea, large type, no legend soup.
+ ## 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
- Self-contained HTML with inline SVG/CSS, then export PNG when the destination is a post or ad. Follow `references/export.md` and `references/output-spec.md`.
+ - 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.
- License: the upstream diagram pack uses MIT. See [third-party notices](../../../THIRD_PARTY_NOTICES.md) and the [source audit](../../../docs/credits.md).
+ ## Inspired by
+
+ - [Cathryn Lavery, diagram-design](https://github.com/cathrynlavery/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](https://c4model.com/diagrams/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](https://en.wikipedia.org/wiki/Chartjunk). 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.