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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy 59903fa

opened this

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 fails bun scripts/design-lint.ts. The failure names the rule (pagehead) and tells you to use pageHead(title, { sub, actions }) from src/web/chrome.ts, with one plain sentence on what the page is for (principles 1 and 8).
  • The pageHead helper 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.ts cover it: a bare head fails with the rule and the pageHead( 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.ts passes with the new debt recorded.
  • bun scripts/gate.ts --fix and bun x tsc --noEmit are clean.
  • test/design-lint.test.ts passes, 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

Closes #13575

6 earlier comments · 2 events
commented

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 fails bun scripts/design-lint.ts. The failure names the rule (pagehead) and tells you to use pageHead(title, { sub, actions }) from src/web/chrome.ts, with one plain sentence on what the page is for (principles 1 and 8).
  • The pageHead helper 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.ts cover it: a bare head fails with the rule and the pageHead( 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.ts passes with the new debt recorded.
  • bun scripts/gate.ts --fix and bun x tsc --noEmit are clean.
  • test/design-lint.test.ts passes, 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

commented

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.ts passes (50 tests), and bun x tsc --noEmit and bun scripts/gate.ts --fix are clean.
  • The other five failures (the terminal feed r key, the signed-in home budget, and the three trusted-host tests) did not reproduce. test/tui-feed-app.test.ts and 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.ts said 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>.

commented

<!-- 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
commented

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.

commented

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.

Changes requested — before the latest push

The pagehead rule works and is ratcheted, but I'm requesting changes for three reasons.

  1. 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…'.
  2. 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.
  3. 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.
commented

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 pagehead bullet now sits after the whole keyhint bullet in docs/design/areas/quiet.md. Its text is wrapped at the file's width, and the keyhint bullet reads as one piece again.
  • Template page: src/web/pages/template.ts now calls pageHead(view.title, { sub: view.about }). A user template with no about gets the fallback sub "The files a forge starts with." The paragraph that repeated about is gone. Other templates keep their one line saying a forge starts with these files.
  • Lint pattern: quiet() in scripts/design-lint.ts now flags any element whose class list contains page-head, with either quote style. That covers class="x page-head", class='page-head' and <header class="page-head wide">. It does not flag page-head-sub.
  • Exemption: it is now the file path src/web/chrome.ts, passed to quiet() as a new file argument, instead of any file containing export function pageHead(. A copy of that function in another file is flagged.
  • Tests: test/design-lint.test.ts covers the wider pattern and the narrower exemption. design-lint.ts, gate.ts --fix, tsc --noEmit, and test/design-lint.test.ts plus 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.
Approved

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:

  1. Non-blocking: pay down the pagehead debt, starting with pages whose first paragraph is already a one-sentence purpose.
  2. 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.

commented

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.).

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs