clearfelt-diagram · v0.2 · engine + Astro adapter

Mermaid that renders the same way twice.

A diagram that renders correctly once and wrong the next time isn't a diagram you can ship. This is the render pipeline, theming system and linter extracted from a production blog's diagram system after 95 real diagrams and several rounds of "looked fine in source, wrong once rendered."

andrei-ionut-nita / clearfelt-diagramView on GitHub ↗

Reproducible Mermaid: static SVG at build time, theme-aliased colors, 12 Cardinal Rules linted in CI.

TypeScriptMIT licencedocs in README

$npx clearfelt-diagram-init init my-docs

architecture.svg · rendered once, at build time

$ cli.js render architecture.mmd

  ✓ subgraph titles repositioned into corner labels
  ✓ accent node given gradient and glow
  ✓ literal colors reverse-mapped to var(--brand-*)
  → architecture.svg  +  architecture.theme.css

$ cardinal-rules-lint architecture.mmd

  ✓ color semantics        ✓ one accent node only
  ✓ nodes per visual row 4 ✓ decision-diamond sizing
  new violations: 0  ·  baseline-diffed

No pass reparses or reserializes the SVG. Every one is a scoped, targeted string replacement, so unrelated markup is never touched.

Why not just write raw Mermaid?

You still do, mostly. This is not a new diagramming language. What it adds:

12 Cardinal Rules

Color semantics, layout, typography hierarchy and decision-diamond sizing. Each rule was written after a real diagram shipped wrong.

Static SVG, zero client JS

Diagrams render once, at build time, through a real headless browser. No client-side Mermaid bundle shipped to every visitor.

Theme-reactive without a re-render

Colors are tokenized to your CSS variables, so a diagram baked once still follows your site's light and dark toggle through the ordinary cascade.

A linter that renders

One check actually renders the SVG and counts nodes per visual row, rather than pattern-matching the source text and hoping.

Baseline-diffed CI

Only new rule violations fail a check, so you can adopt it on an existing diagram corpus without a big-bang fix-everything pass.

Your palette, contrast-checked

The extract-palette skill reads your real CSS tokens, proposes a mapping onto the diagram color slots, validates contrast, and writes a theme for you to review before anything is saved.

Three packages

@clearfelt/diagram-engine

The payload, framework-agnostic: render, lint, theming, palette, a CSS token resolver, a WCAG contrast checker, the typed defineDiagram wrapper, and the CLI.

@clearfelt/diagram-astro

A thin Diagram component for Astro projects, depending only on the engine.

@clearfelt/cli

The scaffolder: init and upgrade with hash-gated skill files, all ten palettes selectable at scaffold time, and the full Claude Code skill set.

What you can ask it to do

create-diagram

Describe the diagram you want and it writes the source, then renders it.

diagram-review

Reads a finished diagram back and says where it is hard to follow.

cardinal-rules-lint

Checks it against the 12 rules and reports only what is newly broken.

extract-palette

Reads your site's real colours, maps them onto the diagram, checks contrast.

Full command reference in the README →

Quick start

pnpm install

node packages/engine/dist/cli.js new architecture --pattern flowchart
node packages/engine/dist/cli.js render architecture.mmd

render writes architecture.svg and, on the shipped default theme, a companion architecture.theme.css, so the diagram displays correctly with zero project styling. If your project already has real design tokens, run extract-palette instead of taking the default.