Skip to content

Commit 2d4964d

Browse files
committed
docs: make the plan agree with the measurement it already records
Review found CHAT-TYPOGRAPHY.md contradicting itself in three places. One cause: D1 was corrected after measuring, and the correction was never propagated. intro "~130-character lines" → ~154, the figure actually measured T1 exit "~72 characters" → ~116, the 680px cap D1 settled on risks "no test guards this" → closed by the guards in this PR The 130 and the 72 were both written BEFORE the measurement that produced 680px; the risk bullet was true when written and stopped being true in the same commit. Rather than proofreading it again, the number is now pinned to the code: a test reads `--prose-max` out of the stylesheet and asserts the doc names that exact cap, and that no stray reference to the disproved 72-character target survives. Prose drifts from code silently — this is the only claim in the doc that a test can hold, so it holds it. Caught both directions: change the CSS without the doc (15/18), the doc without the CSS (15/18), reintroduce the old figure (15/18). The fourth comment (detachedHtml has no CSP) was written against this branch before it was rebased, when it still carried #70's commits. extension.js is no longer in this PR's diff, and the CSP + nonce landed in #70 as dc91502. 33 suites green.
1 parent 407512d commit 2d4964d

2 files changed

Lines changed: 25 additions & 6 deletions

File tree

docs/CHAT-TYPOGRAPHY.md

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ activity. This doc takes the *visual layer*, which that one deliberately left al
1010

1111
This became urgent the moment the chat could open as an editor tab (#70). In a 380px sidebar the
1212
line length is bounded by the container, so nothing looks badly wrong. At 900px it is unbounded,
13-
and the same CSS produces ~130-character lines — roughly twice the readable measure.
13+
and the same CSS produced **~154-character lines**measured, at a 900px viewport.
1414

1515
---
1616

@@ -130,8 +130,9 @@ Each ships independently and is visible on its own.
130130

131131
**T1 — measure + rhythm** *(S)*. D1 and D3. The largest perceptual change for the least code, and the
132132
one that fixes the editor tab. Ships: a wrapper max-width, `em`-based prose spacing, wider `#log`
133-
padding at editor width. **Exit:** a long answer in the editor tab holds ~72 characters per line, and
134-
the sidebar renders byte-identically to today.
133+
padding at editor width. **Exit:** a long answer in the editor tab holds **~116 characters** per line
134+
(the 680px cap of D1, down from ~154), and the sidebar renders byte-identically to today — verified by
135+
comparing computed styles against `develop` at 520px, not by eye.
135136

136137
**T2 — the reading type scale** *(S)*. D2 and D4. Ships: the prose size/leading custom properties and
137138
the widened heading scale. **Exit:** h1/h2/h3 are distinguishable at a glance in a screenshot with no
@@ -157,9 +158,11 @@ by itself is the cheapest way to find out before spending effort on T2–T4.
157158
- **Theme variance.** Inline-code colour already comes from the theme rather than from us (§1), so
158159
any judgement about "busy" colour must be checked across the light, dark and high-contrast themes
159160
the `webviewCss` suite already reasons about — not just the default.
160-
- **No test currently guards the measure.** `webviewCss.test.js` pins hidden-attribute defeats and the
161-
session-card overflow; it should gain a guard that the prose column is bounded, or T1 will regress
162-
silently the first time someone refactors the log container.
161+
- **~~No test currently guards the measure.~~ Closed by T1.** `webviewCss.test.js` now asserts the
162+
column is bounded, that the cap covers every child of the log rather than just `.msg`, that it stays
163+
an absolute length (not `ch`), and that the rhythm change stays width-gated. The risk was real: this
164+
regression is invisible in a sidebar, so whoever refactors the log container would not see it break —
165+
a user with the chat in an editor tab would.
163166
- **Screenshots are not measurements.** Everything here is derived from our own CSS plus a
164167
side-by-side comparison. The specific numbers (72ch, 14px, 1.65) are considered starting points to
165168
be tuned against the real thing at real widths, not values copied from the reference — we cannot

extensions/levelcode-ai/test/webviewCss.test.js

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,22 @@ test('TRANSCRIPT: the prose column is bounded, and every child shares the one me
268268
'the measure should be an absolute length, not `ch` — see CHAT-TYPOGRAPHY.md D1');
269269
});
270270

271+
test('TRANSCRIPT: the design doc quotes the SAME measure the stylesheet ships', () => {
272+
// Review found the doc contradicting itself in three places: the cap was corrected in D1 after
273+
// measuring, and the intro, the exit criterion and the risks list kept the pre-measurement numbers.
274+
// Prose drifts from code silently, so the one number that matters is pinned to the code instead of
275+
// to a proofread.
276+
const doc = fs.readFileSync(path.join(__dirname, '..', '..', '..', 'docs', 'CHAT-TYPOGRAPHY.md'), 'utf8');
277+
const shipped = /--prose-max:\s*(\d+)px/.exec(css);
278+
assert.ok(shipped, 'the stylesheet no longer declares --prose-max');
279+
280+
assert.ok(doc.includes('**Target ' + shipped[1] + 'px**'),
281+
'CHAT-TYPOGRAPHY.md D1 does not name the ' + shipped[1] + 'px cap the stylesheet actually ships');
282+
// And no stray reference to the estimate that measuring disproved.
283+
assert.ok(!/~72 characters per line/.test(doc),
284+
'the doc still quotes the pre-measurement 72-character target somewhere');
285+
});
286+
271287
test('TRANSCRIPT: the looser rhythm is gated to reading width, so the sidebar is untouched', () => {
272288
// T1's exit criterion is that a narrow panel renders exactly as before — a user who upgrades and
273289
// never opens the editor tab should see nothing move. Verified against develop's computed styles

0 commit comments

Comments
 (0)