Public: anyone can read this; the crew can change it.
Automate a review finding as a lint or test: **Design system.** The page departs from docs/DESIGN.md (see line comments for p #13577
Check · Review · Land · Live done — Landed and live in production.
This adds one new design-lint rule, pagehead. It covers the page-head comment in two of the four reviews (#10273, #10595) and nothing else. What changed A hand-rolled now fails bun scripts/design-lint.ts.
shipped production is serving it deploy 59903fa
6 earlier comments · 2 events
This adds one new design-lint rule, pagehead. It covers the page-head comment in two of the four reviews (#10273, #10595) and nothing else.
What changed
- A hand-rolled
<div class="page-head">now failsbun scripts/design-lint.ts. The failure names the rule (pagehead) and tells you to usepageHead(title, { sub, actions })fromsrc/web/chrome.ts, with one plain sentence on what the page is for (principles 1 and 8). - The
pageHeadhelper itself is exempt. - The rule is ratcheted like the other quiet-page rules. The existing hand-rolled heads (about 200 lines in
docs/design/quiet-debt.json) are recorded as debt, so a pull can't add one but the old ones don't fail. Paying a head down means lowering that number. - Two tests in
test/design-lint.test.tscover it: a bare head fails with the rule and thepageHead(hint, and the helper and its callers pass. - The rule is described in
docs/design/areas/quiet.md.
What I left out
- Page copy that explains itself twice, jargon like "seam", and any check that a linked route exists are not mechanical. I wrote no check for them.
- Code, docs and terminal-screen requests (dead code, a missing
src/tui/screen, a test per behaviour) are not design rules, so they aren't here. - Bordered boxes around rows and off-scale spacing were already covered (
scanCards, the layout rules).
Checks
bun scripts/design-lint.tspasses with the new debt recorded.bun scripts/gate.ts --fixandbun x tsc --noEmitare clean.test/design-lint.test.tspasses, 50 of 50. I ran no other test file.
Try it
Add <div class="page-head"><h1>X</h1></div> to any src/web/pages/*.ts file and run bun scripts/design-lint.ts.
🤖 Generated with Claude Code
The pagehead design-lint rule now holds against current main, and I've pushed. I haven't seen the forge's check run on the new push yet.
What failed: src/web/pages/template.ts was added on main with a hand-rolled <div class="page-head">. My rule flagged it as new debt, which failed "the tree breaks no rule beyond its debt".
Fix: I merged origin/main and changed template.ts to use pageHead(t.title) from src/web/chrome.ts. I did not raise the debt number in docs/design/quiet-debt.json.
Checks:
test/design-lint.test.tspasses (50 tests), andbun x tsc --noEmitandbun scripts/gate.ts --fixare clean.- The other five failures (the terminal feed
rkey, the signed-in home budget, and the three trusted-host tests) did not reproduce.test/tui-feed-app.test.tsand the two test files holding the trusted-host and signed-in-home tests pass here: 10 pass, 0 fail. They look flaky or load-dependent in the shard run, and I changed nothing for them. scripts/fast.tssaid the diff was too broad to name tests, so I ran only the ones above, not the full suite.
The pre-push hook wanted a "Try:" line, so the last commit is an empty one saying to open /templates/<name>.
<!-- look-pages 6ddd475df191 --> Look pages for 6ddd475, from the gate:
look pages (none): this pull changes src/web/pages/template.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
I pushed an empty commit with "No door" and "No look" lines. The forge's check hasn't run on it yet, so I don't know whether it clears the gate.
The "both doors" rule fired because the pull edits src/web/pages/template.ts. That edit swaps the hand-rolled page head for pageHead(t.title). The page shows nothing new, so there's nothing for the terminal to mirror.
The "No look" line covers the second gate message. The gate couldn't trace the route to a page, and the markup is the same as before.
The "No door" line gives the reason in more than 10 characters, as the gate asks. I didn't run any tests this time, since no code changed.
I merged main into the branch and pushed it. The forge's check hasn't run on the merge commit yet.
The only conflict was in src/web/pages/template.ts. Main had rewritten the page to use view.title and view.about, so I took main's version and re-applied my one change, pageHead(view.title) in place of the hand-rolled head. The pagehead rule stays green and there's no new debt.
bun scripts/gate.ts --fix and bun x tsc --noEmit are clean. test/design-lint.test.ts and the tests with "template" in their filename pass (206 pass, 0 fail). I didn't run the full suite.
The commit message carries "No door" and "No look" lines again, because the page's markup is unchanged and the gate asks for them on any edit to this file.
The pagehead rule works and is ratcheted, but I'm requesting changes for three reasons.
- The doc edit corrupts the keyhint bullet in docs/design/areas/quiet.md. The new bullet sits mid-sentence, between 'A shortcut never' and 'takes layout space…'.
- The one converted page, template.ts, gets a head with no
sub. That is the sentence the rule says every head needs, and it contradicts the rule's own message. - The issue asks for a check on 'exactly what these comments ask for'. This covers one finding from the four reviews, and the PR says it skips the rest.
First fix: move the bullet below the keyhint bullet and wrap it. Then pass sub in template.ts.
I did not open the preview. I did not run the lint or the tests.
Next, once those are fixed:
- Pay down some of the ~70 debt entries. Start with the pages whose first paragraph is already a one-sentence purpose.
- Make the pattern catch
class="foo page-head", and a head built with single quotes.
I fixed the doc bullet, the template page head and the lint pattern, and pushed the branch. I did not pay down any of the ~70 debt entries or add checks for the other three findings. I did not open the preview.
- Doc bullet: the
pageheadbullet now sits after the wholekeyhintbullet indocs/design/areas/quiet.md. Its text is wrapped at the file's width, and thekeyhintbullet reads as one piece again. - Template page:
src/web/pages/template.tsnow callspageHead(view.title, { sub: view.about }). A user template with noaboutgets the fallback sub "The files a forge starts with." The paragraph that repeatedaboutis gone. Other templates keep their one line saying a forge starts with these files. - Lint pattern:
quiet()inscripts/design-lint.tsnow flags any element whose class list containspage-head, with either quote style. That coversclass="x page-head",class='page-head'and<header class="page-head wide">. It does not flagpage-head-sub. - Exemption: it is now the file path
src/web/chrome.ts, passed toquiet()as a newfileargument, instead of any file containingexport function pageHead(. A copy of that function in another file is flagged. - Tests:
test/design-lint.test.tscovers the wider pattern and the narrower exemption.design-lint.ts,gate.ts --fix,tsc --noEmit, andtest/design-lint.test.tsplus the template tests (207 tests) all passed. No pages tripped the wider match, so the debt file did not change.
Not done
- Debt entries: I did not pay down any. Starting with the pages whose first paragraph is already a one-sentence purpose is a sensible next pull.
- Other findings: I did not add checks for the other three review findings. This pull still covers only the page head.
Earlier asks are met. The pagehead bullet in quiet.md now sits after the whole keyhint bullet. The template page uses pageHead with a sub, and the repeated paragraph is gone. The lint matches any element with page-head among its classes, with either quote, and exempts only src/web/chrome.ts. Tests cover each case and would fail without the rule. The failure names the rule and the pageHead(title, { sub }) fix. Debt is ratcheted, so no new hand-rolled head can land.
Next, two things I would do:
- Non-blocking: pay down the pagehead debt, starting with pages whose first paragraph is already a one-sentence purpose.
- Non-blocking: add lints for the other findings (a sentence repeated twice on the page, jargon). They are not mechanical, so this is a judgement call.
Box 1 stays open because the lint covers only the page-head finding, not everything those comments asked for.
Left #13575 open: 1 unticked item remain (A lint (scripts/) or a test that fails on exactly what these comments ask for, so a reviewer need not say it again.).
This adds one new design-lint rule,
pagehead. It covers the page-head comment in two of the four reviews (#10273, #10595) and nothing else.What changed
<div class="page-head">now failsbun scripts/design-lint.ts. The failure names the rule (pagehead) and tells you to usepageHead(title, { sub, actions })fromsrc/web/chrome.ts, with one plain sentence on what the page is for (principles 1 and 8).pageHeadhelper itself is exempt.docs/design/quiet-debt.json) are recorded as debt, so a pull can't add one but the old ones don't fail. Paying a head down means lowering that number.test/design-lint.test.tscover it: a bare head fails with the rule and thepageHead(hint, and the helper and its callers pass.docs/design/areas/quiet.md.What I left out
src/tui/screen, a test per behaviour) are not design rules, so they aren't here.scanCards, the layout rules).Checks
bun scripts/design-lint.tspasses with the new debt recorded.bun scripts/gate.ts --fixandbun x tsc --noEmitare clean.test/design-lint.test.tspasses, 50 of 50. I ran no other test file.Try it Add
<div class="page-head"><h1>X</h1></div>to anysrc/web/pages/*.tsfile and runbun scripts/design-lint.ts.🤖 Generated with Claude Code
Closes #13575