docs: adaptive themed diagrams maintainer guide

.gitignore

@@ -50,3 +50,4 @@
 **/.turbo/
 **/coverage/
 **/*.tsbuildinfo
+**/*.raw.svg

README.adoc

@@ -12,6 +12,7 @@ ifdef::env-github[]
 <a href="https://github.com/dev-centr/centrmark/stargazers"><img src="https://img.shields.io/github/stars/dev-centr/centrmark.svg?style=for-the-badge" alt="Stars"></a>
 <a href="https://github.com/dev-centr/centrmark/issues"><img src="https://img.shields.io/github/issues/dev-centr/centrmark.svg?style=for-the-badge" alt="Issues"></a>
 <a href="https://github.com/dev-centr/centrmark/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dev-centr/centrmark.svg?style=for-the-badge" alt="License"></a>
+<a href="https://dev-centr.github.io/centrmark/"><img src="https://img.shields.io/badge/Docs-Dev--Centr-4f46e5?style=for-the-badge" alt="Docs | Dev-Centr"></a>
 <br />
 <h3 align="center">CentrMark (CMK)</h3>
 <p align="center">
@@ -43,6 +44,7 @@ endif::[]
 image:https://github.com/dev-centr/centrmark/actions/workflows/cmk-renderer-ci.yml/badge.svg[CMK Renderer CI,link=https://github.com/dev-centr/centrmark/actions/workflows/cmk-renderer-ci.yml]
 image:https://github.com/dev-centr/centrmark/actions/workflows/cmk-pages.yml/badge.svg[CMK Pages,link=https://github.com/dev-centr/centrmark/actions/workflows/cmk-pages.yml]
 image:https://github.com/dev-centr/centrmark/actions/workflows/cmk-release.yml/badge.svg[CMK Release Builds,link=https://github.com/dev-centr/centrmark/actions/workflows/cmk-release.yml]
+image:https://img.shields.io/badge/Docs-Dev--Centr-4f46e5?style=for-the-badge[Docs | Dev-Centr,link=https://dev-centr.github.io/centrmark/]
 
 
 == About The Project
@@ -160,6 +162,9 @@ To keep CentrMark behavior consistent across independent implementations, this r
 
 The documentation + example registry site is in `website/`.
 
+* Maintainer guide: `website/public/docs/adaptive-themed-diagrams.adoc` (also served at `/docs/adaptive-themed-diagrams` on the published site)
+* Diagram generation: `pnpm --dir website diagrams:generate` / `diagrams:check`
+
 == Antora CMK backend
 
 If you want to publish Antora documentation authored in CentrMark (`.cmk`), this repo includes an MVP backend/preprocessor at `antora/cmk-antora-backend/`.

changelog-details/2026-09-08 - adaptive-website-diagrams.adoc

@@ -0,0 +1,7 @@
+= 2026-09-08 – Adaptive website diagrams
+
+* Replaced the checklist and feature-tabs illustrations with genuine Mermaid diagrams whose editable sources describe checklist state transitions and tabbed representation grouping.
+* Added explicit Themed SVG v1 manifests and reproducible generation with `@dev-centr/mermaid-svg-css-vars@0.1.2`, `@dev-centr/themed-svg@0.1.1`, and `@mermaid-js/mermaid-cli@11.17.0`.
+* Published standalone-adaptive canonical SVGs and progressively enhanced `.host.svg` siblings while preserving the original fixed artwork as `.fixed.svg`.
+* Added generated-asset freshness, SVG safety, accessibility, and light/dark delivery checks to the website build.
+* Rendered CentrMark image directives as accessible images and upgraded opted-in diagrams through the sanitized Themed SVG runtime using the website theme tokens.

changelog.adoc

@@ -2,6 +2,13 @@
 
 This changelog acts as a centralized historical record of the evolution of the CentrMark standard over time.
 
+== 2026-09-08 – Adaptive website diagrams
+
+* Replaced two fixed website illustrations with editable Mermaid diagrams and standalone-adaptive SVGs.
+* Added explicit Themed SVG manifests, host-mode outputs, progressive runtime enhancement, and reproducible freshness and safety checks.
+* Preserved the original artwork under stable `.fixed.svg` names.
+* See link:changelog-details/2026-09-08 - adaptive-website-diagrams.adoc[Detailed changelog].
+
 == 2026-08-04 – Literary sources and framework packages
 
 * Added literary-sources citations (`@cite`, `::: sources` / `::: source`, `:: bibliography`) to the language surface and reference renderer.

examples/images.cmk

@@ -13,6 +13,6 @@ status "Final"
 
 Inline directives can embed images without dropping down into raw HTML.
 
-@image[src="/images/feature-tabs.svg" alt="Diagram: tabs grouping multiple representations"](Tabs groups multi-tool/multi-language variants under one semantic item.)
+@image[src="/images/feature-tabs.svg" alt="Diagram: tabs grouping multiple representations" themed=true](Tabs groups multi-tool/multi-language variants under one semantic item.)
 
-@image[src="/images/checklist.svg" alt="Diagram: x/X checklist"](Checklists express state with a single indicator family.)
+@image[src="/images/checklist.svg" alt="Diagram: checklist item states" themed=true](Checklists express state with a single indicator family.)

packages/cmk-renderer/README.md

@@ -16,4 +16,5 @@ Shared CentrMark rendering pipeline for web and editor integrations.
 - `::: checklist [type="..."]` (supports `[ ]`, `[x]`, `[-]`, `[/]`)
 - `::: diagram [format="mermaid|plantuml|graphviz|dot" ...]`
 - `::: animation [format="lottie|gif|mp4|webm|..." src="..."]`
+- `@image[src="..." alt="..." themed=true]` — accessible images; `themed=true` adds `data-themed-svg` for adaptive SVG host upgrade
 - Literary sources: `@cite[key="..."]` / `@cite[keys="a,b"]`, `::: sources` + nested `::: source`, and void `:: bibliography`

packages/cmk-renderer/src/html.ts

@@ -261,6 +261,14 @@ function renderInline(ctx: RenderContext, node: RenderInline): string {
   if (node.type === "inlineDirective" && node.name.toLowerCase() === "cite") {
     return renderCitation(ctx, parseCitationKeysFromProps(node.propsRaw));
   }
+  if (node.type === "inlineDirective" && node.name.toLowerCase() === "image") {
+    const props = parseDirectiveProps(node.propsRaw);
+    const src = typeof props.src === "string" ? props.src : "";
+    const alt = typeof props.alt === "string" ? props.alt : "";
+    const themed = props.themed === true ? " data-themed-svg" : "";
+    const caption = renderInlines(ctx, node.children);
+    return `<span class="cmk-image"><img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}" loading="lazy" decoding="async"${themed} />${caption ? `<span class="cmk-image-caption">${caption}</span>` : ""}</span>`;
+  }
   return `<span data-cmk-inline-directive="${escapeHtml(node.name)}">${renderInlines(ctx, node.children)}</span>`;
 }
 

packages/cmk-renderer/tests/renderer.test.mjs

@@ -37,6 +37,14 @@ test("renders HTML from literate-programming AST fixture", async () => {
   assert.ok(html.includes("<p>") || html.includes("<h1>"));
 });
 
+test("renders themed image directives with an adaptive fallback", async () => {
+  const ast = await loadExampleAst("images");
+  const html = renderIRToHtml(astJsonToRenderIR(ast));
+  assert.ok(html.includes('src="/images/feature-tabs.svg"'));
+  assert.ok(html.includes('alt="Diagram: tabs grouping multiple representations"'));
+  assert.ok(html.includes("data-themed-svg"));
+});
+
 test("renders literary sources citations and bibliography", () => {
   const ast = {
     frontmatter: { raw: "" },