From 68c724364ca956c83f31b55905190d5dcb6d3703 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Claudino?= Date: Tue, 15 Sep 2026 16:38:32 -0300 Subject: [PATCH 1/2] openspec: define docs-book-ux-fixes change (proposal, spec, design, tasks) --- .../changes/docs-book-ux-fixes/.openspec.yaml | 2 ++ openspec/changes/docs-book-ux-fixes/design.md | 29 ++++++++++++++++++ .../changes/docs-book-ux-fixes/proposal.md | 28 +++++++++++++++++ .../specs/docs-book-theme/spec.md | 30 +++++++++++++++++++ openspec/changes/docs-book-ux-fixes/tasks.md | 10 +++++++ 5 files changed, 99 insertions(+) create mode 100644 openspec/changes/docs-book-ux-fixes/.openspec.yaml create mode 100644 openspec/changes/docs-book-ux-fixes/design.md create mode 100644 openspec/changes/docs-book-ux-fixes/proposal.md create mode 100644 openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md create mode 100644 openspec/changes/docs-book-ux-fixes/tasks.md diff --git a/openspec/changes/docs-book-ux-fixes/.openspec.yaml b/openspec/changes/docs-book-ux-fixes/.openspec.yaml new file mode 100644 index 0000000..96db9a4 --- /dev/null +++ b/openspec/changes/docs-book-ux-fixes/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-09-15 diff --git a/openspec/changes/docs-book-ux-fixes/design.md b/openspec/changes/docs-book-ux-fixes/design.md new file mode 100644 index 0000000..34df8ae --- /dev/null +++ b/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 `` 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, `
` 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. diff --git a/openspec/changes/docs-book-ux-fixes/proposal.md b/openspec/changes/docs-book-ux-fixes/proposal.md new file mode 100644 index 0000000..ddf4072 --- /dev/null +++ b/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. diff --git a/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md b/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md new file mode 100644 index 0000000..fc94b1d --- /dev/null +++ b/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md @@ -0,0 +1,30 @@ +# docs-book-theme + +## ADDED Requirements + +### Typography scale and font-size control + +- SHALL render body prose at a 12pt-equivalent scale (root `16px`, body text at or below the current size, headings scaled proportionally). +- 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. +- SHALL keep KaTeX and Mermaid text legible at every size step (no clipping introduced by scaling). + +### Top-bar and content buttons + +- SHALL render top-bar icon buttons as borderless ghost controls (no boxed border, no heavy background) with a subtle hover state, in both light and dark themes. +- SHALL render content `sk-btn` elements at a compact size (shorter than the current `44px` height) with consistent radius and readable labels. + +### Sidebar accordion and resize + +- SHALL collapse sidebar sections as an accordion: expanding one section collapses its siblings, the active chapter's section is exposed on page load, state is keyboard-accessible (`aria-expanded`) and persists across page loads. +- SHALL make sidebar resize reflow content (content width adapts; no fixed `max-width` trap that only shrinks the reading area) with sensible min/max bounds. + +### Mermaid contrast (fixed palette) + +- SHALL render every Mermaid node with a fixed fill+text pair drawn from the `--sk-*` documentation palette (sky, emerald, violet, amber, rose, neutral), identical in light and dark themes, with text-to-fill contrast ratio >= 4.5:1. +- SHALL render edges and edge labels in a fixed neutral color legible on both page backgrounds, with an opaque edge-label background that does not inherit the page theme. +- SHALL NOT rely on Mermaid's per-theme defaults for node text, edge color, or edge-label background. + +### Mermaid overflow + +- SHALL NOT clip text inside flowchart nodes 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. +- SHALL document authoring limits (maximum characters per line, mandatory `
` breaks, short-label guidance) in `docs/src/documentation-guide.md`. diff --git a/openspec/changes/docs-book-ux-fixes/tasks.md b/openspec/changes/docs-book-ux-fixes/tasks.md new file mode 100644 index 0000000..b4937e7 --- /dev/null +++ b/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 `
` 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 #`. From 10c20d64cf7430af79ae05190d24ddb8d7046037 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Claudino?= Date: Tue, 20 Oct 2026 13:15:35 -0300 Subject: [PATCH 2/2] docs(openspec): normalize docs-book-theme spec to valid delta format Rewrite the capability spec as parseable OpenSpec deltas: each section becomes a '### Requirement:' block with '#### Scenario:' WHEN/THEN entries, splitting the long Mermaid requirement into contrast and theme-independence requirements. Content is unchanged. --- .../specs/docs-book-theme/spec.md | 110 +++++++++++++++--- 1 file changed, 93 insertions(+), 17 deletions(-) diff --git a/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md b/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md index fc94b1d..ed8a743 100644 --- a/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md +++ b/openspec/changes/docs-book-ux-fixes/specs/docs-book-theme/spec.md @@ -1,30 +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 -### Typography scale and font-size control +### 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 -- SHALL render body prose at a 12pt-equivalent scale (root `16px`, body text at or below the current size, headings scaled proportionally). -- 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. -- SHALL keep KaTeX and Mermaid text legible at every size step (no clipping introduced by scaling). +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. -### Top-bar and content buttons +#### Scenario: Theme switch leaves diagram colors untouched -- SHALL render top-bar icon buttons as borderless ghost controls (no boxed border, no heavy background) with a subtle hover state, in both light and dark themes. -- SHALL render content `sk-btn` elements at a compact size (shorter than the current `44px` height) with consistent radius and readable labels. +- **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 -### Sidebar accordion and resize +### Requirement: Mermaid overflow containment -- SHALL collapse sidebar sections as an accordion: expanding one section collapses its siblings, the active chapter's section is exposed on page load, state is keyboard-accessible (`aria-expanded`) and persists across page loads. -- SHALL make sidebar resize reflow content (content width adapts; no fixed `max-width` trap that only shrinks the reading area) with sensible min/max bounds. +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 `
` breaks, short-label guidance) SHALL be documented +in `docs/src/documentation-guide.md`. -### Mermaid contrast (fixed palette) +#### Scenario: Long labels stay readable -- SHALL render every Mermaid node with a fixed fill+text pair drawn from the `--sk-*` documentation palette (sky, emerald, violet, amber, rose, neutral), identical in light and dark themes, with text-to-fill contrast ratio >= 4.5:1. -- SHALL render edges and edge labels in a fixed neutral color legible on both page backgrounds, with an opaque edge-label background that does not inherit the page theme. -- SHALL NOT rely on Mermaid's per-theme defaults for node text, edge color, or edge-label background. +- **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 -### Mermaid overflow +#### Scenario: Authoring limits are documented -- SHALL NOT clip text inside flowchart nodes 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. -- SHALL document authoring limits (maximum characters per line, mandatory `
` breaks, short-label guidance) in `docs/src/documentation-guide.md`. +- **WHEN** a documentation author follows `docs/src/documentation-guide.md` +- **THEN** the guide states the maximum characters per line, the mandatory `
` breaks and the short-label guidance for Mermaid nodes