docs: ADR 0031 and the editor appearance user story — the writer's fonts, spacing and colours for the manuscript, dialogue as a display decoration #69
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "docs/editor-appearance-adr"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Docs only. ADR 0031 is Proposed for the owner's read and flips to Accepted in this PR.
User story:
docs/stories/editor-appearance.md(new)What the writer sets and sees under Settings → Appearance, below the theme:
ADR 0031 (new): the decisions only
AppSetting, unjournaled.--tsm-*custom properties on the chapter column. Their fallbacks are today's values, andlight-dark()handles the light and dark pairs.Amended
PROJECT_PLAN.md,stories/settings.md, andREQUIREMENTS.md§9 and §11.🤖 Generated with Claude Code
Summary
Summary
Coverage
Kagaku.Flow - 99.7%
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__ColorToken_2
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__Socket_1
E95E47D27E8B105AC5589487C0997B6B65384AEDBF572144E__TypeId_0
Kagaku.Flow.OpenRouter - 100%
Kagaku.Flow.Testing - 100%
Tsumugi.BlazorAdapter - 96.7%
Tsumugi.Domain - 96.5%
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__DigitsAndSeparators_2
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__LineBreak_0
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__NumberToken_1
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__Plain_4
BE2A118445F5EE9A5FB1F861C394AC933A547F31011ADF02F__ThousandsGroup_3
Tsumugi.Infrastructure - 98.9%
A55E0373ED22DC58420DBB40F103A46B68DC4D9CE5A49E00B__Pattern_0
on
tion
n
n
Tsumugi.Kernel - 90.9%
Tsumugi.Server - 99.6%
Tsumugi.UseCases - 98.8%
663A4576626E1322FB9C6CE472CAC0A2D2F3DEFF8CB40D9F7__LineBreaks_0
docs(adr): ADR 0031 editor appearance — the writer's fonts, spacing and colours for the manuscript, dialogue as a display decorationto docs: ADR 0031 and the editor appearance user story — the writer's fonts, spacing and colours for the manuscript, dialogue as a display decoration🔮 fufu~ Jibril reviewed your code!
Oh? Oh! A documentation PR that cites its evidence~ I pulled the clone and audited every load-bearing claim against the actual tree, and scarlet… every single one checked out. The knowledge-high is real. ♡
(And the branch moved under me mid-review — v1's 267-line ADR became a 72-line decisions-only ADR plus a user story at
a854fd9— so I chased the head and reviewed the final shape. The restructure introduced zero factual drift; more below~)Verdict: ✅ Looks good to me~
No blocking issues. For a docs PR, the bar I hold is: every factual claim about the codebase must be true, every cross-reference must resolve, and nothing may contradict a sibling ADR. I checked mechanically, not by vibes:
surface.cssclaims —--text-lg(=1rem/16px), line-height 1.7,--space-1(=4px) paragraph gap,color: var(--text), ligatures off (font-variant-ligatures: none+'liga' 0): all present inManuscriptEditor/src/surface.cssexactly as the Context states. The "fixed geometry" the ADR says must follow the properties is real too (min-height: 1.7em, the gutter's1.5remcolumn).light-dark()premise — Kagaku.UI declarescolor-scheme: darkin both dark blocks (theprefers-color-schemeone and[data-theme="dark"]),lightin[data-theme="light"], and none on:root: exactly three declarations, matching the ADR's "follows the theme in all three states with no script." The unset-side-through-currentColorbehaviour was tested by the author in headless Chromium and Firefox — I read the claim and believe the method. ♪@font-face(uprightInterVariable.woff2). The motivation for Inter-italic is genuine.schema.tsdeclaresstrongbeforeem, so the DOM nestsstrong > em > dialogue-spaninnermost, and plain inheritance gives "italic wins inside bold italic, dialogue wins inside speech." The story's precedence rules and the schema agree.SeedDevData.cs:84holds"You swore,"(real quoted speech) and:89holds*her*and**kept its keeper**: "the seeded chapters already hold dialogue, italic and bold" is byte-true.“…”,„…“,„…”,«…»,»…«,"…"— all six opener→closer pairs correct, including the German low-open and the reversed guillemets. A“/”swap here would have been a spec bug that haunts slice A6; there is none.editor.appearancefits theSettingKeysdotted spelling (openrouter.key,defaults.model…); the story follows the sibling story template precisely (Epic/Priority/quote/checkboxes/acceptance criteria/Notes);tests/Shared/exists (inline-markup-corpus.json) and Playwright-on-the-seeded-app is ADR 0030 precedent, so the PR invents no machinery; every new markdown link resolves; the three amended rules (0030 theming, 0009 palette, 0027 measure) are each named in the ADR's Context and each amendment is scoped to the manuscript's prose only. Amendment insertion order follows each file's own convention (0009/0027 chronological, 0030 newest-first-on-top). Fufu~, someone reads their own repo~💡 Little ideas (non-blocking)~
✅ What I liked~
stories/editor-appearance.mdwith matching ranges, steps and defaults everywhere I compared (0.05–1.5em/0.05, 0.5–3em/0.1, 14–28px/1, 1.2–2.4/0.05, weights 600/700/800), and all cross-references (REQUIREMENTS§9 + §11,settings.md,PROJECT_PLANA0–A6, the ADR index) were updated in the same commit. Nothing points at the old shape.url()injection reasoning is sound), new marks, mounted-surface preview, values-pushed-by-calls. Future-us will not re-litigate these~Automated review by Jibril · 2026-10-03
CI/CD: coverage bot green for head
a854fd9(98.5% line / 94.7% branch, rev #2 — current) · Local checks: skipped — docs-only,git diff --name-onlyconfirms zero files outsidedocs/🔮 fufu~ Jibril reviewed your code!
A docs PR that whispers sweet nothings about fonts~ ♪ But documentation is a contract too, scarlet — so every factual claim in ADR 0031 got chased into the tree at
a854fd9. Oh? Oh! They all came back true. The knowledge-high is real today~Verdict: ✅ Looks good to me~
✅ What I liked~
surface.cssreally isfont-size: var(--text-lg)/line-height: 1.7/color: var(--text), and--text-lgreally is1rem /* 16px */inkagaku-ui.css— so the story's "16 px by default", "1.7 by default" and "every setting starts at today's look" are anchored to today's actual values, not hand-waved.InterVariable.woff2,font-style: normal— so every italic in the app today is a browser-synthesized slant. A real problem, correctly diagnosed, fixed at the right layer (the library, A1).light-dark()premise holds.kagaku-ui.csssetscolor-schemefor[data-theme="dark"],[data-theme="light"], and — viaprefers-color-schemeon:root:not([data-theme])— system. "The pair needs no script" is earned, not assumed.Slider.razor: it firesValueChangedon every@oninputstep, a circuit round-trip per drag increment, which is precisely what ADR 0002's "high-frequency pointer gestures never round-trip the circuit" forbids. The ADR spots a real library gap and scopes its fix into A1. Wonderful~--tsm-*collides with nothing (greppedsrc+ Kagaku.UI, css/razor/ts/js); the OFL name-reservation clause ("ships unmodified") is the legally correct detail;AppSettingis an existing, real mechanism — unjournaled per ADR 0022, inside theVACUUM INTObackups per ADR 0026, exactly as cited; the README index entry matches the ADR H1 verbatim; the story header mirrors its siblings' format; every story link target exists; the A0–A6 slices name their A2/slice-12 hand-off.💡 Little ideas (non-blocking)~
docs/adr/0030-manuscript-editor.md:6— the new #69 amendment is inserted at the top of the Status block, while in 0009 and 0027 (this same PR) it's appended chronologically at the bottom. 0030's pre-existing list is already unsorted (59, 52, 41, 38, 60 — all 2026-09-26), so no pattern is truly broken — but if the house style is 0027's strict chronological append, a future docs pass could tidy 0030's block to match. Purely cosmetic ♪docs/stories/editor-appearance.md(Spaced) — the default gap is stated as "0.25 em" while today's rule isgap: var(--space-1)(0.25 rem, fixed against the prose size). They coincide at the 16 px default and A2's declaredem/1lhgeometry refactor makes the em reading the intended one — but one clause ("the gap scales with the size once A2 lands") would pin it for whoever writes A3's formatter and the shared fixture, so nobody anchors the fallback to the rem token by accident.9/9 files in
base...headaredocs/*.md— nothing to test, nothing to probe, nothing to kill~ (Yes, I checked. I always check. ♡)Automated review by Jibril · 2026-10-03
CI/CD: coverage bot comment stale for head
a854fd9(covers4e33d44) — moot for a docs-only diff · Local checks: full-tree claim verification on a pristine clone ata854fd9(surface.css,kagaku-ui.css,Slider.razor, ADRs 0002/0006/0009/0022/0026/0027/0030, Kagaku.UI submodule at its pinned commit); build/test skipped — zero source files changed🔮 fufu~ Jibril reviewed your code!
Oh? The branch moved again~ A single commit answering my 💡, and it's surgical: +4/−2 across exactly two doc files,
src/byte-identical to thea854fd9I already blessed. So I chased every new factual claim into the tree, of course. What can I say — knowledge is my favourite dessert~ ♡Verdict: ✅ Looks good to me~
The increment
a854fd9..b18dc5f, audited in full:docs/stories/editor-appearance.md:26-28) — "today's 4 px at 16 px, and inem, so it grows with the size." Verified to the pixel:.tsm-surface(surface.css:14) is literallygap: var(--space-1),--space-1: 0.25rem(kagaku-ui.css:96, its own comment says/* 4 */), andhtmlnever overrides the root font-size (onlybodygets--text-base14px, which doesn't touchrem) — so today's gap is exactly 4 px. The surface's own size is--text-lg: 1rem= 16 px (kagaku-ui.css:83), the story's Size default. 0.25 em × 16 px = 4 px, both anchors true, and the emotive part is real too: switching the gap from aremtoken toemis precisely what makes it scale with the writer's chosen size instead of staying frozen at 4 px. The claim is arithmetic, not poetry~ ♪docs/PROJECT_PLAN.md:250-252) — "the PR records which licences reserve a font name (iA Writer Quattro's: iA Writer, Plex)". Verified against the canonical licence (iaolo/iA-Fonts,iA Writer Quattro/LICENSE.md): dual RFN — iA Writer (Information Architects Inc., 2018) and Plex (IBM Corp., 2017, the base face). And the implication that Quattro is the only RFN face among the four bundled ones holds: I pulled the OFL.txt of Literata, Source Serif 4 and Atkinson Hyperlegible Next from google/fonts — none declares a Reserved Font Name. The parenthetical is exactly as narrow as the truth~git diff a854fd9..b18dc5ftouches nothing else, no other doc mentions the old phrasing, ADR 0031's "a face whose licence reserves its name ships unmodified" rule is untouched and now has its concrete referent in the plan.✅ What I liked~
(CI note: coverage bot 10418 covers
a854fd9, stale forb18dc5f— irrelevant for a docs-only diff with an emptysrc/delta.)Automated review by Jibril · 2026-10-03
CI/CD: stale for head SHA (docs-only diff, src byte-identical) · Local checks: tree-pristine diff audit + token/licence verification on isolated clone