feat(docs): brand-styled Mermaid diagrams via @docusaurus/theme-mermaid - #69
Merged
Conversation
Convert the three tables in WayOfWork/spec-driven-development.md (Pipeline stages, Layers, Commands) into Mermaid flowcharts that inherit the Conduction cobalt-and-orange palette. - Add @docusaurus/theme-mermaid and enable markdown.mermaid in docusaurus.config.js. The theme registers a remark plugin that picks up ```mermaid fences in both .md and .mdx, so existing CommonMark docs keep working. - Set site-wide brand themeVariables (cobalt-50 fill, cobalt-200 border, cobalt-400 edges, cobalt-700 text, Figtree font) so authors write plain ```mermaid blocks without per-diagram theme directives. - Ship src/css/conduction-mermaid.css with container chrome (cobalt-50 panel matching the product-page mockups), uppercase Plex Mono cluster labels, and three classDef hooks: :::accent (KNVB orange, one per diagram), :::stage (cobalt-cobalt for system nodes), :::muted (dashed cobalt-100 for out-of-scope nodes).
… MDX Three round-trip refinements to the Mermaid + cn-arch-flow surface: 1. Mermaid nodes are now solid cobalt-blue with white text and no visible border (border = fill). The previous lavender fill was Mermaid's `default` theme leaking through — the theme key has to live at themeConfig.mermaid.theme (not options.theme), because theme-mermaid's client spreads options first and overlays theme last, so options.theme was always overridden. 2. Subgraph cluster rects: transparent fill, cobalt-blue stroke. Groups now read as outlined regions rather than stacked cards — filled cobalt nodes > outlined groups > panel background. Cluster label fill also bumped from cobalt-400 to cobalt-blue for matching weight. 3. <cn-arch-flow> is now available site-wide in MDX/Markdown. src/diagrams/cn-arch-flow.js is copied locally pending the next @conduction/docusaurus-preset release; registration happens via clientModules so authors can drop <cn-arch-flow>...</cn-arch-flow> into any page without a per-page import. (clientModules also has to be set on the config object directly, since the preset's createConfig wrapper doesn't forward it.) Two MDX edits land alongside the wiring: - spec-driven-development.md "Claude Code" — the 3-lane Mermaid Layers diagram is replaced by two cn-arch-flow rows (Tool name on top row, what Claude does on bottom row), with OpenRegister / Schemas & validation as the accent column. - hydra/README.md "How it works" — the ASCII pipeline diagram becomes two cn-arch-flow rows: Build phase (Todo → Builder → Quality tests → Browser tests, Builder accent) and Review phase (Code review → Security review → Draft PR → Archive, Security review is the orange-hex accent). Prose bullets carry the detail that the 3-word nodes can't.
5 tasks
rubenvdlinde
added a commit
that referenced
this pull request
May 14, 2026
Brings in cn-pair, cn-arch-flow, and the App Builder hex orange fix. Drops the local website/src/diagrams/cn-arch-flow.js stopgap copy that was committed alongside PR #69 before the preset version bump. Site-wide cn-arch-flow registration now lives in one line: import '@conduction/docusaurus-preset/diagrams/cn-arch-flow'; (in website/src/diagrams/index.js, side-effect-imported via the clientModules entry in docusaurus.config.js — no per-page imports needed in MDX/Markdown). Verified locally: cn-arch-flow upgrades to a shadow-rooted custom element on the Spec-Driven Development and Hydra pages, no console errors, no missing-module warnings.
MWest2020
pushed a commit
that referenced
this pull request
Jul 17, 2026
…uild timeouts for 2-locale sites' (#69) from ci/docs-drop-setup-node-and-bump-timeout into main
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Turn the three tables in
docs/WayOfWork/spec-driven-development.md(Pipeline, Layers, Commands) into Conduction-branded Mermaid flowcharts. Authors keep writing plain Markdown; diagrams render with the cobalt-and-orange palette automatically.What changes
@docusaurus/theme-mermaidadded towebsite/. The theme registers a remark plugin that picks up triple-backtickmermaidfences in both.mdand.mdx, so the existing CommonMark docs (which don't escape angle brackets / curly braces) keep working.themeVariablesindocusaurus.config.js— cobalt-50 fill, cobalt-200 border, cobalt-400 edges, cobalt-700 text, Figtree font. Authors don't need per-diagram%%{init}%%blocks.website/src/css/conduction-mermaid.cssships the container chrome (cobalt-50 panel matching the product-page mockups), uppercase Plex Mono cluster labels, and threeclassDefhooks::::accent— KNVB orange, the one-orange-per-scene knob (use once per diagram).:::stage— solid cobalt for system / 'owned by us' nodes.:::muted— dashed cobalt-100 for out-of-scope nodes.spec-driven-development.md— three tables become three Mermaid charts plus bullet detail (so the prose in column 3 doesn't get lost in 3-word nodes).Why hybrid, not all-Mermaid
Mermaid is excellent for flowcharts and stays diff-friendly in MDX, but it cannot reliably render pointy-top hexes with one-orange accents and stay brand-strict. The line is:
<cn-*>web components from@conduction/docusaurus-preset/diagrams.The shape-illustration side is being expanded in a parallel design-system PR (new
<cn-pair>and<cn-arch-flow>components extracted from the unindexed patterns inpreview/product-pages/technical-docs.htmlandintegrations.html).Follow-up (not in this PR)
Promote
conduction-mermaid.cssfromwebsite/src/css/into@conduction/docusaurus-presetso every Conduction Docusaurus site inherits the theme. Deferred until the CSS settles in the live site.Test plan
npm run startboots cleanly onlocalhost:30883 - Buildin KNVB orange/opsx-applyin KNVB orangeapp-downloads.jsonin the preset, unrelated)npm run buildsucceeds (preview only; CI will run on merge)