openspec: define docs-book-ux-fixes change (proposal, spec, design, tasks)

openspec/changes/docs-book-ux-fixes/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-15

openspec/changes/docs-book-ux-fixes/design.md

@@ -0,0 +1,29 @@
+# Design: docs-book-ux-fixes
+
+## Context
+
+The book theme lives in three files loaded via `docs/book.toml` `additional-css`/`additional-js`:
+`docs/skin/custom.css` (~1150 lines), `docs/skin/custom.js` (theme-list cleanup, brand, reveal),
+`docs/skin/mermaid-init.js` (renders `language-mermaid` fences with hardcoded `theme: 'dark'`).
+No `.mermaid` CSS exists. Sidebar and resize behavior is inherited from mdBook 0.5.2 defaults.
+
+## Decisions
+
+1. **Typography**: keep `:root 16px` (= 12pt); scale body prose down via `.content p/li` size and proportional heading steps; implement font-size control as three small ghost buttons (A-, A, A+) in the menu bar driven by a `data-sk-font-scale` attribute on `<html>` with `localStorage` persistence. Bounded range (e.g. 0.875–1.125) so KaTeX/Mermaid do not break.
+2. **Buttons**: top-bar `.icon-button` becomes borderless (`border: none`, transparent background, muted color, soft hover wash). Content `a.sk-btn` shrinks to `36px` height, `10px` radius, `0.85rem` font. Both variants keyed off existing `--sk-*` tokens; no new palette.
+3. **Sidebar accordion**: delegate to `custom.js`; wrap each `ol.section` under a toggle button with `aria-expanded`; single-open policy (opening one closes siblings at the same level); on load, expand the section containing `.active` and restore persisted state. Pure progressive enhancement — no-JS still shows all sections.
+4. **Resize reflow**: keep mdBook's `#sidebar-resize-handle`; change `.content main` from fixed centered `max-width: 62rem` to a fluid rule (`min(62rem, 100%)` + flex growth) so dragging the sidebar reflows text; add min/max clamp on sidebar width.
+5. **Mermaid fixed palette**: stop relying on Mermaid themes. Pass fixed `themeVariables` (node border/text, edge color, `edgeLabelBackground` opaque) plus a `.mermaid svg` CSS safety net per `.node` class. Map the six `--sk-*` pairs:
+   sky `#e0f2fe/#0c4a6e`, emerald `#dcfce7/#14532d`, violet `#ede9fe/#3b0764`,
+   amber `#fef3c7/#78350f`, rose `#ffe4e6/#7f1d1d`, neutral `#f4f4f5/#18181b`.
+   Migrate all `style X fill:...`-only directives in `docs/src/**` to `fill+stroke+color` triples.
+6. **Overflow**: `.mermaid { overflow-x: auto }`, `.mermaid svg { max-width: 100%; height: auto }`, Mermaid `flowchart: { htmlLabels: true, useMaxWidth: true }`, `wrap: true`; authoring rule (<= ~24 chars/line, `<br/>` breaks) added to `documentation-guide.md`; split only if a diagram still clips after CSS (ch05 nested subgraphs are candidates, not mandatory).
+
+## Alternatives considered
+
+- Per-theme Mermaid palettes (light pastel vs dark vibrant): rejected per operator decision for fixed colors (simpler, single test pass).
+- Third-party mdBook preprocessors for accordion/resize: rejected; mdBook 0.5 plugin surface is thin and upstream JS already owns the sidebar.
+
+## Verification
+
+- `mdbook build docs` succeeds; open `tutorials/how-to-add-an-algorithm.html` ("The journey at a glance"), `architecture.html`, one `ch*` page in both themes; check font control, accordion, resize, and Mermaid contrast/overflow at 3 font steps.

openspec/changes/docs-book-ux-fixes/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The mdBook documentation ships a custom theme (`docs/skin/custom.css`, `custom.js`, `mermaid-init.js`) with six user-reported defects: oversized body typography with no resize control, visually heavy top-bar buttons, a sidebar that never collapses sections, a resize handle that only shrinks content, illegible Mermaid text in the dark theme, and clipped node text in flowcharts.
+
+## What Changes
+
+- Reduce base body typography toward a 12pt-equivalent scale and add a persistent, accessible font-size control.
+- Restyle top-bar icon buttons (ghost style) and normalize content `sk-btn` sizing.
+- Add sidebar accordion behavior (single-open, persists state, exposes active chapter).
+- Fix sidebar/content resize so content reflows instead of only shrinking.
+- Standardize Mermaid diagrams on fixed `--sk-*` palette pairs (fill + text) with a neutral fixed edge color and edge-label background; migrate pastel-only `style` directives.
+- Fix Mermaid node-text clipping (container overflow, SVG max-width, authoring limits on label length).
+
+## Capabilities
+
+### New Capabilities
+
+- `docs-book-theme`: user-visible documentation theme behavior — typography scale + font-size control, buttons, sidebar accordion + resize, Mermaid contrast and overflow handling.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- Affected: `docs/skin/custom.css`, `docs/skin/custom.js`, `docs/skin/mermaid-init.js`, Mermaid fences in `docs/src/**/*.md`, `docs/src/documentation-guide.md` (authoring rules).
+- No Rust crates, no public API, no runtime behavior outside the built book.
+- Verification via `mdbook build docs` plus visual check of affected pages in both themes.

openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md

@@ -0,0 +1,106 @@
+# docs-book-theme
+
+## Purpose
+
+Defines the readability and interaction contract of the mdBook documentation theme
+(typography, controls, sidebar, Mermaid rendering) shared by the light and dark
+palettes.
+
+## ADDED Requirements
+
+### Requirement: Typography scale and font-size control
+
+The book SHALL render body prose at a 12pt-equivalent scale (root `16px`, body text at
+or below that size, headings scaled proportionally) and SHALL provide a visible
+font-size control (decrease / reset / increase) in the top bar that adjusts prose size
+across a bounded range, persists the choice across page loads and respects
+`prefers-reduced-motion` where animation is involved. KaTeX and Mermaid text SHALL stay
+legible at every size step, with no clipping introduced by scaling.
+
+#### Scenario: First visit uses the default size
+
+- **WHEN** a reader opens any page without a previously stored preference
+- **THEN** prose renders at the 12pt-equivalent default and the control shows the reset state
+
+#### Scenario: Reader increases the size and reloads
+
+- **WHEN** a reader presses the increase control and then reloads another page
+- **THEN** the enlarged size applies again from the stored preference and no KaTeX or Mermaid text is clipped
+
+### Requirement: Top-bar and content buttons
+
+Top-bar icon buttons SHALL render as borderless ghost controls (no boxed border, no
+heavy background) with a subtle hover state in both light and dark themes, and content
+`sk-btn` elements SHALL render at a compact size (shorter than the original `44px`
+height) with consistent radius and readable labels.
+
+#### Scenario: Ghost hover state in both themes
+
+- **WHEN** a reader hovers or focuses a top-bar icon button in the light theme and then in the dark theme
+- **THEN** the button shows the same subtle hover treatment with no boxed border or heavy background
+
+#### Scenario: Compact content buttons
+
+- **WHEN** a page renders content `sk-btn` elements
+- **THEN** each button is shorter than `44px`, keeps a consistent radius and a readable label
+
+### Requirement: Sidebar accordion and resize
+
+The sidebar SHALL behave as an accordion: expanding one section collapses its siblings,
+the active chapter's section is exposed on page load, state is keyboard-accessible via
+`aria-expanded` and persists across page loads. Sidebar resize SHALL reflow the content
+width (no fixed `max-width` that only shrinks the reading area) within sensible
+minimum and maximum bounds.
+
+#### Scenario: Single-open sections
+
+- **WHEN** a reader expands a sidebar section while another one is open
+- **THEN** the previously open section collapses and both toggles expose the correct `aria-expanded` state
+
+#### Scenario: Resizing reflows the content
+
+- **WHEN** a reader drags the sidebar resize handle wider or narrower
+- **THEN** the reading column reflows to the new available width instead of merely clipping, within the configured bounds
+
+### Requirement: Mermaid contrast with a fixed palette
+
+Every Mermaid node SHALL render with a fixed fill+text pair drawn from the `--sk-*`
+documentation palette (sky, emerald, violet, amber, rose, neutral), identical in the
+light and dark themes, with a text-to-fill contrast ratio of at least 4.5:1. Edges and
+edge labels SHALL use a fixed neutral color legible on both page backgrounds, with an
+opaque edge-label background that does not inherit the page theme.
+
+#### Scenario: Diagrams render identically in both themes
+
+- **WHEN** a reader switches between the light and dark themes on a page containing a Mermaid diagram
+- **THEN** node fills, node text, edges and edge-label backgrounds keep the same fixed colors with contrast of at least 4.5:1
+
+### Requirement: Mermaid colors independent of the page theme
+
+The theme SHALL NOT rely on Mermaid's per-theme defaults for node text, edge color or
+edge-label background; those three elements SHALL be pinned explicitly so a theme switch
+never changes diagram legibility.
+
+#### Scenario: Theme switch leaves diagram colors untouched
+
+- **WHEN** a reader toggles the light/dark theme while a Mermaid diagram is on screen
+- **THEN** node text, edge color and edge-label background do not change with the page theme
+
+### Requirement: Mermaid overflow containment
+
+Text inside flowchart nodes SHALL NOT be clipped for the documented diagrams (including
+`tutorials/how-to-add-an-algorithm.md` "The journey at a glance"): long tokens wrap or
+break, the SVG scales to its container (`max-width: 100%`) and horizontal overflow
+scrolls within the diagram container rather than clipping. Authoring limits (maximum
+characters per line, mandatory `<br/>` breaks, short-label guidance) SHALL be documented
+in `docs/src/documentation-guide.md`.
+
+#### Scenario: Long labels stay readable
+
+- **WHEN** a diagram contains a node label longer than the node width
+- **THEN** the label wraps or breaks inside the node and the diagram scrolls horizontally within its container instead of clipping
+
+#### Scenario: Authoring limits are documented
+
+- **WHEN** a documentation author follows `docs/src/documentation-guide.md`
+- **THEN** the guide states the maximum characters per line, the mandatory `<br/>` breaks and the short-label guidance for Mermaid nodes

openspec/changes/docs-book-ux-fixes/tasks.md

@@ -0,0 +1,10 @@
+# Tasks
+
+- [x] 1. Set up `docs/book-ux-fixes` code worktree (branch `docs/book-ux-fixes`) and `-openspec` worktree; open ADR issue in English.
+- [x] 2. Typography: scale prose toward 12pt-equivalent and add persistent A-/reset/A+ control in the top bar (attribute + localStorage, bounded range, both themes).
+- [x] 3. Buttons: convert top-bar icon buttons to ghost style; compact `sk-btn` sizing; verify hover/focus states in both themes.
+- [x] 4. Sidebar accordion: single-open toggle with `aria-expanded`, active-chapter auto-expand, persisted state, no-JS fallback.
+- [x] 5. Resize reflow: fluid `.content main` rule + sidebar min/max clamp; verify dragging reflows instead of only shrinking.
+- [x] 6. Mermaid contrast: fixed `themeVariables` + `.mermaid svg` safety net; migrate pastel-only `style` directives to `--sk-*` fill+stroke+color triples; fixed neutral edges and opaque edge-label background.
+- [x] 7. Mermaid overflow: container scroll + SVG max-width + flowchart wrap config; apply `<br/>` breaks to "The journey at a glance" and any other clipping diagram; document authoring limits in `documentation-guide.md`.
+- [x] 8. Validate: `mdbook build docs`, visual check of affected pages in both themes at 3 font steps; independent review; update `CHANGELOG.md`; open PR with `Closes #<adr-issue>`.