Public: anyone can read this; the crew can change it.
design-lint refuses a fixed pixel width wider than 390 on any page rule outside a media query #13535
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13520-design-lint-refuses-a-fixed-pixel-width → main 1 commit fork
3 files
changed +124
−14
scripts/design-lint.ts +53 −14
| @@ -30,9 +30,10 @@ | ||
| 30 | 30 | * target a button, link, input or select under 24px wide or high, WCAG 2.5.8 |
| 31 | 31 | * (specification.website, target size) |
| 32 | 32 | * |
| 33 | * The layout rules (`src/design/layout.ts`, #12017) are held the same way, under `layout` in the baseline: | |
| 34 | * z-index outside the `--z-` tokens, `position: fixed` or a full-viewport box outside src/web/overlay_host.ts, | |
| 35 | * spacing off the scale. | |
| 33 | * The layout rules (`src/design/layout.ts`, #12017) are held the same way, under `layout` in the | |
| 34 | * baseline: | |
| 35 | * z-index outside the `--z-` tokens, `position: fixed` or a full-viewport box outside | |
| 36 | * src/web/overlay_host.ts, spacing off the scale. | |
| 36 | 37 | * |
| 37 | 38 | * The quiet-page rules (#8775, #8719) are held per file in `docs/design/quiet-debt.json`, |
| 38 | 39 | * the same ratchet, and may only go down: `label` ("Status: Open"), `caps` |
| @@ -41,7 +42,8 @@ | ||
| 41 | 42 | * accent token such as `--accent-2`; only `--accent` and `--accent-fg` exist). |
| 42 | 43 | * They match markup and style, never a paragraph's words. Named in docs/design/areas/quiet.md. |
| 43 | 44 | * |
| 44 | * `stranger` (#11458) names each word of `STRANGER_NEVER_SEES` that a stranger-path page says; see `strangerWords()`. | |
| 45 | * `stranger` (#11458) names each word of `STRANGER_NEVER_SEES` that a stranger-path page says; see | |
| 46 | * `strangerWords()`. | |
| 45 | 47 | * |
| 46 | 48 | * `banner` (#10699) refuses a standing alert in the home and board builders; see `banner()`. |
| 47 | 49 | * |
| @@ -69,10 +71,12 @@ import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts"; | ||
| 69 | 71 | import { contrastFindings } from "../src/design/contrast.ts"; |
| 70 | 72 | import { compareLayout, layoutCounts, scanLayout } from "../src/design/layout.ts"; |
| 71 | 73 | import { motionFindings } from "../src/design/motion.ts"; |
| 74 | import { PHONE_PX, widthFindings } from "../src/design/width.ts"; | |
| 72 | 75 | import { cssBlocksAt, scanOverlay, sourceFiles } from "../src/design/overlay.ts"; |
| 73 | 76 | |
| 74 | 77 | // The covered-page rule lives in src/design/ so the release preflight runs it too (#11916). |
| 75 | 78 | export { motionFindings, type MotionFinding } from "../src/design/motion.ts"; |
| 79 | export { widthFindings, type WidthFinding } from "../src/design/width.ts"; | |
| 76 | 80 | export { compareLayout, layoutCounts, layoutIn, scanLayout } from "../src/design/layout.ts"; |
| 77 | 81 | export { matchesClosedOverlay, overlay, overlayClassesIn, type OverlayFinding, scanOverlay, sourceFiles } from "../src/design/overlay.ts"; |
| 78 | 82 | |
| @@ -146,7 +150,10 @@ function tokenFor(line: string): string { | ||
| 146 | 150 | return "a token from docs/DESIGN.md §2 (var(--…))"; |
| 147 | 151 | } |
| 148 | 152 | |
| 149 | /** Where `countFile` counts colours and off-scale sizes: file line, the literal, the system's answer. */ | |
| 153 | /** | |
| 154 | * Where `countFile` counts colours and off-scale sizes: file line, the literal, the system's | |
| 155 | * answer. | |
| 156 | */ | |
| 150 | 157 | export function locate(text: string): Finding[] { |
| 151 | 158 | const code = blanked(text); |
| 152 | 159 | const lines = code.split("\n"); |
| @@ -246,7 +253,10 @@ export function designText(root: string): string { | ||
| 246 | 253 | return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n"); |
| 247 | 254 | } |
| 248 | 255 | |
| 249 | /** The area files under docs/design/areas/: each is wholly vocabulary, one file per component area (#4063). */ | |
| 256 | /** | |
| 257 | * The area files under docs/design/areas/: each is wholly vocabulary, one file per component area | |
| 258 | * (#4063). | |
| 259 | */ | |
| 250 | 260 | export function areaFiles(root: string): string[] { |
| 251 | 261 | try { |
| 252 | 262 | return readdirSync(join(root, AREAS)).filter((n) => n.endsWith(".md") && n !== "README.md").sort().map((n) => readFileSync(join(root, AREAS, n), "utf8")); |
| @@ -310,7 +320,9 @@ export function compare(base: Baseline, now: Scan, design: string, areas: readon | ||
| 310 | 320 | return out; |
| 311 | 321 | } |
| 312 | 322 | |
| 313 | /** The quiet-page rules a machine can check (#8775, from #8719): markup and style only, never prose. */ | |
| 323 | /** | |
| 324 | * The quiet-page rules a machine can check (#8775, from #8719): markup and style only, never prose. | |
| 325 | */ | |
| 314 | 326 | export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent"; |
| 315 | 327 | export type QuietFinding = { line: number; rule: QuietRule; text: string; use: string }; |
| 316 | 328 | export const QUIET_RULES: readonly QuietRule[] = ["label", "caps", "echo", "inline-colour", "keyhint", "accent"]; |
| @@ -321,7 +333,8 @@ export function quiet(text: string): QuietFinding[] { | ||
| 321 | 333 | const code = blanked(text); |
| 322 | 334 | const at = (i: number) => code.slice(0, i).split("\n").length; |
| 323 | 335 | const out: QuietFinding[] = []; |
| 324 | // "Status: Open": a label tag ending in a colon, straight before a status word, a tag or an interpolation. | |
| 336 | // "Status: Open": a label tag ending in a colon, straight before a status word, a tag or an | |
| 337 | // interpolation. | |
| 325 | 338 | for (const m of code.matchAll(new RegExp(`>\\s*(?:Status|State)\\s*:\\s*(?=<|\\$\\{|(?:${STATUS_WORD})\\b)`, "gi"))) { |
| 326 | 339 | out.push({ line: at(m.index!), rule: "label", text: m[0].slice(1).trim(), use: "the status glyph and colour alone, its word in title/aria-label and on the detail page (§6a)" }); |
| 327 | 340 | } |
| @@ -343,7 +356,8 @@ export function quiet(text: string): QuietFinding[] { | ||
| 343 | 356 | out.push({ line: at(m.index!), rule: "keyhint", text: m[0], use: "hintAttr(key): a tooltip on hover and an overlay on request; an inline hint only inside a menu item" }); |
| 344 | 357 | } |
| 345 | 358 | } |
| 346 | // At most one accent (docs/DESIGN.md, principles): `--accent` and `--accent-fg` exist; a second is a second voice. | |
| 359 | // At most one accent (docs/DESIGN.md, principles): `--accent` and `--accent-fg` exist; a second | |
| 360 | // is a second voice. | |
| 347 | 361 | for (const m of code.matchAll(/--accent(?!-fg\b)(?:[-_][a-z0-9_-]*|\d+)(?![\w-])/gi)) { |
| 348 | 362 | out.push({ line: at(m.index!), rule: "accent", text: m[0], use: "var(--accent) for interaction alone, and var(--fg) or var(--muted-fg) for emphasis; one accent per page" }); |
| 349 | 363 | } |
| @@ -380,7 +394,10 @@ export function quietCounts(files: Record<string, QuietFinding[]>): QuietDebt { | ||
| 380 | 394 | return out; |
| 381 | 395 | } |
| 382 | 396 | |
| 383 | /** What broke a quiet rule beyond the debt, and a debt that has been paid and not struck. Empty passes. */ | |
| 397 | /** | |
| 398 | * What broke a quiet rule beyond the debt, and a debt that has been paid and not struck. Empty | |
| 399 | * passes. | |
| 400 | */ | |
| 384 | 401 | export function compareQuiet(debt: QuietDebt, files: Record<string, QuietFinding[]>): string[] { |
| 385 | 402 | const out: string[] = []; |
| 386 | 403 | const now = quietCounts(files); |
| @@ -445,7 +462,9 @@ export function scanBanner(root: string): string[] { | ||
| 445 | 462 | export const CARD_ALLOW: Record<string, string> = {}; |
| 446 | 463 | export type CardFinding = { line: number; text: string }; |
| 447 | 464 | |
| 448 | /** The first argument of the call whose `(` is at `open`: up to the top-level comma or the close. */ | |
| 465 | /** | |
| 466 | * The first argument of the call whose `(` is at `open`: up to the top-level comma or the close. | |
| 467 | */ | |
| 449 | 468 | function firstArg(code: string, open: number): string { |
| 450 | 469 | let depth = 0, tpl = 0; |
| 451 | 470 | for (let i = open + 1; i < code.length; i++) { |
| @@ -498,7 +517,10 @@ export const STRANGER_FILES = ["src/web/pages/claim.ts", "src/web/pages/start-fo | ||
| 498 | 517 | const STRANGER_RE = new RegExp(`(?<![A-Za-z0-9_-])(?:${STRANGER_NEVER_SEES.join("|")})(?:s|ed|ing)?(?![A-Za-z0-9_-])`, "gi"); |
| 499 | 518 | export type StrangerFinding = { line: number; word: string; text: string }; |
| 500 | 519 | |
| 501 | /** The strings of `code`: [start offset, raw text with `${}` holes blanked]; nested templates are their own strings. */ | |
| 520 | /** | |
| 521 | * The strings of `code`: [start offset, raw text with `${}` holes blanked]; nested templates are | |
| 522 | * their own strings. | |
| 523 | */ | |
| 502 | 524 | function stringsOf(code: string): { at: number; text: string; quote: string }[] { |
| 503 | 525 | const out: { at: number; text: string; quote: string }[] = []; |
| 504 | 526 | const template = (i: number): number => { |
| @@ -564,7 +586,10 @@ export function scanStranger(root: string): string[] { | ||
| 564 | 586 | return STRANGER_FILES.flatMap((f) => strangerWords(readFileSync(join(root, f), "utf8")).map((w) => `${f}:${w.line} "${w.word}" in "${w.text}" → a stranger is never shown this word (docs/DESIGN.md § The first five minutes): say it in plain words`)); |
| 565 | 587 | } |
| 566 | 588 | |
| 567 | /** Calm (#12418): a transition or animation over 100 ms with no reduced-motion answer in its sheet. Not a ratchet: none is allowed. */ | |
| 589 | /** | |
| 590 | * Calm (#12418): a transition or animation over 100 ms with no reduced-motion answer in its sheet. | |
| 591 | * Not a ratchet: none is allowed. | |
| 592 | */ | |
| 568 | 593 | export function scanMotion(root: string): string[] { |
| 569 | 594 | const out: string[] = []; |
| 570 | 595 | for (const f of sourceFiles(root)) { |
| @@ -576,6 +601,20 @@ export function scanMotion(root: string): string[] { | ||
| 576 | 601 | return out; |
| 577 | 602 | } |
| 578 | 603 | |
| 604 | /** | |
| 605 | * Phone width (#13520): a fixed `width` over 390px outside a min-width media query. Not a ratchet: | |
| 606 | * none is allowed. | |
| 607 | */ | |
| 608 | export function scanWidth(root: string): string[] { | |
| 609 | const out: string[] = []; | |
| 610 | for (const f of sourceFiles(root)) { | |
| 611 | for (const css of cssBlocks(readFileSync(f, "utf8"))) { | |
| 612 | for (const m of widthFindings(css)) out.push(`${relative(root, f)}: ${m.selector} — width: ${m.px}px is wider than a phone (${PHONE_PX}px); use max-width, a fraction, or put it inside @media (min-width: …)`); | |
| 613 | } | |
| 614 | } | |
| 615 | return out; | |
| 616 | } | |
| 617 | ||
| 579 | 618 | const BASELINE = "docs/design/baseline.json"; |
| 580 | 619 | const DESIGN = "docs/DESIGN.md"; |
| 581 | 620 | const SECTIONS = "docs/design/sections"; |
| @@ -592,7 +631,7 @@ if (import.meta.main) { | ||
| 592 | 631 | } else { |
| 593 | 632 | const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8")); |
| 594 | 633 | const debt: QuietDebt = JSON.parse(readFileSync(join(root, QUIET_DEBT), "utf8")); |
| 595 | const problems = [...compare(base, now, designText(root), areaFiles(root)), ...compareQuiet(debt, scanQuiet(root)), ...scanBanner(root), ...compareLayout(base.layout ?? {}, scanLayout(root)), ...scanOverlay(root), ...scanCards(root), ...scanStranger(root), ...scanMotion(root), ...contrastFindings()]; | |
| 634 | const problems = [...compare(base, now, designText(root), areaFiles(root)), ...compareQuiet(debt, scanQuiet(root)), ...scanBanner(root), ...compareLayout(base.layout ?? {}, scanLayout(root)), ...scanOverlay(root), ...scanCards(root), ...scanStranger(root), ...scanMotion(root), ...scanWidth(root), ...contrastFindings()]; | |
| 596 | 635 | for (const p of problems) console.error(p); |
| 597 | 636 | if (problems.length) process.exit(1); |
| 598 | 637 | console.log("design: no colour, size or component added outside the system"); |
src/design/width.ts added +41
| @@ -0,0 +1,41 @@ | ||
| 1 | /** | |
| 2 | * Phone width (#13520): a fixed box wider than a phone is what makes the page | |
| 3 | * scroll sideways. A stylesheet rule with `width: <n>px` over 390 is refused | |
| 4 | * unless a `@media (min-width: …)` query encloses it. `max-width` and | |
| 5 | * `min-width` are not fixed widths and are not read. Plain data in (one | |
| 6 | * sheet's text), plain findings out. | |
| 7 | */ | |
| 8 | ||
| 9 | export type WidthFinding = { selector: string; px: number }; | |
| 10 | ||
| 11 | export const PHONE_PX = 390; | |
| 12 | ||
| 13 | const strip = (css: string): string => css.replace(/\/\*[\s\S]*?\*\//g, ""); | |
| 14 | ||
| 15 | export function widthFindings(css: string): WidthFinding[] { | |
| 16 | const out: WidthFinding[] = []; | |
| 17 | const walk = (text: string, wide: boolean): void => { | |
| 18 | let i = 0; | |
| 19 | while (i < text.length) { | |
| 20 | const open = text.indexOf("{", i); | |
| 21 | if (open < 0) return; | |
| 22 | let depth = 1, j = open + 1; | |
| 23 | while (j < text.length && depth) depth += text[j] === "{" ? 1 : text[j] === "}" ? -1 : 0, j++; | |
| 24 | const head = text.slice(i, open).replace(/^[\s;}]+/, "").trim(); | |
| 25 | const inner = text.slice(open + 1, j - 1); | |
| 26 | if (/^@keyframes\b/i.test(head)) { | |
| 27 | /* steps are not page rules */ | |
| 28 | } else if (head.startsWith("@")) { | |
| 29 | walk(inner, wide || (/^@media\b/i.test(head) && /\(\s*min-width\s*:/i.test(head))); | |
| 30 | } else if (head && !wide) { | |
| 31 | for (const d of inner.matchAll(/(?<![\w-])width\s*:\s*(\d*\.?\d+)px\b(?!\s*[-+*/])/gi)) { | |
| 32 | const px = Number(d[1]); | |
| 33 | if (px > PHONE_PX) out.push({ selector: head.replace(/\s+/g, " "), px }); | |
| 34 | } | |
| 35 | } | |
| 36 | i = j; | |
| 37 | } | |
| 38 | }; | |
| 39 | walk(strip(css), false); | |
| 40 | return out; | |
| 41 | } |
test/design-lint-width.test.ts added +30
| @@ -0,0 +1,30 @@ | ||
| 1 | import { describe, expect, test } from "bun:test"; | |
| 2 | import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; | |
| 3 | import { tmpdir } from "node:os"; | |
| 4 | import { join } from "node:path"; | |
| 5 | import { scanWidth, widthFindings } from "../scripts/design-lint.ts"; | |
| 6 | ||
| 7 | describe("design lint: no fixed width wider than a phone (#13520)", () => { | |
| 8 | test("a fixed width over 390px fails, naming the selector", () => { | |
| 9 | expect(widthFindings(`.panel { width: 480px; }`)).toEqual([{ selector: ".panel", px: 480 }]); | |
| 10 | }); | |
| 11 | test("a max-width media query does not excuse it", () => { | |
| 12 | expect(widthFindings(`@media (max-width: 700px) { .a { width: 500px; } }`).length).toBe(1); | |
| 13 | }); | |
| 14 | test("390px or less, max-width, min-width, percentages and calc pass", () => { | |
| 15 | expect(widthFindings(`.a { width: 390px; } .b { max-width: 900px; } .c { min-width: 600px; } .d { width: 100%; } .e { width: calc(100% - 500px); }`)).toEqual([]); | |
| 16 | }); | |
| 17 | test("inside a min-width media query it passes", () => { | |
| 18 | expect(widthFindings(`@media (min-width: 700px) { .a { width: 600px; } }`)).toEqual([]); | |
| 19 | }); | |
| 20 | test("the sheets of a tree are scanned, naming the file", () => { | |
| 21 | const root = mkdtempSync(join(process.env.TMPDIR ?? tmpdir(), "width-")); | |
| 22 | mkdirSync(join(root, "src/web"), { recursive: true }); | |
| 23 | writeFileSync(join(root, "src/web/a.ts"), "export const css = /* css */ `.x { width: 600px; }`;\n"); | |
| 24 | writeFileSync(join(root, "src/web/b.ts"), "export const css = /* css */ `.y { width: 300px; }`;\n"); | |
| 25 | const out = scanWidth(root); | |
| 26 | expect(out.length).toBe(1); | |
| 27 | expect(out[0]).toContain("src/web/a.ts"); | |
| 28 | expect(out[0]).toContain(".x"); | |
| 29 | }); | |
| 30 | }); |
new above
offline