Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation review — adaptive themed website diagrams
Reviewed PR #1 against the repository documentation standards. The feature work is solid: changelog entries, reproducible generation, CI freshness checks, and renderer/runtime wiring are in place.
Gaps found in this PR
| Area | Finding |
|---|---|
| Maintainer runbook | No guide for website/diagrams/, generate-diagrams.mjs, or @image[themed=true] workflow |
| Spec surface | @image with themed property not documented in spec/informal.adoc |
| Website README | website/README.adoc still contained Food Truck Nerdz boilerplate unrelated to CentrMark |
| Docs index | New subsystem not linked from /docs navigation |
| Root README | Missing Docs | Dev-Centr badge; Website section lacked diagram commands |
| Published changelog | website/public/docs/changelog.adoc was missing several entries present in root changelog.adoc |
Companion documentation PR
Addressed in branch cursor/documentation-automation-system-01ed (companion PR):
website/public/docs/adaptive-themed-diagrams.adoc— maintainer guide covering Mermaid sources, Themed SVG manifests,diagrams:generate/diagrams:check, safety verification, host token wiring, and troubleshooting- Wired into
/docs/adaptive-themed-diagramssite routes - Fixed
website/README.adocfor the CentrMark SolidStart site - Documented
@image[themed=true]inspec/informal.adocand@centrmark/cmk-rendererREADME - Added Docs badge and Website pointers in root
README.adoc - Synced published changelog with root source
Codepaths covered
website/scripts/generate-diagrams.mjs— generation, contrast, SVG safety, freshnesswebsite/diagrams/*— Mermaid + theme manifest authoringwebsite/src/entry-client.tsx+app.css— runtime upgrade and host tokenspackages/cmk-renderer/src/html.ts—@image/data-themed-svgrenderingexamples/images.cmk— CMK author usage
Note on Antora
This repository publishes docs through the SolidStart site (website/public/docs/), not a separate Antora playbook. No Antora/Valentus migration is required for this change set.
Sent by Cursor Automation: Generate docs
| @@ -0,0 +1,182 @@ | |||
| import { spawnSync } from "node:child_process"; | |||
There was a problem hiding this comment.
Good addition — the generation script encodes the full maintainer contract (Mermaid render → themed dual output → contrast + SVG safety + freshness checks). This was the main documentation gap: the PR ships the pipeline but did not previously explain how to extend or troubleshoot it. See companion branch cursor/documentation-automation-system-01ed for website/public/docs/adaptive-themed-diagrams.adoc.
| 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" : ""; |
There was a problem hiding this comment.
The themed=true → data-themed-svg contract is the author-facing hook for progressive enhancement. Consider cross-linking from spec/informal.adoc (companion docs PR adds @image documentation) so CMK authors know when to opt in.
| @@ -1,3 +1,12 @@ | |||
| import { mount, StartClient } from "@solidjs/start/client"; | |||
| import { upgradeThemedSvgImages } from "@dev-centr/themed-svg/runtime"; | |||
There was a problem hiding this comment.
Runtime upgrade via upgradeThemedSvgImages + MutationObserver is easy to miss when debugging theme mismatches. The new maintainer guide documents the host-token wiring in app.css that this depends on.
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
1 participant
Summary
The checklist and feature-tabs images were fixed-color drawings with no editable diagram source. This PR replaces them with reproducible Mermaid diagrams that remain readable as ordinary images and progressively inherit the website palette when JavaScript is available.
This PR:
.fixed.svg.host.svgsiblings with the pinned published packagesThe existing
/examples/imagesroute currently encounters a Solid hydration mismatch from its client-only resource setup. Direct browser checks of both generated SVGs passed, but that pre-existing route issue prevents an end-to-end runtime-upgrade smoke test in this PR.Happy to adjust the diagram wording or palette mapping if another representation fits the project better.
Visual review
Preserved fixed artwork
Adaptive replacements
Verification
pnpm installpnpm run buildinwebsitepnpm --filter @centrmark/cmk-renderer testpnpm --dir website run diagrams:checkorigin/main