Codebase Diagrams And Slides

Codebase → Diagrams & Slides

Produce a small set of branded vector diagrams and an optional animated HTML slide deck that explain a codebase to humans. The output bar is high: light, clean, eye-friendly, professionally typeset, well-spaced, and visually verified.

This skill is language-agnostic. It reads the repo, distills the story, then renders it with a proven, palette-driven toolkit so results are consistent every time.

What you produce

Inputs & defaults

Resolve these before building. Everything except the codebase has a smart default.

Decide vs. ask

• If the user says "you decide / feel free / pick for me", do not interrogate them — apply the defaults above and state your assumptions in the summary.
• Otherwise, if key parameters are missing, ask once with a compact AskQuestion (max ~5 questions). High-value questions only:
  1. Number of diagrams (auto / 3 / 5 / 6).
  2. Slide deck? (no / yes ~8 / yes ~12 / yes — you choose count).
  3. Palette (company default / custom hex list).
  4. Audience (engineers / mixed / executives).
  5. Anything specific to emphasize (a subsystem, a flow, KPIs…).
• Never block on trivia. Pick reasonable defaults for fonts, spacing, file names.

Workflow

- [ ] 0  Resolve inputs (codebase, palette, #diagrams, slides?, audience)
- [ ] 1  Explore the codebase and distill the story
- [ ] 2  Plan the diagram set (archetype → set)
- [ ] 3  Generate diagrams with the toolkit → docs/diagrams/
- [ ] 4  Render to PNG, VIEW them, fix overlaps/overflow
- [ ] 5  (optional) Build the deck from the template → docs/presentation.html
- [ ] 6  Summarize, embed previews, offer tweaks

0 · Resolve — settle inputs per the policy above. Echo the plan in one line.

1 · Explore — understand before drawing. Prefer the explore subagent (or read key files: entry points, READMEs, config, module/dir layout, command/agent/route definitions, data models). Extract: purpose, top-level components, layers, the main flow/lifecycle, key entities, data/state movement, external systems, and any "reliability" rules (guards, tests, policies). Write a 5–10 bullet "story" you will draw. Do not fabricate behavior — only diagram what the code shows.

2 · Plan the set — map the codebase archetype to a diagram set (table below). Pick the count from inputs. Each diagram = one clear idea.

3 · Generate — copy scripts/svg_kit.py into docs/diagrams/, then write docs/diagrams/build_diagrams.py that does import svg_kit as k and composes each diagram with the proven primitives (so the output folder is self-contained and reproducible). Canvas is 1280×720. Use the layout recipes in references/diagram_patterns.md. Follow references/design_system.md for palette roles, fonts, spacing. Call k.use_palette([...]) first, then run it to emit SVGs.

4 · Verify (mandatory) — render every SVG to PNG with scripts/render.py and actually open the PNGs to inspect. Fix text overflow, overlaps, off-canvas elements, weak contrast, and crowding. Re-render after each fix. Never ship diagrams you have not looked at.

5 · Deck (optional) — copy templates/presentation.html to docs/presentation.html. Set the 5 palette vars in :root, brand text, and slide content. Embed diagrams with relative img src="diagrams/<file>.svg". The slide engine auto-counts slides, builds dots, supports keyboard / dots / buttons / swipe / fullscreen / deep-links, and respects reduced motion — don't reinvent it. Then render slides (render.py html ... --slides N) and view them. See references/slide_deck_spec.md.

6 · Summarize — list outputs, embed a few preview PNGs, state assumptions, and offer concrete next tweaks (count, language, dark theme, logo, PDF/PPTX export).

Codebase archetype → diagram set

Use as a starting set; trim/extend to the requested count.

Reusable layouts that cover almost everything: layered bands, phase/snake flow, card grid (roster), mapping rows, themed column cards, node/handoff flow. Recipes: references/diagram_patterns.md.

Design system (summary)

Full detail in references/design_system.md. Essentials:

• Palette roles (from the 5 colors, darkest→lightest): darkest = headings / emphasis fills (white text on it); mid = section accents / arrows; bright = accents & highlights; light = chip/box fills; pale = backgrounds. Body text is the darkest color; secondary text a derived muted tint. Light background, generous whitespace.
• Contrast: dark text on light fills. Never light-on-light or rainbow chips.
• Fonts — diagrams use system-safe fonts (Segoe UI / system stack) so they render identically inside PowerPoint. The HTML deck uses premium webfonts (Bricolage Grotesque display + Plus Jakarta Sans body + IBM Plex Mono) with safe fallbacks. Avoid generic Inter/Roboto in the deck.
• Spacing — consistent margins, breathing room, aligned grids; never crowd.
• Motion (deck only) — one orchestrated load: directional slide transitions + staggered reveals. Purposeful, smooth, never gratuitous.

Quality bar

What makes the output good — hold to all of it:

1. One idea per diagram. A viewer gets it in ~5 seconds.
2. Clarity over density. Cut detail before crowding.
3. Strong hierarchy. Title → sections → items, sized accordingly.
4. Restraint. Few colors, aligned grids, consistent radii/shadows.
5. Motion with purpose (deck) and respect reduced-motion.
6. Verify visually. Render and look. Fix anything that overlaps or overflows.
7. Truthful. Diagram only what the code does. Don't invent metrics/numbers.

Verification (do not skip)

SKILL below = .cursor/skills/codebase-diagrams-and-slides. Copy svg_kit.py once so the build script can import it (cp on macOS/Linux, Copy-Item in PowerShell).

# diagrams
cp  $SKILL/scripts/svg_kit.py  docs/diagrams/
python -X utf8 docs/diagrams/build_diagrams.py
python $SKILL/scripts/render.py svgs --dir docs/diagrams --out docs/diagrams/preview
# → open the PNGs and inspect every one; fix and re-render

# deck
python $SKILL/scripts/render.py html --file docs/presentation.html --slides N \
       --out docs/diagrams/preview --size 1600x900
# → open the slide PNGs and inspect; fix and re-render

render.py finds Chrome/Edge automatically (Windows/macOS/Linux). On Windows use python -X utf8.

Output & portability

• Diagrams: docs/diagrams/. Deck: docs/presentation.html (keep it next to diagrams/ because it references the SVGs by relative path).
• For a self-contained, send-anywhere deck, inline the SVG markup into the HTML instead of img src (note this trade-off to the user).
• The deck loads webfonts from Google Fonts when online; it degrades gracefully offline via the fallback stack.

Anti-patterns

• No rainbow palettes, no light-text-on-light, no overlapping/clipped elements.
• Don't fabricate data, KPIs, or behavior not present in the code.
• Don't ship without rendering and viewing the output.
• Don't hand-place dozens of chips by eye — use the toolkit's text measurement.
• No Windows-style paths in generated code (scripts/x.py, not scripts\x.py).
• Don't drop or restyle the company palette unless the user gives a new one.

Files in this skill