feat: ambient mm illustrations (48 = 12 slots × 4 心境) + themed-plate pipeline#11
Merged
Conversation
…/code theming
Unifies the plumbing that lets mental-model chapters carry ambient
illustrations with native day/night variants, and smooths two friction
points in the bilingual reading experience.
- sync-content.mjs: retire the mkdocs-era card emission from the article
body (the `<div class="mm-article" data-card=…>` wrapper now unwraps to
prose-only); when a `<stem>.dark.png` sibling exists alongside an inline
``, emit a `<span class="themed-plate">` carrying both
`.themed-plate__light` and `.themed-plate__dark` `<img>` tags so the CSS
layer can swap them per `[data-theme]`. Tests updated accordingly.
- reader-site.css: add the themed-plate visibility rules; gate Shiki's
`--shiki-dark` CSS variables on `[data-theme="dark"]` so dual-theme
code blocks actually switch (Astro's default wiring uses
`prefers-color-scheme`, which doesn't match the site's manual toggle —
the symptom was near-black code text on near-black paper-sunk in dark).
- Topbar.astro: preserve approximate reading position across zh ↔ en
switches. On chapter pages we capture {sectionId, offsetRatio} into
sessionStorage keyed by destination pathname, then restore on
`astro:page-load` (required because Hall uses `<ClientRouter />` — an
SPA swap, so the inline script only runs once on the initial load).
Ratios, not pixels, keep the landing point meaningful across the
~30-50% length gap between ZH and EN. Non-chapter pages fall back to
a whole-page scrollY ratio. URL stays hash-free.
- mermaid-loader.ts: replace the default `dark`/`neutral` mermaid palettes
with `theme: "base"` driven by tokens.css (paper / ink / rule /
vermilion / gold / celadon). Strip author-supplied inline `style X
fill:#…` lines before rendering so they can't re-assert pink/yellow
defaults. Watch `[data-theme]` via MutationObserver and re-init +
re-render existing diagrams on flip. Font stack now includes LXGW
WenKai / Noto Serif SC fallbacks so the Chinese edge labels in a
bilingual flowchart don't drop to a random system font.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the mkdocs-era infograph card PNGs on 12 mental-model sections with hand-brushed ambient illustrations, generated via gpt-image-2 on fal.ai. Each slot ships four "心境" variants — ZH day (宣纸水墨), ZH night (夜绢研墨), EN day (18c natural-philosophy plate), EN night (Victorian candlelit etching) — each variant drawn natively, not as a palette flip of another. The four share a common vermilion seal carrying one Chinese character per chapter (正 / 控 / 熵 / 系 / 形 / 因 / 符) as the across- culture anchor, and the site's warm tokens (paper / ink / vermilion / gold / celadon) as the only legal palette — no cool blues, no tech- infographic tropes. Slots and anchor paragraphs follow the judgment-pass from `.claude/notes/mental-models-illustration-slots.md`: only sections where a single image genuinely carries weight (the car spinning its tires, the helmsman on open water, Boltzmann's desk, Maxwell's demon at the door, demon → institution, seed ↔ mountain, Koch snowflake, Indra's pearl, Hume's billiard, Pearl's ladder, two roads). Heavy-taxonomy sections (OCP maps, OS break-points, symbol-connectionism analytics) stay text-only on purpose. Integration uses the themed-plate pipeline from the previous commit: each slot now has `assets/X.png` + `assets/X.dark.png` next to each other in both `docs/zh/...` and `docs/en/...`, plus a single plain `` reference at the anchor paragraph in the source markdown. sync-content.mjs emits the paired <img>s; reader-site.css swaps them on `[data-theme]`. - 12 slots × 4 variants = 48 new/updated PNGs (24 light files replace the old card PNGs; 24 `.dark.png` are new). - 12 source markdown pairs (ZH + EN) gain one inline `` line each at the slot's anchor paragraph. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat: ambient mm illustrations (48 = 12 slots × 4 心境) + themed-plate pipeline
PanQiWei
self-requested a review
April 23, 2026 13:37
Owner
|
Thanks! LGTM |
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
2 participants
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.
Cherry-picked from fork
pandazki/advanced-agentic-dev-patterns— originally PR #1 there, already merged to the fork'smain. Opening to upstream now.Summary
sync-content.mjsnow detects a<stem>.dark.pngsibling next to an inline image and emits a<span class="themed-plate">with paired<img>tags so CSS can swap per[data-theme]. Old mkdocsdata-cardwrappers are retired from the article body (info-cards will come back as a separate artefact, alongside the wiki module redo).--shiki-darkCSS vars but keys them onprefers-color-scheme; this site uses[data-theme="dark"]on<html>, so dark-mode code blocks were rendering near-black text on near-black paper-sunk bg. Override added.theme:"base"driven bytokens.css(paper / ink / rule / vermilion / gold / celadon). Strips author-suppliedstyle X fill:#…overrides, re-inits on[data-theme]flip, adds CJK fallback to the font stack for bilingual diagrams.Topbar.astronow saves{sectionId, ratio}intosessionStorageon language switch and restores it viaastro:page-load(Hall uses<ClientRouter />so the inline script only fires once otherwise). Ratios, not pixels, keep the landing point meaningful across the ~30-50% length gap between ZH and EN.Slot map
Only sections where a single ambient image earns its place got a slot; heavy-taxonomy sections (OCP maps, OS break-points, symbols-connectionism analytics) stay text-only on purpose.
Test plan
cd site && npm run test:sync→ 8/8 pass (transformCards no longer emits card image; themed-plate emitted when.dark.pngsibling exists)npm run syncproduces 24 themed-plate spans acrosssrc/content/mm/{zh,en}/**/0*.md—grep -rl themed-plate site/src/content/mm | wc -lshows 24<img>swaps correctly, page stays on approximately the same paragraph/zh/mm/entropy→ scroll to §02 因果结构 — mermaid renders in warm site palette (not pink/yellow), arrow labels render with CJK font/en/mm/entropy→ scroll to §02 Causal structure — the ASCIIpositive feedback loopcode block is readable in dark mode (was near-black on near-black before)#hashleft on the URL after language switch🤖 Generated with Claude Code