feat(diagrams): bring the hand-drawn diagrams onto the same palette

[jd]

<GitGraph> was a second Graphviz pipeline running beside the dot fences,
with its own COLORS map, its own EDGE_COLOR, and its own string-replace for
dark mode. <StackMapping> was a third, with five more hex literals. Three
surfaces, three private palettes, all drifting apart — which is how a page like
merge-queue/stacks ends up rendering a themed diagram and a baked one side by
side.

All three now name roles. src/util/diagramSvg.ts holds the post-processing
both Graphviz surfaces share — drop the canvas, strip the inline paint, mark a
borderless shape as a caption — so there is one place to change and no second
list of hex strings to fall out of date. The hand-placed SVG in GitGraph's
linear mode and in StackMapping emits the same node / edge groups and the
same role classes, so .dg paints all four kinds of diagram from one
stylesheet. --theme-diagram-edge is deleted: it was the old surfaces' single
diagram token and --dg-a-chrome now says the same thing.

This also fixes the bug that made the case for it. GitGraph marks every node
style=filled, which reaches a shape=plaintext node too, so the main
branch label sat on an opaque pale box — barely noticeable in light mode and
glaring in dark, on seven pages. It is a caption, so it now carries plain and
the box is gone.

Two things changed while I was in there:

• <StackMapping> sizes its columns to their content. They were fixed at
  160px and the generated branch names did not fit; the overflow was invisible
  while the label was white on a solid fill, and would have been plainly
  visible once the label became dark text on a tint.
• Graph-mode commit graphs are typeset at the same sizes as the fences (13/10
  rather than Graphviz's default 14 and a hand-set 9), so the two kinds of
  diagram on one page no longer disagree about how big a label is.

A call site names a role rather than a color: color: "green" becomes
role: "queued", commitColor="green" becomes commitRole="queued". The
prop is typed as DiagramRole, so a color name no longer compiles.

[jd]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	feat(diagrams): bring the hand-drawn diagrams onto the same palette	#12647	👈
2	feat(diagrams): let each diagram name its own roles, and lock the door	#12648
3	docs(design): write the diagram system into DESIGN.md	#12649

[mergify]

Merge Protections

🔴 2 of 6 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	👀 Review Requirements	👀 reviews
🔴	🔎 Reviews	👀 reviews
🟢	🤖 Continuous Integration	—
🟢	Enforce conventional commit	—
🟢	📕 PR description	—
🟢	🚦 Auto-queue	—

🔴 👀 Review Requirements

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

• any of:
  • #approved-reviews-by >= 2
  • author = dependabot[bot]
  • author = renovate[bot]
  • all of:
    • author = mergify-ci-bot
    • -head ~= ^docs-agent/

🔴 🔎 Reviews

Waiting for

• #review-requested = 0

This rule is failing.

• #review-requested = 0
• #changes-requested-reviews-by = 0
• #review-threads-unresolved = 0

---

Show 4 satisfied protections

🟢 🤖 Continuous Integration

• all of:
  • check-success = build
  • check-success = lint
  • check-success = test
  • any of:
    • check-success = test-broken-links
    • label = ignore-broken-links
  • any of:
    • check-success=Cloudflare Pages
    • -head-repo-full-name~=^Mergifyio/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[Copilot]

🔵 Needs a closer look

It changes shared diagram rendering and styling across many pages, so a final human review with visual verification is advisable.

Pull request overview

This PR unifies all diagram rendering (Graphviz fences, <GitGraph>, and <StackMapping>) under a single role-based palette and shared SVG post-processing, so diagrams stay consistent across themes and pages.

Changes:

• Introduces finishDiagramSvg() as a shared Graphviz SVG post-processor and a single source of truth for diagram roles.
• Refactors <GitGraph> and the remark Graphviz pipeline to emit role classes (instead of hard-coded colors) and rely on .dg styling.
• Updates hand-drawn SVG diagrams (<StackMapping>, GitGraph linear mode) and docs call sites to use roles (commitRole, role) instead of colors.

File summaries

File	Description
src/util/diagramSvg.ts	Adds shared SVG post-processing and centralized DiagramRole vocabulary.
src/styles/theme.css	Removes the legacy --theme-diagram-edge token in favor of role accents.
src/styles/index.css	Extends .dg painting rules to cover hand-placed shapes and sets sizing for fixed-size diagrams.
src/content/docs/stacks/updating.mdx	Updates <GitGraph> usage from commitColor to commitRole.
src/content/docs/stacks/concepts.mdx	Updates <GitGraph> usage from commitColor to commitRole.
src/content/docs/stacks/compare/graphite.mdx	Migrates node objects from color to role.
src/content/docs/stacks/compare/gh-stack.mdx	Migrates node objects from color to role.
src/content/docs/stacks.mdx	Migrates PR/node coloring from color/commitColor to role-based props.
src/content/docs/merge-queue/stacks.mdx	Updates <GitGraph> usage from commitColor to commitRole.
src/content/docs/merge-queue/merge-strategies.mdx	Migrates node objects from color to role.
src/components/StacksLocalModel.astro	Updates <GitGraph> usage from commitColor to commitRole.
src/components/StackMapping.astro	Refactors hand-placed SVG to use .dg roles and content-sized columns (removes hex literals/styles).
src/components/GitGraph.astro	Refactors both linear and Graphviz modes to emit role classes and use shared SVG post-processing.
plugins/remark-graphviz.ts	Switches to shared SVG post-processing and keeps legacy color-to-role mapping via roleFor.

Review details

Suppressed comments (1)

plugins/remark-graphviz.ts:140

• To keep the finishDiagramSvg(..., { roleFor }) contract type-safe, legacyRoleFor should return DiagramRole | undefined (matching the roles actually used in LEGACY_ROLES). This prevents accidentally returning an unsupported role string that .dg can't style.

function legacyRoleFor(kind: DiagramKind, { fill, stroke }: ShapePaint): string | undefined {
  if (kind === 'edge') return stroke ? LEGACY_ROLES[stroke.toLowerCase()] : undefined;
  const table = kind === 'cluster' ? LEGACY_CLUSTER_ROLES : LEGACY_ROLES;
  const color = !fill || fill === 'none' ? (kind === 'cluster' ? stroke : undefined) : fill;
  return color ? table[color.toLowerCase()] : undefined;

• Files reviewed: 14/14 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jd]

Revision history

#	Type	Changes	Reason	Date
1	initial	204561e		2026-09-02 00:57 UTC
2	content	204561e → e2b246d	review (#12647): type roleFor and the legacy tables as DiagramRole; unit-test the shared SVG post-processor	2026-09-02 00:57 UTC
3	rebase	e2b246d → b010849 (rebase only)	rebase onto main after #12646 merged — the squashed phase-1 commit made this branch conflict; no content change	2026-09-03 16:59 UTC

[jd]

Re-pushed to address the review: 204561e → e2b246d (compare).

• roleFor returns DiagramRole | undefined, and the legacy tables are Record<string, DiagramRole> — a typo in one of the ~40 role names used to compile and produce an unstyled element, and now fails the build.
• DiagramRole imported alongside DiagramKind / ShapePaint.
• New src/util/diagramSvg.test.ts: 7 cases on the shared post-processor, driven on hand-written SVG rather than through Graphviz. The one that earns its place is direct-children-only paint stripping, which find() instead of children() would break while passing every existing test.

pnpm check, pnpm test and pnpm build green on this commit on its own.

[mergify]

@jd this pull request is now in conflict 😩

[jd]

Rebased onto main now that #12646 has merged — that was the conflict: the branch still carried the pre-squash phase-1 commit. No content change, just a new base.

e2b246d → b010849 — e2b246d...b010849

pnpm check, pnpm test (202), pnpm check:diagram-tokens and pnpm build all green on the rebased stack.