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

Merged opened this

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

Merged

scout/forge:scout/13520-design-lint-refuses-a-fixed-pixel-width → main 1 commit fork

  • Merged. scout/13520-design-lint-refuses-a-fixed-pixel-width was merged into main as 5c691cb.

Review

Sign in to review this change.
3 files changed +124 −14
scripts/design-lint.ts +53 −14
@@ -30,9 +30,10 @@
3030 * target a button, link, input or select under 24px wide or high, WCAG 2.5.8
3131 * (specification.website, target size)
3232 *
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.
3637 *
3738 * The quiet-page rules (#8775, #8719) are held per file in `docs/design/quiet-debt.json`,
3839 * the same ratchet, and may only go down: `label` ("Status: Open"), `caps`
@@ -41,7 +42,8 @@
4142 * accent token such as `--accent-2`; only `--accent` and `--accent-fg` exist).
4243 * They match markup and style, never a paragraph's words. Named in docs/design/areas/quiet.md.
4344 *
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()`.
4547 *
4648 * `banner` (#10699) refuses a standing alert in the home and board builders; see `banner()`.
4749 *
@@ -69,10 +71,12 @@ import { STRANGER_NEVER_SEES } from "../src/design/first_five_minutes.ts";
6971 import { contrastFindings } from "../src/design/contrast.ts";
7072 import { compareLayout, layoutCounts, scanLayout } from "../src/design/layout.ts";
7173 import { motionFindings } from "../src/design/motion.ts";
74 import { PHONE_PX, widthFindings } from "../src/design/width.ts";
7275 import { cssBlocksAt, scanOverlay, sourceFiles } from "../src/design/overlay.ts";
7376
7477 // The covered-page rule lives in src/design/ so the release preflight runs it too (#11916).
7578 export { motionFindings, type MotionFinding } from "../src/design/motion.ts";
79 export { widthFindings, type WidthFinding } from "../src/design/width.ts";
7680 export { compareLayout, layoutCounts, layoutIn, scanLayout } from "../src/design/layout.ts";
7781 export { matchesClosedOverlay, overlay, overlayClassesIn, type OverlayFinding, scanOverlay, sourceFiles } from "../src/design/overlay.ts";
7882
@@ -146,7 +150,10 @@ function tokenFor(line: string): string {
146150 return "a token from docs/DESIGN.md §2 (var(--…))";
147151 }
148152
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 */
150157 export function locate(text: string): Finding[] {
151158 const code = blanked(text);
152159 const lines = code.split("\n");
@@ -246,7 +253,10 @@ export function designText(root: string): string {
246253 return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n");
247254 }
248255
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 */
250260 export function areaFiles(root: string): string[] {
251261 try {
252262 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
310320 return out;
311321 }
312322
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 */
314326 export type QuietRule = "label" | "caps" | "echo" | "inline-colour" | "keyhint" | "accent";
315327 export type QuietFinding = { line: number; rule: QuietRule; text: string; use: string };
316328 export const QUIET_RULES: readonly QuietRule[] = ["label", "caps", "echo", "inline-colour", "keyhint", "accent"];
@@ -321,7 +333,8 @@ export function quiet(text: string): QuietFinding[] {
321333 const code = blanked(text);
322334 const at = (i: number) => code.slice(0, i).split("\n").length;
323335 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.
325338 for (const m of code.matchAll(new RegExp(`>\\s*(?:Status|State)\\s*:\\s*(?=<|\\$\\{|(?:${STATUS_WORD})\\b)`, "gi"))) {
326339 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)" });
327340 }
@@ -343,7 +356,8 @@ export function quiet(text: string): QuietFinding[] {
343356 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" });
344357 }
345358 }
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.
347361 for (const m of code.matchAll(/--accent(?!-fg\b)(?:[-_][a-z0-9_-]*|\d+)(?![\w-])/gi)) {
348362 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" });
349363 }
@@ -380,7 +394,10 @@ export function quietCounts(files: Record<string, QuietFinding[]>): QuietDebt {
380394 return out;
381395 }
382396
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 */
384401 export function compareQuiet(debt: QuietDebt, files: Record<string, QuietFinding[]>): string[] {
385402 const out: string[] = [];
386403 const now = quietCounts(files);
@@ -445,7 +462,9 @@ export function scanBanner(root: string): string[] {
445462 export const CARD_ALLOW: Record<string, string> = {};
446463 export type CardFinding = { line: number; text: string };
447464
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 */
449468 function firstArg(code: string, open: number): string {
450469 let depth = 0, tpl = 0;
451470 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
498517 const STRANGER_RE = new RegExp(`(?<![A-Za-z0-9_-])(?:${STRANGER_NEVER_SEES.join("|")})(?:s|ed|ing)?(?![A-Za-z0-9_-])`, "gi");
499518 export type StrangerFinding = { line: number; word: string; text: string };
500519
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 */
502524 function stringsOf(code: string): { at: number; text: string; quote: string }[] {
503525 const out: { at: number; text: string; quote: string }[] = [];
504526 const template = (i: number): number => {
@@ -564,7 +586,10 @@ export function scanStranger(root: string): string[] {
564586 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`));
565587 }
566588
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 */
568593 export function scanMotion(root: string): string[] {
569594 const out: string[] = [];
570595 for (const f of sourceFiles(root)) {
@@ -576,6 +601,20 @@ export function scanMotion(root: string): string[] {
576601 return out;
577602 }
578603
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
579618 const BASELINE = "docs/design/baseline.json";
580619 const DESIGN = "docs/DESIGN.md";
581620 const SECTIONS = "docs/design/sections";
@@ -592,7 +631,7 @@ if (import.meta.main) {
592631 } else {
593632 const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8"));
594633 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()];
596635 for (const p of problems) console.error(p);
597636 if (problems.length) process.exit(1);
598637 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs