pi-pocket 0.26.0 → 0.27.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +1 -1
- package/docs/design/design-system.md +165 -0
- package/docs/design/ds-notes-b.md +61 -0
- package/docs/design/ds-notes-g.md +170 -0
- package/docs/design/ds-notes-t.md +303 -0
- package/docs/design/ds-notes-u.md +220 -0
- package/docs/design/ds-notes-v.md +186 -0
- package/docs/design/ds-rounds.md +160 -0
- package/docs/design/ds-u-bridge.patch +732 -0
- package/docs/examples/design-system/README.md +15 -0
- package/docs/examples/design-system/pocket/.pi/design/components/badge.html +112 -0
- package/docs/examples/design-system/pocket/.pi/design/components/button.html +203 -0
- package/docs/examples/design-system/pocket/.pi/design/components/card.html +125 -0
- package/docs/examples/design-system/pocket/.pi/design/components/code-block.html +155 -0
- package/docs/examples/design-system/pocket/.pi/design/components/input.html +156 -0
- package/docs/examples/design-system/pocket/.pi/design/components/menu-row.html +167 -0
- package/docs/examples/design-system/pocket/.pi/design/components/notice.html +171 -0
- package/docs/examples/design-system/pocket/.pi/design/components/segmented.html +120 -0
- package/docs/examples/design-system/pocket/.pi/design/components/switch.html +117 -0
- package/docs/examples/design-system/pocket/.pi/design/components/tool-step.html +163 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/components.css +730 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/names.md +495 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tailwind.css +1132 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.css +1126 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.dark.resolved.json +2022 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.high-contrast.resolved.json +2022 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.light.resolved.json +2022 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.resolved.json +371 -0
- package/docs/examples/design-system/pocket/.pi/design/dist/tokens.studio.json +5915 -0
- package/docs/examples/design-system/pocket/.pi/design/guidelines.md +81 -0
- package/docs/examples/design-system/pocket/.pi/design/tokens.dark.json +182 -0
- package/docs/examples/design-system/pocket/.pi/design/tokens.high-contrast.json +185 -0
- package/docs/examples/design-system/pocket/.pi/design/tokens.json +2034 -0
- package/docs/features.md +6 -2
- package/docs/index.md +1 -0
- package/docs/map.md +34 -25
- package/docs/release-notes.md +1 -1
- package/docs/releases.md +45 -0
- package/package.json +2 -1
- package/src/server/design/check-cli.ts +283 -0
- package/src/server/design/color.ts +654 -0
- package/src/server/design/components.ts +328 -0
- package/src/server/design/docsite-assets.ts +29 -0
- package/src/server/design/docsite-color-section.ts +366 -0
- package/src/server/design/docsite-color.ts +303 -0
- package/src/server/design/docsite-components.ts +89 -0
- package/src/server/design/docsite-core.ts +634 -0
- package/src/server/design/docsite-css-base.ts +397 -0
- package/src/server/design/docsite-css-content.ts +477 -0
- package/src/server/design/docsite-css-phone.ts +251 -0
- package/src/server/design/docsite-css-reference.ts +374 -0
- package/src/server/design/docsite-css-specimens.ts +465 -0
- package/src/server/design/docsite-js-code.ts +96 -0
- package/src/server/design/docsite-js-core.ts +72 -0
- package/src/server/design/docsite-js-demos.ts +24 -0
- package/src/server/design/docsite-js-links.ts +25 -0
- package/src/server/design/docsite-js-nav.ts +73 -0
- package/src/server/design/docsite-js-stages.ts +81 -0
- package/src/server/design/docsite-js-table.ts +81 -0
- package/src/server/design/docsite-markdown.ts +221 -0
- package/src/server/design/docsite-motion.ts +110 -0
- package/src/server/design/docsite-reference.ts +269 -0
- package/src/server/design/docsite-sanitize.ts +193 -0
- package/src/server/design/docsite-shadows.ts +45 -0
- package/src/server/design/docsite-space.ts +289 -0
- package/src/server/design/docsite-type.ts +167 -0
- package/src/server/design/docsite.ts +508 -0
- package/src/server/design/export.ts +86 -9
- package/src/server/design/fix.ts +666 -0
- package/src/server/design/guide.ts +137 -22
- package/src/server/design/index.ts +368 -15
- package/src/server/design/lint-color.ts +293 -0
- package/src/server/design/lint-page-checks.ts +204 -0
- package/src/server/design/lint-page-elements.ts +252 -0
- package/src/server/design/lint-page-focus.ts +165 -0
- package/src/server/design/lint-page-literals.ts +293 -0
- package/src/server/design/lint-page-setup.ts +102 -0
- package/src/server/design/lint-page-states.ts +121 -0
- package/src/server/design/lint-page-values.ts +329 -0
- package/src/server/design/lint-page.ts +101 -0
- package/src/server/design/lint-suggest.ts +340 -0
- package/src/server/design/lint.ts +1136 -0
- package/src/server/design/render.ts +369 -18
- package/src/server/design/scan-braces.ts +115 -0
- package/src/server/design/scan-categorize.ts +187 -0
- package/src/server/design/scan-channels.ts +113 -0
- package/src/server/design/scan-color-base.ts +209 -0
- package/src/server/design/scan-color-names.ts +403 -0
- package/src/server/design/scan-color-palette.ts +91 -0
- package/src/server/design/scan-color-roles.ts +565 -0
- package/src/server/design/scan-colors.ts +22 -0
- package/src/server/design/scan-facts-antd.ts +171 -0
- package/src/server/design/scan-facts-files.ts +300 -0
- package/src/server/design/scan-facts-lists.ts +538 -0
- package/src/server/design/scan-facts-sass.ts +113 -0
- package/src/server/design/scan-facts-theme.ts +400 -0
- package/src/server/design/scan-facts-use.ts +674 -0
- package/src/server/design/scan-facts-wordpress.ts +374 -0
- package/src/server/design/scan-facts.ts +285 -0
- package/src/server/design/scan-files.ts +384 -0
- package/src/server/design/scan-import-convert.ts +277 -0
- package/src/server/design/scan-import-eval.ts +583 -0
- package/src/server/design/scan-import-material.ts +745 -0
- package/src/server/design/scan-import-sd-config.ts +370 -0
- package/src/server/design/scan-import-sd.ts +381 -0
- package/src/server/design/scan-import-studio.ts +242 -0
- package/src/server/design/scan-import.ts +336 -0
- package/src/server/design/scan-infer.ts +313 -0
- package/src/server/design/scan-js-eval.ts +1267 -0
- package/src/server/design/scan-palette.ts +485 -0
- package/src/server/design/scan-parse.ts +1134 -0
- package/src/server/design/scan-prepare.ts +402 -0
- package/src/server/design/scan-render-pages.ts +367 -0
- package/src/server/design/scan-render-probe.ts +229 -0
- package/src/server/design/scan-render.ts +524 -0
- package/src/server/design/scan-review.ts +54 -0
- package/src/server/design/scan-roles.ts +259 -0
- package/src/server/design/scan-sass-colors.ts +275 -0
- package/src/server/design/scan-sass-eval.ts +269 -0
- package/src/server/design/scan-sass-expr.ts +911 -0
- package/src/server/design/scan-sass-modules.ts +353 -0
- package/src/server/design/scan-sass-run.ts +1003 -0
- package/src/server/design/scan-sass-stmt.ts +256 -0
- package/src/server/design/scan-sass-values.ts +886 -0
- package/src/server/design/scan-scales.ts +983 -0
- package/src/server/design/scan-tailwind.ts +34 -0
- package/src/server/design/scan-theme-shapes.ts +579 -0
- package/src/server/design/scan-tree.ts +290 -0
- package/src/server/design/scan-util.ts +44 -0
- package/src/server/design/scan-variables.ts +470 -0
- package/src/server/design/scan.ts +703 -0
- package/src/server/design/system-schema.ts +68 -0
- package/src/server/design/system-types.ts +279 -0
- package/src/server/design/system.ts +510 -82
- package/src/server/design/tokens-base.ts +123 -0
- package/src/server/design/tokens-compile.ts +440 -0
- package/src/server/design/tokens-dtcg.ts +354 -0
- package/src/server/design/tokens-io.ts +417 -0
- package/src/server/design/tokens-model.ts +1163 -0
- package/src/server/design/tokens-names.ts +112 -0
- package/src/server/design/tokens-ramps.ts +112 -0
- package/src/server/design/tokens-summary.ts +317 -0
- package/src/server/design/tokens-tailwind.ts +324 -0
- package/src/server/design/tokens-values.ts +921 -0
- package/src/server/design/tokens.ts +533 -0
- package/src/server/docs.ts +8 -0
- package/src/server/extensions/artifacts.ts +87 -2
- package/src/server/extensions/design/app.js +280 -0
- package/src/server/extensions/design/canvas.js +142 -17
- package/src/server/extensions/design/check.js +656 -0
- package/src/server/extensions/design/color.js +383 -0
- package/src/server/extensions/design/data.js +102 -7
- package/src/server/extensions/design/devices.js +26 -0
- package/src/server/extensions/design/docks.js +117 -3
- package/src/server/extensions/design/index.js +171 -219
- package/src/server/extensions/design/messages.js +49 -0
- package/src/server/extensions/design/parts.js +15 -1
- package/src/server/extensions/design/paths.js +4 -0
- package/src/server/extensions/design/picker.js +123 -0
- package/src/server/extensions/design/specimen.js +55 -0
- package/src/server/extensions/design/state.js +72 -7
- package/src/server/extensions/design/style.css +546 -0
- package/src/server/extensions/design/system-actions.js +214 -0
- package/src/server/extensions/design/system-api.ts +62 -0
- package/src/server/extensions/design/system-data.js +315 -0
- package/src/server/extensions/design/system-preview.js +41 -0
- package/src/server/extensions/design/system-routes.ts +1122 -0
- package/src/server/extensions/design/system-sections.js +1344 -0
- package/src/server/extensions/design/system-ui.js +32 -0
- package/src/server/extensions/design/system-view.js +1196 -0
- package/src/server/extensions/design/system-widgets.js +942 -0
- package/src/server/extensions/design/system.css +2313 -0
- package/src/server/extensions/design/system.js +1479 -0
- package/src/server/extensions/design/unsaved.js +20 -0
- package/src/server/extensions/design/views.js +2 -2
- package/src/server/extensions/design/workspace.js +200 -105
- package/src/server/extensions/design.ts +89 -6
- package/src/server/extensions/updates/index.js +31 -9
- package/src/server/extensions/updates/style.css +11 -0
- package/src/server/extensions/updates.ts +29 -1
- package/src/server/host.ts +4 -1
- package/src/server/http/artifact-inspect.ts +338 -24
- package/src/server/updates.ts +235 -53
- package/src/server/versions.ts +71 -0
- package/web/artifact-bridge.js +34 -1
- package/npm-shrinkwrap.json +0 -3162
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
# Stream U: the System view
|
|
2
|
+
|
|
3
|
+
Branch `ds/ui`. The design system as a place to work in, inside the Design workspace: sections of tokens, edits in place that show live on the open design, undo and redo, Save and Discard, a page check with pins and Send to Pi, the documentation page, the files for code, focus mode, and the phone's frame.
|
|
4
|
+
|
|
5
|
+
## How to look at it
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
node test/serve-design-system.ts 8913 127.0.0.13 # a throwaway copy with designs and a system ("Harbor")
|
|
9
|
+
node test/serve-design-system.ts 8913 127.0.0.13 --no-system
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
It prints sign-in links for an owner, a guest, and a viewer, and a kill command. Open the Design panel, then the first row of the picker ("Design system"), `/design-open system`, or the launcher action "Open the design system". The hooks that tests and the bench can use: `.dsy-main` (the view), `.dsy-tabs [role=tab]` (the sections), `[data-token="color.bg.surface"]` (a token's row or tile), `.dsy-savebar`, `.dsy-preview` (the open design beside the view).
|
|
13
|
+
|
|
14
|
+
## What is built
|
|
15
|
+
|
|
16
|
+
Server (`src/server/extensions/design/`, called from `design.ts`):
|
|
17
|
+
|
|
18
|
+
- `system-routes.ts`: the routes (all through `web.conversationRoute`; read = view access, write = steer access). Under `/api/x/design/c/:conversation/`:
|
|
19
|
+
- `GET system` (`?revision=` answers `{ unchanged }`): `{ system, legacy }`. `system` is the loaded system without the generated files (only the components' CSS, and the sizes of the four files); `legacy` is the size of `.pi/design-system.md` when `.pi/design/` is absent.
|
|
20
|
+
- `POST system` (steer): `{ set?, modes?, guidelines?, baseRevision? }`. `set` is `[{ mode, token, value }]` (500 at most; a name of up to 8 segments of `[A-Za-z0-9_-]`, never `__proto__`, `constructor`, or `prototype`; a value of text, a number, a boolean, a list of up to 32, or an object of up to 32 keys, 5 deep, 8 KB). `modes` adds (`{}`) or removes (`null`) a mode. `guidelines` is text up to 16,000 characters without control characters. A save that the engine refuses answers **200 with `{ ok: false, error, problems }`** (a module's route error carries only words, so the structured problems go in the body); a stale `baseRevision` answers 409 and writes nothing. Saves for one folder go one at a time. Success: `{ ok: true, system }`, and the event `system` goes to every tab.
|
|
21
|
+
- `POST system/check` (steer): `{ id, version?, colorScheme?, viewport? }` → `{ report, id, version }`. The report is cut to a fixed shape (300 findings, text lengths, the 12 rules, numbers finite).
|
|
22
|
+
- `POST system/docs` (steer): `{ key }` → `{ id: "design-system-docs", version }`. Writes a new version of that artifact (HTML, with the page's assets by hash) in one commit; the same key finds its version. Refused (409) while the system has an error.
|
|
23
|
+
- `POST system/export` (steer): writes `exports/<name>-tokens.zip` (`tokens.css`, `tailwind.css`, `tokens.resolved.json`, `components.css`, from the engine's compile) and answers `{ path, relative, name, size }`; the browser downloads it through core's route. Refused (409) while the system has an error.
|
|
24
|
+
- `system-api.ts`: the one import of the engines (see "The engines").
|
|
25
|
+
|
|
26
|
+
Browser module (`src/server/extensions/design/`):
|
|
27
|
+
|
|
28
|
+
- `system.js`, `color.js`, `specimen.js`: pure logic with tests. `system.js` has the sections and groups, the model (saved values with the person's edits laid over them, aliases followed, loops found), contrast (declared pairs, or worked out for text colors), the history of edits (undo, redo, steps of one thing merged within 1.2 s, 500 kept), the change a save sends, and the CSS custom properties a design is told. `color.js` reads every form a token file has (hex, rgb, hsl, oklch, oklab, `color(srgb …)`, the 2025.10 objects) and measures WCAG 2.2 contrast. `specimen.js` makes the page of a component's states.
|
|
29
|
+
- `system-view.js` (bar, section tabs, modes, menu, problems, save bar, the open design beside it), `system-sections.js` (Colors with an overview card, roles, and palette ramps; Type; Spacing; Radii; Shadows; Motion with playable durations and easings; Other; Components; Guidelines), `system-widgets.js` (swatch, copy-name, badge, number and color fields, curve, alias picker, the token editor), `system-actions.js`, `system-data.js`, `system-preview.js`, `picker.js` (the design picker, with the pinned item, moved out of `workspace.js`), `check.js` (the Check dock).
|
|
30
|
+
- The state is in `state.js` (`systemState()`), so going back to the chat on a phone leaves the view as it was, unsaved edits included.
|
|
31
|
+
|
|
32
|
+
Also fixed, as asked:
|
|
33
|
+
|
|
34
|
+
- **The phone's frame on a phone.** The canvas size is `auto` until a person picks one: it follows the panel (under 700 px the phone's frame, under 1000 the tablet's, else the desktop's). An explicit pick is kept as before; `auto` is never saved.
|
|
35
|
+
- **Focus mode.** A button in both bars (only where the panel is beside the chat, 1100 px and up) hides the conversation and gives the panel the whole width (`html[data-dsn-focus]` in `style.css`). With the room the view and the open design sit side by side (from 900 px of panel).
|
|
36
|
+
|
|
37
|
+
## How it behaves
|
|
38
|
+
|
|
39
|
+
- **Edits** are a list of steps (`{ mode, token, raw }`), never written until Save. An edit that puts a saved value back changes nothing and is left out of the count and the save. A mode that takes the default's value follows an edit of the default (as far as the saved values can tell). Editing a token that links to another replaces the link; "Link to a token" opens a searchable list of the tokens of the same type that do not lead back. "Match Light" gives a mode the default's value. A color is written back as hex, in the dialect of the value it replaces (text, or the 2025.10 object).
|
|
40
|
+
- **Live preview.** `system-preview.js` computes, from the system and the steps, the custom properties to show; the canvas sends them through `pocket-tweak-set` in batches of 100 (the bridge's limit), with `null` to take one away. It sends the tokens that vary between modes (set to the mode in view, so a page that follows the OS's dark setting still shows the mode in view) and the tokens that differ from the saved default. A design on the canvas outside the view keeps showing unsaved edits (with a banner) in the default mode until they are saved or given up.
|
|
41
|
+
- **Components** are shown in a frame per component and mode, `sandbox="allow-same-origin"` (no scripts; the same origin only so that the page can read the frame's height), a CSP of `default-src 'none'`, markup without `script`, `meta`, `link`, `base`, `iframe`, `object`, `embed`, `form`, and CSS that cannot end its own `<style>`.
|
|
42
|
+
- **Check.** The Check tab of a design (people who steer) runs `POST system/check`, lists findings (pin number, rule, level, message, value → suggestion, the element), pins them with `pocket-highlight`, and **Send N to Pi** puts one message in the message box (each finding as JSON in a fence that nothing in it can end, marked as data from the page). It leaves the comment pins alone while it is open.
|
|
43
|
+
- **Viewers** see everything and change nothing: no undo, no save bar, no alias links, no check, no publish or export, no ask to Pi.
|
|
44
|
+
- **Not set up.** A project with no `.pi/design/` shows what to do: ask Pi to scan the project (or, with `.pi/design-system.md`, to convert it). A session with no designs has a way to the view from its empty page.
|
|
45
|
+
- **Safety.** Everything from project files is data: names, descriptions, and values are text nodes; styles that use a value pass `safeCss` (no `;{}<>\`, `url(`, `@`, comments, over 400 characters); the bridge names are checked with its own pattern and values over 200 characters are left out (a refused batch changes nothing); the message to Pi uses fences and one-line cuts.
|
|
46
|
+
|
|
47
|
+
## Tests
|
|
48
|
+
|
|
49
|
+
- `test/design-system-parts.test.ts`: color reading and contrast, sections and groups, search, edits through aliases, loops, inherited modes, contrast, roles, typed values, undo and redo and the cap, the change of a save, preview CSS and `safeCss`, specimen pages with hostile markup, font stacks.
|
|
50
|
+
- `test/design-system-routes.test.ts`: access (view, steer, one-session guest), the revision, no system and the old file, a linked folder, saves and their refusals, a stale revision, the shape checks of every field, guidelines and modes, the check and its report cut, publishing (once for each key, assets by hash), the zip and its download, a system with an error.
|
|
51
|
+
- `test/design-system-ui.test.ts` (real Chromium, 26 tests): the picker and every section; copy; live preview through the frame bridge (the page reports its button's color), undo, redo, discard, save; links; modes and side by side; typing checks; sizes, easings, and Ask Pi for a shadow; search; component frames; guidelines; a conflict; a refused save; the check and Send to Pi; publish and export from the menu; modes from the menu; a viewer; no system and the old file; an error in the system; focus mode; a phone (fits, the open design a tap away, the phone's frame, no overflow); `/design-open system` and the launcher; Ctrl+Z, Ctrl+Shift+Z, and Ctrl+S; Discard asking again, and Save saying what it wrote.
|
|
52
|
+
- `test/design-system-fixtures.ts` (the "Harbor" system and a page that uses it) and `test/serve-design-system.ts`.
|
|
53
|
+
- Run on the merged tree at the last commit: `npm run format` changes nothing, `npm run check` and `npm run lint` pass, and `npm test` passes 1167 of 1167 (the three `design-system-*` files hold 59 of them).
|
|
54
|
+
|
|
55
|
+
## Round 2: the integrator's review
|
|
56
|
+
|
|
57
|
+
- **The check's scheme.** The page in the canvas follows the app's dark scheme, so a check that ran in Light put its pins on colors that a person could not see. The check now **defaults to what the canvas shows**: its color scheme (the app's) and the size of its frame (`checkOptions` in `check.js`; the options are `null` until a person picks, and then follow the canvas). If a person picks the other scheme, the dock says that the canvas shows the other one and that the pins are for the checked one. The canvas is not forced into the checked scheme: a design is a page that this view does not control.
|
|
58
|
+
- **The sections at a panel's width.** At about 650 px (the panel beside the chat) the nine sections now fit one row: the counts show only on the section in use, and the tabs are closer; if they still do not fit, they wrap to a second row, so none runs off the edge. A phone scrolls them, with the one in use brought to the middle. A test checks that every section is inside the panel at that width.
|
|
59
|
+
- **The warnings box.** A warning is one line with a count (`⚠ 2 warnings Show ⌄`) until a tap, at every width; an error is open where there is room, and one line on a phone. A test checks that the first token is in the first screen on a phone.
|
|
60
|
+
- Also: a color that is the same in every mode shown has one swatch, one value, and one badge (the flagship has hundreds); a component lists 8 of its tokens and says how many more; the contrast of a color with no declared pair is worked out only for plain text on the page (`primary`, `secondary`, `muted`, `link`…): `inverse`, `faint`, `disabled` and the like sit on other grounds, which only a declared pair can say (the flagship has several, and the first version marked them as failing); a phone with a system that has custom mode names gets a list of modes in place of the buttons; `--flagship` for `test/serve-design-system.ts` shows Pi Pocket's own system.
|
|
61
|
+
|
|
62
|
+
## Round 3: the integrator's second review
|
|
63
|
+
|
|
64
|
+
The judges gave people 6, enforcement 7, accessibility 7. The eight items, and what was done.
|
|
65
|
+
|
|
66
|
+
1. **Roles first, the palette after.** `groupsOf` (system.js) now orders every section as semantic tokens, then primitives, then a component's own tokens. Primitives start folded when the section has semantic tokens too; component tokens always start folded. Colors shows **Roles** as compact cards (swatch, short name, value, the contrast badge with its words when it fails). Every ramp goes into **one folded "Palette" group** as a strip: one row per ramp, swatches side by side, a tap opens the editor under the strip. **Component colors** is a second folded group. Type folds its sizes, families, weights and line heights under the styles; motion, spacing, radii, shadows and Other do the same with their component tokens. A group that has the same title in two tiers says the tier (`Durations · semantic`). A search opens every folded group that has a match, and a tap on a token from elsewhere (a component's "used" list, a problem) unfolds its group.
|
|
67
|
+
2. **The color overview is neutral.** It is a card made only of the system's roles: "Card title", "Body text reads at a glance.", "Muted text for the details.", a Primary and a Secondary button, and an Error, Warning and Success chip. It says nothing about ferries. It shows one card for each mode shown.
|
|
68
|
+
3. **Phone Check is a sheet.** On a narrow panel the Check dock is a bottom sheet of 62 % of the room, with a handle. The handle takes a drag (it settles on 34, 62 or 90 %), a tap (the next height), and the arrow keys; it is a `separator` with a value. The page stays visible above. Each finding has a pin button with a name ("Show finding 3 on the page"); a tap on the finding marks it, sets the canvas back to Fit, and asks the frame to scroll that element into view and ring its pin (a new `reveal` flag on a `pocket-highlight` target, see B below).
|
|
69
|
+
4. **Two tiles named "shadow".** Radii and shadow tiles are named by the shortest tail of the path that tells them apart: `lift`, and `card.shadow` against `menu.shadow` (`tails` in system.js; a test checks it).
|
|
70
|
+
5. **One count.** A tab says the number of tokens in its section; the rule is the docs page's: **every token is in exactly one section (`sectionOf`, the same function in system.js and in `docsite.ts`), whatever its tier, and a component's own tokens count too.** The sections add up to the system's tokens (the flagship: Colors 211, Other 54, Type 33, Motion 30, Spacing 28, Radii 18, Shadows 6 = 380), and a tab's number is what its section lists, folded groups included. G wrote the same rule in `ds-notes-g.md`; `sectionCounts` has a test that the sums agree. (The first version here left out component tokens and said 149; G's page and a tab that lists 211 colors would not agree, so that rule was dropped.)
|
|
71
|
+
6. **The picker's name on a phone.** The picker keeps 142 px, the mode list gives way (108 px, and its words are short: "Both modes"), and a test checks at 360 px that "Design system" is not cut.
|
|
72
|
+
7. **The pin badge.** The bridge's `update` (B's file) now puts a badge where it covers no text: above the element, else to its left, right, below, or inside its right edge; a place is free when no text of the page and no picture lies under it. A pin keeps its place while that stays free (a scroll moves all together).
|
|
73
|
+
8. **Keyboard and screen reader.** The nine sections are one tab stop with the arrow keys, Home and End (`role=tablist`, roving `tabindex`, `aria-controls`, a `tabpanel`). A two-pixel focus ring on every control of the view, the bars and the docks. Role cards are named with their value and contrast ("color.text.primary, #1c1e26, contrast 16.6:1 AAA"); strips with the token and value; the pins are buttons. A `role=status` region that is always in the page says a save ("Saved 1 change · tokens.css 9.1 KB") and the result of a check ("Checked version 1: 4 errors and 5 warnings."); refusals keep their `alert`. Tests: the tab order and rings of the main controls in the view and the dock, the arrow keys, the live regions, the sheet's three heights, and the 360 px picker.
|
|
74
|
+
|
|
75
|
+
### Round 3, second judge: three more items
|
|
76
|
+
|
|
77
|
+
1. **The check offers every mode of the system.** The Check dock lists the modes that the system has (the flagship: Light, Dark, High contrast), as buttons, or as a list when there are more than three or a phone cannot fit them. The route `system/check` takes `mode` (refused with the engine's words when the system has no such mode) and checks the page against that mode, in the color scheme the system gives it (`schemes`); the check kept for a design is per mode and size. The mode that the dock starts at is the one of the canvas: the page in the canvas follows the app's theme, or the backdrop when a person chose Light or Dark there (the frame now has that `color-scheme`, so the backdrop in the zoom bar and in the menu changes the page, not only what is behind it). When that mode changes while the dock is open (the app's theme, or the backdrop), a check that was made is made again in the new mode, unless that mode was checked already. A mode that a person picked in the dock is theirs: the canvas changes, nothing runs, and the dock says that the canvas shows another mode, with "Follow the canvas". The app's theme is kept in the store (`appDark`), so what depends on it draws again when it changes. The message to Pi names the mode ("high-contrast mode").
|
|
78
|
+
2. **The sections on a phone.** The bar of sections and the two buttons (the open design, the search) were one scroll bar with the buttons laid over its end, so the last tab showed half behind them. They are side by side now: the sections scroll in their own bar (it fades where more is out of sight), and the buttons stay at its end. On a phone only the section in use shows its count, so that four or five sections fit. A test checks that the bar and the buttons do not overlap at 390 px.
|
|
79
|
+
3. **The slow test.** "A system with an error says so at the top…" took 1.4 to 5 s alone here, and 11 to 14 s with four copies in parallel; it could not be made to take 32 s. What it spends is full page loads: three `go()`s, each of which loads the whole app, and a full run has a few dozen browsers doing that at once, so that on a busy machine the load alone can pass the 30 s that a `go` allows. The test now swaps the session inside the page (`navigate` of `store.js`, the way a tap on a session row does) and takes 0.2 to 3 s, also when four run together. The older 32 s in `r1-test.log` was a failure of the first round's version of this test ("Timed out waiting for the row"), which is gone. Two other tests had counted on the page that an earlier test left behind (the focus mode, the design that the view follows): they set that up themselves now.
|
|
80
|
+
|
|
81
|
+
### What B must know (these are B's files; U changed them)
|
|
82
|
+
|
|
83
|
+
`src/server/http/artifact-inspect.ts` and `web/artifact-bridge.js` changed, because pin placement is there. The change is `docs/design/ds-u-bridge.patch`. If B's branch changed the same lines, keep B's and apply the patch again: **(a)** `findPlace` and `covered` in `updatePins` put a pin where it covers no text (the first draft ran its hit tests on every frame for every pin: 148 ms a frame for 100 pins in view; now a place is found when a pin first shows, and again only when its element's place on the page or its size changes, when the content changes (a mutation observer, at most once a second), when the page is resized (a resize observer), or when the place leaves the screen; a frame spends at most 3 ms on first places, and a pin is hidden until it has one; a frame reads all the rectangles first and writes all the styles after, by `transform`, and only the ones that changed). Measured in Chromium on a long page, 1200 rows, 100 pins, scrolled by 40 px a frame: median 0.3 ms, 95th percentile 0.4 ms, worst 5.3 ms a frame. With all 100 pins on the screen at once (rows 9 px high): median 4.2 ms, 95th percentile 8.3 ms (the code before pin placement: 20 ms); **(b)** a `pocket-highlight` target may carry `reveal: true` (checked as a boolean in `checkAppMessage`): the page scrolls that element into view and draws its pin and outline stronger. `test/design-bridge-ui.test.ts` has two new lines for (b), and a test that a quiet page and a small scroll make no hit tests.
|
|
84
|
+
|
|
85
|
+
### What G must know
|
|
86
|
+
|
|
87
|
+
Nothing changed in `docsite.ts`. The count rule above is the one in `ds-notes-g.md`.
|
|
88
|
+
|
|
89
|
+
### Weak after round 3
|
|
90
|
+
|
|
91
|
+
- A tapped finding resets the zoom to Fit and asks the frame to scroll; the canvas does not pan to the pin when the page is zoomed in (the app cannot see where the pin is inside a frame; the bridge would have to send its place back).
|
|
92
|
+
- The sheet's drag was tried by hand with made-up pointer events; the test uses the keys, not a touch drag.
|
|
93
|
+
- Pin places are chosen by the text rectangles at that moment; a page that moves its text later (an animation) can put a badge over it until the next update.
|
|
94
|
+
- Role cards drop the alias chain (the editor has it); a person who wants to see "→ color.white" at a glance opens the card.
|
|
95
|
+
- The palette is folded: a person who looks for one primitive opens "Palette" first (a search opens it).
|
|
96
|
+
|
|
97
|
+
## Round 4: what T's engine gives the editor
|
|
98
|
+
|
|
99
|
+
T's `shadow` parts, `overrides` for each mode, `contrasts`, and the exempt pairs are all used now.
|
|
100
|
+
|
|
101
|
+
1. **A shadow is edited by its parts, and keeps its links.** The editor shows each layer with its X and Y offset, blur, spread and color, and whether it is inset. A member is a value of its own in the field of its kind (a size with a unit, a color), or a link to a token (`space.4`, `color.scrim.40`): a link has "Change" (the same list of tokens as for any link, here of the member's kind) and "Use a value" (the token's value becomes the member's); a value has "Link to a token". A layer is added (a copy of the last) or taken away. The parts are read from `ModeValue.parts` (the `var(--…)` of a member names the token it links to, found by `byVar`); an edit holds the DTCG value as the file has it (`{space.4}` stays that, one layer is an object, several are a list), and the model follows each link in the mode, so the tile, the open design (the `box-shadow` keeps `var()`) and the dark mode that takes the shadow from light all move with it. A shadow that is a link to another shadow shows that one's parts, read only, and "Use a value" copies them with their links. A typography style is still shown, and changed with Pi.
|
|
102
|
+
2. **Inherited, and give it back.** A mode other than the default says, in its editor, **Inherited from Light** (the mode's file does not set the token: `overrides`) or **Dark sets this itself** with **Use Light's value**, which is a removal: the edit is `{ inherit: true }`, `changeOf` makes it `remove: [{ mode, token }]` (only for a token that the file sets now), and the save sends `remove`. The route takes `remove` (the mode and the token, nothing more), refuses it in the default mode (it would delete the token), for a token the mode does not set, and for a mode or a token that is not there. A mode's token that is inherited follows an edit of the default's; one the file sets does not (before this, the view guessed from equal values). In one mode, an inherited color card has its value underlined dotted, a title, and "inherited from Light" in its name for a screen reader. Reset puts back the saved state of each mode (an inherited token is inherited again). "Match Light", which wrote a copy, is gone.
|
|
103
|
+
3. **All the pairs of a color.** The editor lists every pair a token declares (up to four) with its badge, and for a body text color with none, the page it is checked against; each pair names its ground, which opens. The badge in a card is the first pair, as before.
|
|
104
|
+
4. **An exempt pair is a note.** A pair below its minimum that is `exempt: "disabled" | "decorative"` has a neutral badge (**Exempt**), the line "exempt: decorative" in the list, and is in **N notes, no action needed**, a quiet line under the problems that opens to the notes (`DesignSystem.notes`); it is never counted as a warning, nor shown red.
|
|
105
|
+
|
|
106
|
+
The test fixture (Harbor) has a text color with two pairs (`color.text.link`), one with an exempt pair that falls (`color.text.placeholder`), and a shadow made of links (`shadow.lg`). New tests: the model (`design-system-parts.test.ts`: inheritance, a removal, a shadow's parts and its change, the pairs), the route (`design-system-routes.test.ts`: a removal and its refusals, a shadow saved with its links, the shape check), and the view (`design-system-ui.test.ts`: the three of them, in a browser; the typography test took the place of the shadow's Ask Pi).
|
|
107
|
+
|
|
108
|
+
Weak: a shadow's color that is a literal is shown as a hex field, and its alpha is in the hex (eight digits); there is no alpha slider. A shadow has no preview of its own in the editor (the tile above it moves). A part's list of links has every token of the kind (spacing, radii, font sizes), by name search. The inherited mark of a card is for one mode in view; side by side shows the values as before.
|
|
109
|
+
|
|
110
|
+
## Round 4: a cheap start
|
|
111
|
+
|
|
112
|
+
The app loads Design's browser module for everyone at every start, on phones too, also when nobody opens Design. It had grown to 24 files. Now the app loads three small files at start, the workspace when the panel first opens, and the rest when a person first needs it.
|
|
113
|
+
|
|
114
|
+
| Measured in Chromium, page loaded, nothing clicked | files | bytes (source) | bytes on the wire |
|
|
115
|
+
| -------------------------------------------------- | ------------------------------------------ | -------------- | ----------------- |
|
|
116
|
+
| Before (`fd2178e`) | 25 (24 JavaScript, `style.css`) | 462,953 | 125,084 |
|
|
117
|
+
| After | **3** (`index.js`, `paths.js`, `state.js`) | **17,506** | **7,214** |
|
|
118
|
+
| After, the panel opened (a design shown) | 18 | 176,575 | |
|
|
119
|
+
| After, the System view opened as well | 29 | 457,569 | |
|
|
120
|
+
|
|
121
|
+
The files, by when they load:
|
|
122
|
+
|
|
123
|
+
- **At the app's start:** `index.js` (the store, the rail button, the launcher actions, the command and event handlers, and a loading state), `paths.js` (the one icon), and `state.js`. The designs are not listed and no stylesheet loads until the panel opens (the designs list used to be read on every session change).
|
|
124
|
+
- **When the panel first opens** (`app.js`, with a loading state in the panel): the data, the actions, the picker, the toolbar, the canvas with the Check helpers, `style.css` (the workspace's sheet, 33 KB; the panel waits for its rules to apply, so nothing flashes bare).
|
|
125
|
+
- **When first needed:** `docks.js` (the tabs beside the canvas), `views.js` (compare, the variations grid, the slide strip, presentation), and the System view as one part, `system-ui.js` with `system.js`, `color.js`, `specimen.js`, `system-view.js`, `system-sections.js`, `system-widgets.js`, `system-actions.js`, `system-preview.js`, and its own sheet `system.css` (the rules of `style.css` that only the System view uses: 38 KB). A short loading state shows while a part loads.
|
|
126
|
+
|
|
127
|
+
What moved to make that so: `state.js` no longer imports `system.js` (it has its own empty history); the unsaved count and the change a save sends go through `unsaved.js`, which the System view fills in when it loads (with no edits the answer is 0 and nothing is loaded); `openSystem` and `focusFinding`, which the workspace needs, moved from `system-actions.js` to `app.js`; the preview watcher starts when the System view first loads (edits are only made there). `style.css` was split by what each rule styles (a `dsy-` class that the workspace's own parts use, such as the Check dock and the picker's pinned row, stays in `style.css`).
|
|
128
|
+
|
|
129
|
+
`test/design-system-ui.test.ts` holds the budget: on a page that starts with the panel shut, only those three files load and they are under 40,000 bytes; when the panel opens, none of the System view's files, nor `docks.js` or `views.js`, has loaded; the System view's files load when it opens. It prints the numbers.
|
|
130
|
+
|
|
131
|
+
**A failure of the budget test in a whole-file run, and its cause.** The test saw 28 files (436,992 bytes) at the start in a run of the whole file, and 3 files alone. The cause was the test, not the app: `go()` (and a bare `navigate`) can report "done" while the _old_ page is still there when the address is the same, and the resource list of that page holds everything it loaded since it began (every test before it: the workspace, the System view). A mark put on the page before the navigation (`window.__before`) was still there afterwards. A question put to a page while it is replaced can also never come back, so the test now waits, asks nothing during the switch, and then checks that the mark is gone (it navigates again if not). It also sets the worst that a browser keeps for Design on purpose (its saved look in `localStorage`, the design it had open in `sessionStorage`) and still asserts that only the three start files load, so it does not depend on the tests before it. The app itself loads the workspace only when the panel is shown, whatever is stored (the panel's own key is the only stored state that opens it, and then the workspace is right to load).
|
|
132
|
+
|
|
133
|
+
Left alone: `docs/map.md` (the description of the `design/` folder there says that `index.js` sets up everything: it should name `app.js`, `system-ui.js`, `unsaved.js`, `paths.js` and `system.css`, and say which load when); the 33 KB of `style.css` is the panel's first cost (a split of the workspace's own sheet, such as the docks, would save more); `docks.js` still imports the Check dock, which `canvas.js` shares in part (`check.js`).
|
|
134
|
+
|
|
135
|
+
## Round 4, the integrator's second list (people experience 7, enforcement 8)
|
|
136
|
+
|
|
137
|
+
1. **The Colors tab says the roles.** A tab now counts what its section shows open (`sectionCounts`: `{ open, folded, total }`): for the flagship **Colors 52** (the roles), and the Palette group says its own 97 in its head, the component colors their 62. Every section follows the same rule, so Type says its styles, and a tab's tooltip says "52 shown open, and 159 more in folded groups". The integrator has chosen this rule for the view and for the documentation page (G changes the page to it). **The rule, in one sentence for G to copy: "A section's headline count is its role tokens, the ones a person uses (for a section that is only a scale, such as spacing, the scale); the palette and the component tokens show their own counts inside their groups, and every token is in one section, so the parts add up to the system."**
|
|
138
|
+
2. **A shadow tile says what the shadow is**, under its name, as Radii and Spacing do: the first layer as `x y blur`, with its alpha, and `+N` for more layers (`0 18 40 / 14% +1`; `shadowSummary`).
|
|
139
|
+
3. **Phone.** The mode switch is a segmented control (an icon each: sun, moon, a half-and-half circle for any other mode, and the pair for all) for up to four modes, and one button that shows the mode in view and opens a list for more; the Check dock's mode choice is the same (a list only above four). The bar of sections has a mark at the edge that has more (`›` before the buttons, `‹` at the start when it is scrolled), as well as the fade. The Check sheet snaps to 24, 54 and 88 percent of the room and starts at 54, which leaves the page 46 percent (it had 38): the page is at Fit 29 percent on a 390 px screen (22 before).
|
|
140
|
+
4. **Spacing** is a grid of small tiles (a bar at its own scale, the name, the value; 132 px wide and more) and not a row a panel wide for each step.
|
|
141
|
+
5. **The save bar** has undo and redo with discard and save, and keeps its place at the foot of the System view's column while there are edits (it does not move when the view scrolls). With no edit left it goes; redo is in the bar at the top and brings it back. `test/design-system-ui.test.ts` checks its place and takes a screenshot of it (written to `$DS_SHOTS/system-savebar.png` when that is set).
|
|
142
|
+
6. **One-tap fixes.** The Check dock says "N findings are a value that is exactly a token's" with **Fix N exact matches**, for the findings that the server marks `fixable`. The route `POST system/fix` (`id`, `version`, `key`, `mode`, `colorScheme`, `viewport`) checks the version again, rewrites what is exact, and writes a **new version** of the artifact in one commit (the version's record and assets kept, a call id `design-fix:<key>`, so the same tap finds its version; 409 when nothing is exact), with no run of Pi; the dock then shows the newest version and checks it. **V's function is not there yet: `system-fix.ts` is a stand-in** with the signature `fixExactMatches(bundle, system, report, { mode }) → { content, fixed, fixes }` and `isFixable(finding, system, mode)`; `system-api.ts` re-exports it, so V's replaces it by changing that one line. What the stand-in does: a finding is fixable when it is a color or a size that the check calls "written as a literal" **and** its value is exactly the token's in the mode checked (the check calls a value close to a token a literal too: that is not rewritten), and it rewrites that value in the declarations of the page's `<style>` blocks and `style=""` attributes (a size only in the properties the finding names); it never touches custom properties (a page that holds the system's own CSS would have its tokens made to refer to each other), selectors, scripts, text, other attributes, or assets, and a value that two findings want as different tokens is left alone. `fixable` is also read from the engine's finding (`fixable: true`) when V sets it. Tests: `test/design-system-fix.test.ts` (the stand-in), the route test (a version, a key, the checks of a body), and a UI test (one tap in the dock, a version 2, its check).
|
|
143
|
+
7. **Harbor's Radii and Shadows show their tokens** (five corners with their sizes, three shadows with their values; checked in the screenshots at 1440 and 390 px and in the tests, which count them).
|
|
144
|
+
|
|
145
|
+
## Round 5 (people experience 7)
|
|
146
|
+
|
|
147
|
+
1. **Phone Check.** The findings start as a bar at the foot (`10 findings`, `4 errors`, `6 warnings`, and `Fix 2` for the exact matches), so the page keeps 85 to 90 percent of the room (the test asks for 60). A tap on the bar, or on a pin in the page, opens the sheet (54 percent: the page keeps 46; the handle goes to 88 percent and back to the bar). The pin is now a tap target: the frame tells the app (`pocket-pin` with `tap`, `web/artifact-bridge.js`), the finding is marked and scrolled to in the list, and a pin that is asked to come into view says where its element is (`pocket-pin` with `rect`), so that the canvas, which may be bigger than its room, scrolls there too (this was the "the canvas does not pan to a pin" weakness). On a phone the zoom that nobody chose is `auto`, which is the **width of the room** (`Width 91%`: text is readable, the page scrolls inside it), and the zoom value cycles width, whole page (`Fit`), 100%; `fit` is a choice that is kept. The bridge files are B's again (`artifact-inspect.ts`: the pin takes taps; the page's own handlers get nothing from them).
|
|
148
|
+
2. **The phone's section tabs** settle on a whole tab at the left (scroll snap, with the width of the fade as padding), and at rest, a moment after the scroll stops, a tab that is not whole (or is under a fade) is left out: never half a letter, a fade and a `›`/`‹` mark toward the rest, the active tab scrolled to the middle.
|
|
149
|
+
3. **The editor keeps its name.** The head of the editor (the name, the mode in view as a chip, and the way to close it) is `sticky` at the top of the scroll while the editor scrolls (a row's editor keeps its row the same way); the contrast of a color is under its value, above the link row; and an editor that opens out of sight is scrolled to (its head and what follows it, 280 px) when it opens.
|
|
150
|
+
4. **Shadow values in words:** `y 18 · blur 40 · 14%`, with `x` and `spread` only when they are not 0, `inset` first, and `+1 layer` in full.
|
|
151
|
+
5. **Focus mode.** Beside the System view, with no size chosen, the open design's frame is the pane's own size at 100%, centered (it was a desktop page at 44 percent, a card in a corner); a size that was chosen is kept.
|
|
152
|
+
6. **The notes bar** (`1 note, no action needed`) is on the Colors tab only; it is about contrast pairs.
|
|
153
|
+
7. **The Ferry fixture's image** is a small inline SVG picture (no alt text, as the check needs). The bench's phone Check shot follows the bar (and takes the sheet as a second picture, `check-sheet`); its flagship run now starts the copy with `--flagship` (before, the system was swapped in after the design was published with Harbor's CSS, so the flagship's variables did not exist in it and the page's text was white on white in the focus shot).
|
|
154
|
+
|
|
155
|
+
## Round 6 (people experience 8)
|
|
156
|
+
|
|
157
|
+
1. **Spacing and Radii are grouped as the docs page groups them** (`groupsOf` in `system.js`; the roots are `SPACE_ROOT`, `SIZE_ROOT`, `RADIUS_ROOT`, copied from `docsite-space.ts`, and a test reads the page to check that both agree): Steps, Roles, Sizes, Component tokens; and for radii the Scale first (what other radii point at), then Roles, each tile under the step it uses. A tile whose last word says little alone (`in`, `out`, `md`) shows its whole path (`layout.gap.in`). The tab counts the role tokens.
|
|
158
|
+
2. **Shadows** show every layer on its own line with a color swatch, and a copy button for the whole CSS value.
|
|
159
|
+
3. **Phone Check:** a finding of the whole page (`html`, `body`, no `data-pid`) has no pin; it is listed with "the whole page". The frame shows no more than the page fills (`pocket-size` from the frame; B's `artifact-inspect.ts` and `artifact-bridge.js`, in `ds-u-bridge.patch`). The bar says "Fix 2 exact".
|
|
160
|
+
4. **Desktop Check:** a long mode name is cut with dots, not run into its icon.
|
|
161
|
+
5. **Accepted findings:** `Accept` on a finding stores its id per design (`DesignItem.accepted` in `docs.ts`: who, when, rule, message; routes in `design.ts`), for everyone, with Undo. They show in a folded "Accepted (N)" group and are not in the counts. **For V:** please add `CheckOptions.accepted?: readonly string[]` (the engine moves those ids to `report.accepted`, counts only the open ones, and `applyExactFixes` skips them). The route already passes the ids and splits by id when the engine does not (`cleanReport`, `fixExactMatches`).
|
|
162
|
+
6. **Section tabs:** a tab that is not whole goes at once (no fade-out), and the chevron has no box behind it.
|
|
163
|
+
|
|
164
|
+
Left undone: a route test for accept and undo, a bridge test for `pocket-size`, and the new bench shots.
|
|
165
|
+
|
|
166
|
+
## The engines (round 2: the real ones)
|
|
167
|
+
|
|
168
|
+
`system-api.ts` re-exports `loadDesignSystem` and `writeDesignSystem` (T), `checkDesign` (V), and `renderSystemDoc` (G). The stand-ins are gone. With the real engines six tests of this stream failed. The causes, and what was done:
|
|
169
|
+
|
|
170
|
+
1. **A save that must be refused was accepted.** The real `set` makes a mode file for a mode that does not exist, and a token for a name that does not exist (it is how Pi adds them). The view only changes tokens that are there, in modes that are there, so the route now refuses a `set` that names a mode or token the loaded system does not have (400). The route also refuses `{}` for a mode that exists (it would empty its file) and the removal of the default mode. T does not need to change this: it is the route's rule.
|
|
171
|
+
2. **The fixture had two real warnings** (T's checks): `color.bg.overlay` held a raw value (a semantic color), and `color.text.disabled` failed its 4.5:1 pair on purpose. The fixture's tokens are fixed, not the warnings hidden: `overlay` links to a new primitive `color.scrim.40` (the 2025.10 object with an alpha; dark uses `scrim.60`), and `disabled` declares the quieter 3:1 pair that it reaches. The tests that wanted a failing badge now cause one with an edit (the pair falls, the badge says Fail, undo brings it back). The Harbor system loads with no problem.
|
|
172
|
+
3. **`loadDesignSystem` throws for a linked `.pi/design`** (it did not return `undefined`). The route answers 400 with the engine's words, and the view says it could not read it. The test says so.
|
|
173
|
+
4. **The error test.** The engine leaves out a token that failed (`color.accent.hover` with a link to nothing), so it has no row to go to: a problem whose token is not in the system is now a label, not a button. The warning test uses a real warning (too faint in dark) whose token has a row.
|
|
174
|
+
5. **The focus test** failed only because the test before it left the session on a system with no design.
|
|
175
|
+
6. **The messages for a person.** `DesignSystemError.message` is written for Pi ("Fix it and call again"). The route says `Not saved: …` with the problems' own messages (3 at most, then "and N more"), and sends the problems cut to a fixed shape.
|
|
176
|
+
|
|
177
|
+
Used from the new engine: `schemes` (a mode's colour scheme: the specimen's page and `color-scheme`), the `parts` of a typography token (`font-size: var(--font-size-base)`): a type style is drawn from them, so an edit to the size token moves the specimen and its line (`20px / 1.5 · 400 · Geist`); a contrast pair's `on` as a bare name; the token left out of a mode that failed.
|
|
178
|
+
|
|
179
|
+
What T could still change (none of it blocks the view):
|
|
180
|
+
|
|
181
|
+
- `DesignSystemError` could carry a short `summary` for people next to the message written for Pi.
|
|
182
|
+
- A shadow has no `parts`: its box-shadow is drawn from the resolved value, so an edit to a color that a shadow uses does not move the shadow's tile. `parts` for a shadow (`color`, `offset-x`, … as `var(--…)`) would let it, and let the view edit a shadow's members.
|
|
183
|
+
- Which tokens a mode file overrides (`overrides: string[]` on a mode): the view cannot tell an override from a value that is inherited, so "Match Light" writes the default's value as an override. With it the view could show "inherited" and use `remove` to reset.
|
|
184
|
+
- `ResolvedToken.contrast` is the first pair only; a token with several pairs shows its first.
|
|
185
|
+
|
|
186
|
+
What V and G need to keep: findings with a `pid` or a `selector` (no pin without one) and `suggestion` as `var(--color-…)`; the docs page's asset names are valid bundle names (the route refuses 200 assets or 2 MB).
|
|
187
|
+
|
|
188
|
+
## Differences from the plan, and choices made
|
|
189
|
+
|
|
190
|
+
- The route that saves answers 200 with `{ ok: false }` when the engine refuses a change (see above). A stale revision is a 409.
|
|
191
|
+
- The zip has the four generated files at its root (no `dist/` folder); the file is `<system name>-tokens.zip`.
|
|
192
|
+
- An "Other" section holds what no other section takes (z-index, breakpoints, plain numbers). Plan sections are all there.
|
|
193
|
+
- Components show all the states of one component in one frame (a grid), per mode, not one frame per state.
|
|
194
|
+
- Composite tokens are read-only (above). A shadow's fields, a typography style's parts, and gradients are changed with Pi: "Ask Pi" puts a request about the token, with its values as data, in the message box.
|
|
195
|
+
- Check runs on the saved system (the server loads it), not on unsaved edits.
|
|
196
|
+
- The default size of the canvas is `auto` (above), which is a change of `state.js`'s prefs.
|
|
197
|
+
- `/design-open system` opens the view (no new command: a second built-in command would change `test/extension-commands.test.ts`, which is not mine); a launcher action "Open the design system" does the same.
|
|
198
|
+
- Undo is kept to 500 steps; a step that a later one makes no difference to goes first.
|
|
199
|
+
- `src/server/extensions/design/picker.js` is new: the picker moved out of `workspace.js` so that the System bar can use it.
|
|
200
|
+
|
|
201
|
+
## What the docs must say (for the integrator)
|
|
202
|
+
|
|
203
|
+
`docs/features.md`, in **Design**, a bullet after **Decks**:
|
|
204
|
+
|
|
205
|
+
> **The design system.** The first row of the design picker (or `/design-open system`, or the launcher's "Open the design system") shows the project's design system, `.pi/design/` in the session's folder: **Colors** (a neutral card of the look in each mode, roles as cards with their value and contrast badge, the palette as one folded group of ramp strips), **Type**, **Spacing**, **Radii**, **Shadows**, **Motion** (durations and easings that play), **Components** (every state, in a frame that runs nothing and loads nothing), and **Guidelines** (Markdown). Light and dark show one at a time or side by side. People who steer change a color, a size, a time, a weight, a font, or an easing in place, or link a token to another; the open design shows each change live (it follows the system when it uses its variables), **Undo** and **Redo** step through them, **Discard** gives them up, and **Save** writes the files and the generated CSS with no run of Pi (it refuses a change that the system's checks refuse, and one made on a system that changed meanwhile). A shadow is edited by its parts (each a value or a link to a token, kept as a link), a mode says which of its tokens it takes from the default mode and can give one back, a color lists all its contrast pairs (a pair that is exempt is a note, not a failure), and a typography style is changed with Pi. The menu publishes the documentation as a design (`design-system-docs`, a new version each time), exports the generated files as a zip, and adds or removes a mode. A design's **Check** tab (in any mode of the system, the one of the canvas to start with) renders the page on the server and lists what is not the system's (colors, fonts, sizes), contrast, tap targets, overflow, alt text, and headings, with a pin on each element (on a phone the list is a bottom sheet with a handle, and a tap on a finding shows its pin); **Send to Pi** puts one message with them in the message box. People who only view see everything and change nothing. A project with no `.pi/design/` is told how to get one. **Focus mode** (the button by the menu, where the panel is beside the chat) hides the conversation for wide work. Until a size is chosen, the canvas takes the size of its panel, so a phone gets the phone's frame.
|
|
206
|
+
|
|
207
|
+
`docs/map.md`: `extensions/design/` gains `system-routes.ts`, `system-api.ts`, and the browser files above; `test/design-system-*.test.ts`, `test/serve-design-system.ts`.
|
|
208
|
+
|
|
209
|
+
`docs/extensions/built-in.md`: the module's routes `system`, `system/check`, `system/docs`, `system/export` and its event `system`.
|
|
210
|
+
|
|
211
|
+
## What is still weak
|
|
212
|
+
|
|
213
|
+
- Unsaved edits are lost when the tab reloads (they live in the module's store, which survives closing the panel and going to the chat).
|
|
214
|
+
- Nothing creates, renames, deletes, or reorders a token; a mode is added or removed, and tokens already there are changed.
|
|
215
|
+
- Gradients, borders, transitions, and typography styles are read-only (a shadow is edited by its parts).
|
|
216
|
+
- The page check does not see unsaved edits.
|
|
217
|
+
- A design shows the edits only when it uses the system's variables. The view says so, but cannot tell whether a given design does.
|
|
218
|
+
- The first 120 tokens of a group are drawn, with "Show more"; there is no virtual list beyond that. Frames of components reload all together when an edit changes the mode's CSS.
|
|
219
|
+
- The contrast of a color with no declared pair is worked out against the page background for text colors only (shown with a dashed badge).
|
|
220
|
+
- Light app themes were checked by changing the theme's variables on a dark build, not with each shipped light theme.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Stream V notes: verification and export (`ds/verify`)
|
|
2
|
+
|
|
3
|
+
## What was built
|
|
4
|
+
|
|
5
|
+
### `src/server/design/lint.ts` (checks), with `lint-page.ts` and `lint-color.ts`
|
|
6
|
+
|
|
7
|
+
- **`checkDesign(bundle, system | undefined, options, host, signal): Promise<CheckReport>`**, the contract. It renders in the private Chromium (`withRender`), loads the page, applies the view, runs the steps, and checks. It works with only a `DesignSystem` object (no file reads).
|
|
8
|
+
- **`CheckOptions`** (new, in `lint.ts`; `system-types.ts` is untouched): `viewport` (a preset or `{ width, height }`, default desktop), `colorScheme` (`light` | `dark`), `mode` (a system mode; default `dark` for a dark scheme when the system has that mode, else its default mode; a non-default mode also sets `data-theme` on the root when the page sets none), `tweaks`, `page` (another HTML page of the bundle), `actions` (`hover | click | focus` + selector, run first), `slide` (a deck: a slide from 1, or `"all"` up to 40).
|
|
9
|
+
- **`checkPage(page, system, view)`**: the same checks on a page already loaded in a `DesignPage`. `design_preview` uses it, so the checks cost no extra render. Also exported: `analyze(raw, tokens)` (pure: no browser), `modeFor`, `reportOf`, `mergeFindings`.
|
|
10
|
+
- **`lint-page.ts`** is the script that runs in the page: one walk of the DOM (capped at 4,000 elements and 300 groups for each kind), which returns groups of equal values with a count and the first element. It runs in an **isolated world** (`Page.createIsolatedWorld`), so a page cannot change `getComputedStyle`, `Array.from`, and so on. Its answer is untrusted: `analyze` checks shapes and cuts strings.
|
|
11
|
+
- **`lint-color.ts`**: OKLab distance, WCAG contrast, and `tokenSet(system, mode)`: the system's colors, font families, and font-size, spacing, and radius lengths in one mode. Token colors and lengths are resolved **by the browser** (the same canvas path that resolves the page's colors), so every CSS color syntax and `rem`/`clamp()` work, and a token compares with the page like with like.
|
|
12
|
+
- Rules (levels): `off-system-color` (error), `off-system-font` (error), `off-system-size` (warning; font size, spacing, radius, each on its own scale), `contrast` (error for text: 4.5, 3 for large text; warning for a form field's edge: 3), `tap-target` (error under 24 px, warning under 44 px; see round 2), `overflow` (error when the page scrolls sideways, warning when `overflow-x: hidden` hides content), `image-alt` (error), `heading-order` (warning), `font-fallback` (error when a declared `@font-face` did not load, warning when a family has no face and is not installed), `missing-viewport` (error; not for decks), `missing-pid` (warning; one finding for the whole page that names the tags; an element needs its own `data-pid`), `focus-visible` (warning).
|
|
13
|
+
- Precision choices: the background is the real one (every ancestor's color, opacity, alpha composited over the canvas). Contrast is **not judged** when it cannot be known: a gradient, image, filter, blend mode, or `backdrop-filter` in the chain, text over media or a positioned fill, `background-clip: text`, disabled controls, hidden or 1 px text. Auto and percent margins and padding, pill and circle radii, native checkbox margins, text-link tap targets inside a sentence, a native checkbox without a label, and `0` are not findings. The default black text is not an off-system color. Transitions and animations are switched off while checking, so computed values are resting values. Focus is tested on one element of each kind by really focusing it, and the snapshot covers the element, its descendants, its labels, and siblings and parents three levels up, so a `:focus-visible + .box` pattern counts.
|
|
14
|
+
- Equal values in one `data-pid` scope are one finding (round 2): its message ends with `(and N more elements)` (or says `N elements`), and the selector, `pid`, and `rect` are the first element's.
|
|
15
|
+
- Suggestions: `off-system-color` names the nearest token (a role beats a palette value when two are as near; a token named for another role is not offered: a border is not a background; none when nothing is within 20); `contrast` names the system color nearest to the text color that passes on that background; `off-system-size` names the nearest step (the smaller one on a tie); `off-system-font` names the font token with the same generic fallback.
|
|
16
|
+
|
|
17
|
+
### `design_preview`
|
|
18
|
+
|
|
19
|
+
New arguments: `checks` (default true), `tweaks`, `colorScheme`, `page`, `actions` (up to 10; hover, click, focus; a step that cannot run is a `Note:` and is skipped). The output is the screenshots, then one text: `Checks (mobile, desktop; light; system "Name", mode light): 3 errors, 5 warnings.`, up to 30 findings (errors first, then by rule), `… and N more`, notes, then the console errors and failed requests (the old JSON text is gone; `details.errors` and `details.failedRequests` stay, and `details.checks` holds up to 200 findings for each view). A finding that is in only some of the viewports names them. With actions, the checks run before and after the steps and merge. A system that cannot be read is a note, and the screenshots still come.
|
|
20
|
+
|
|
21
|
+
### Export fixes
|
|
22
|
+
|
|
23
|
+
- Deck PNG: `slide` (number from 1) in the tool and the route; `"all"` writes a zip of `slide-N.png` (default path `exports/<id>-v<n>-slides.zip`). `slide` with a non-deck or another format is an error.
|
|
24
|
+
- `tweaks` in the tool and the route are applied before the export (CSS custom properties with the knob's unit, plus a `pocket:tweak` event, as the canvas does). The route takes `viewport` as a preset, `WxH`, or `{ width, height }`.
|
|
25
|
+
- A page's PDF is as wide as the viewport (paper width and height from the viewport, no margins; an `@page` rule still wins, and decks keep their slide size).
|
|
26
|
+
- PPTX: notes leave out `style`, `script`, `template`, `noscript`, and `title` text (`slides()` reads text nodes, not `textContent`); slide images are taken at 2× (3840×2160 for the default slide; no side over 4096 pixels, so very large slides are scaled less).
|
|
27
|
+
- Renders hide scrollbars (`Emulation.setScrollbarsHidden`): a tall page's PNG was 15 px narrower than its viewport.
|
|
28
|
+
|
|
29
|
+
### `render.ts`
|
|
30
|
+
|
|
31
|
+
- `Slots` (limit, queue, wait): renders **queue** first in, first out instead of failing the third. 2 at once, up to 16 waiting, up to 5 minutes of waiting; a wait ends on abort. The 90 s limit starts when a render starts.
|
|
32
|
+
- `DesignPage`: `load(viewport, { scale, page })`, `setScale`, `settle`, `applyView({ colorScheme, theme, tweaks })`, `act(actions)`, `evaluateIsolated`, `pdf(viewport)`. `tweakValues` and `designActions` validate tool and route input.
|
|
33
|
+
|
|
34
|
+
## What differs from the plan
|
|
35
|
+
|
|
36
|
+
- `color.ts` was renamed `lint-color.ts` so that it does not clash with stream T's `color.ts` (commit 5440256 on `ds/tokens`).
|
|
37
|
+
- New files besides `lint.ts`: `lint-page.ts` (the page script), `lint-color.ts` (math and token sets), `tokens-stub.ts` (below). All are in `src/server/design/` and are new, so nothing conflicts.
|
|
38
|
+
- `checkDesign` takes `CheckOptions` as its `options` (the plan left its shape open). `checkPage` is the extra seam so the preview does not render twice.
|
|
39
|
+
- `design_preview`'s `slide` stays a single number; `"all"` is only for `design_export`.
|
|
40
|
+
- Level choices the plan did not fix: off-system colors and fonts are **errors** (the system is the point), sizes are warnings.
|
|
41
|
+
- `focus-visible` and the form-field edge are warnings (best effort).
|
|
42
|
+
|
|
43
|
+
## Stubs
|
|
44
|
+
|
|
45
|
+
- `src/server/design/tokens-stub.ts`: `loadDesignSystem(cwd)` with the plan's signature, returning `undefined`. `index.ts` imports it. When T lands, the integrator changes that one import to `./tokens.ts` and deletes the stub. `designTools(host, { loadSystem })` takes the loader as an optional second argument, which the tests use, so U's `designTools(host)` call needs no change.
|
|
46
|
+
|
|
47
|
+
## For U (the System view)
|
|
48
|
+
|
|
49
|
+
- `checkDesign(await readBundle(...), loadDesignSystem(cwd), { viewport, colorScheme, tweaks, slide }, host, signal)` gives `CheckReport`. Each finding has `selector`, `pid`, and `rect` (page coordinates) for pins, `suggestion` (`var(--…)`), and a message that can go to Pi as is. Counts of equal values are in the message.
|
|
50
|
+
- A check takes about 0.5 s on a small page and about 1.5 s with 4,000 elements.
|
|
51
|
+
|
|
52
|
+
## Text for `docs/features.md` (the integrator merges it)
|
|
53
|
+
|
|
54
|
+
In the Design bullet, replace the `design_preview` and `design_export` sentences: `design_preview` renders a version in a private headless Chromium at mobile and desktop sizes (or the sizes asked for) and returns screenshots, then a short report: values that are not design-system tokens (with the nearest token), contrast (WCAG 2.2 AA), tap targets, sideways overflow, image alt text, heading order, fonts that did not load, a missing viewport tag, missing `data-pid`s, and elements with no visible focus style; at most 30 findings, errors first. Options: `checks` (on by default), `tweaks`, `colorScheme`, `page`, and `actions` (hover, click, or focus before the screenshot). `design_export` also takes `tweaks`, a custom `viewport`, and (for a deck's PNG) `slide`, or `"all"` for a zip of every slide. A page's PDF is as wide as the viewport, and PPTX slide images have twice the pixels. Renders queue (2 at once) instead of failing.
|
|
55
|
+
|
|
56
|
+
## What I checked
|
|
57
|
+
|
|
58
|
+
- `npm run format`, `npm run check`, `npm run lint`, and the full `npm test` (961 tests) pass.
|
|
59
|
+
- New tests: `test/design-lint.test.ts` (24 tests: color math, token sets, every rule with a positive and a negative page, dark mode, tweaks, another page, actions, decks, a clean page with zero findings, a hostile page), `test/design-verify.test.ts` (18 tests: the queue, input validation, the report text, every new preview argument, deck slide PNG and zip, tweaks, custom size, PDF width, PPTX notes and 2× images, tool and route).
|
|
60
|
+
- By hand on a throwaway copy (`127.0.0.12:8912`): the export route with `slide`, `slide: "all"`, a custom `viewport`, and `tweaks` over HTTP with a signed-in owner; an invalid slide is a clear 400.
|
|
61
|
+
- Real pages: `site/index.html` and `site/architecture.html` (900 elements, no system): the findings were real (a real horizontal overflow at 390 px, 17 px footer links, grey text at 2.05:1).
|
|
62
|
+
|
|
63
|
+
## What is still weak
|
|
64
|
+
|
|
65
|
+
- **No real `loadDesignSystem` yet**, so `design_preview` has no off-system rules until T lands (tested with an injected system).
|
|
66
|
+
- **Token naming is a guess**: which dimension tokens are the type, spacing, and radius scales comes from path names (`lengthKind` in `lint-color.ts`: `space`, `spacing`, `radius`, `font.size`, `text.*`…). A system that names them otherwise gets no size rule. Worth one look when T's names are final.
|
|
67
|
+
- **Gradients are not parsed**: a color inside `linear-gradient()` is not compared with the system, and text on a gradient or image is not judged for contrast.
|
|
68
|
+
- **Box shadows, SVG fills, and outlines of the default focus ring** are not compared with the system.
|
|
69
|
+
- **Caps**: 4,000 elements and 300 groups for each kind; beyond that the rest is not checked, and the report does not say so.
|
|
70
|
+
- **Fluid sizes** (`clamp()` in a page) are compared at the checked viewport only, so a fluid font size is off-system unless a token resolves to the same pixels.
|
|
71
|
+
- **Backgrounds come from the DOM chain and rectangle overlap**, not from hit testing (scrolling would change the page), so a sibling overlay is found only when it is positioned or has an image.
|
|
72
|
+
- `font-fallback` for a family with no `@font-face` guesses by measuring text, with an allow list of common system fonts; a font installed only on the reader's machine is a warning.
|
|
73
|
+
- `focus-visible` focuses one element of each tag-and-class kind (up to 40 kinds, 20 findings), so a state that only some instances lack is missed.
|
|
74
|
+
- The preview does not run the checks per slide beyond the slide it shows (`checkDesign` can: `slide: "all"`).
|
|
75
|
+
|
|
76
|
+
## Round 2: the bench's lint phase (0.772 before, 1.0 after)
|
|
77
|
+
|
|
78
|
+
Before: precision 0.815, recall 0.733, 5 false findings (2 on clean designs). After: precision 1, recall 1, 0 findings on the clean designs in both color schemes (`node test/design-system-bench/run.ts --only lint`). One suggestion is not the bench's (below); it does not change the score. Every change is a general fix for a cause, with a test; nothing names a design.
|
|
79
|
+
|
|
80
|
+
Root causes, found in a real browser:
|
|
81
|
+
|
|
82
|
+
1. **A real bug: the walk skipped `<body>`.** `body.querySelectorAll("*")` does not include the body, so the page's background (almost always on `body`) was never part of the backdrop and every text was judged on white. That gave `title` at 1.18:1 and `lede` at 2.43:1 in the dark runs (light text on a white backdrop). Fix: the body is in the walk. This was the cause of all three contrast false positives on text.
|
|
83
|
+
2. **The form-field edge heuristic** (`#name`, 1.40:1) was my own extra rule and is not in the plan or the bench. It is kept only for borders that are not the system's: when every color that makes the edge is a system color, the system owns the look (its contrast pairs are checked by the system validator), so the page is not blamed. A border that is not a system color is still judged.
|
|
84
|
+
3. **Tap targets:** the plan says under 24 px is an error and under 44 px a warning, on any viewport. I had added WCAG's spacing exception and a "phone only" condition for the 44 px warning. Both removed. Links inside a sentence stay exempt (WCAG's inline exemption), as does a native checkbox without a label.
|
|
85
|
+
4. **One finding for each `data-pid` scope, not for each value.** Equal values were merged across the whole page, so the finding named the first element and the others were lost (`title` `#151a22`, `avatar-img`: same `src` as `hero-img`). The group key now includes the nearest `data-pid`: the same value in one scope is still one finding with a count, in another scope it is another finding. This fits how people and Pi name elements (comments and pins use the pid).
|
|
86
|
+
5. **`missing-pid` needs the element's own `data-pid`** (the plan: "a control, heading, image or landmark without its own"). A parent's does not count.
|
|
87
|
+
6. **A literal is not a token, even when equal.** `color: #151a22` written in a rule equals `--color-gray-900` in light, but it does not follow the token (dark mode, a change in the system). With a system, the page's own CSS rules and inline styles are read (CSSOM, not computed styles) for colors, lengths (font size, spacing, radius), and font families written without `var()`. A computed value that equals such a literal is reported: an error when it is not a system value, a warning ("written as a literal") with the token to use when it is. `--custom-property` definitions are not uses. Color tolerance for "the same color" is now 1.0 (was 1.5).
|
|
88
|
+
|
|
89
|
+
Where I disagree with the bench, with evidence: the seeded `banner` expects `color.accent.subtle` or `color.blue.100` for `#e9f0fd`. By OKLab distance the nearest token is `color.bg.subtle` / `gray.100` (`#eceef2`, 1.41) and `blue.100` (`#dce7fb`) is 2.99 away: the color is nearer to the neutral. I report `var(--color-bg-subtle)`, so the bench's suggestion count is 4 of 5. A hue-aware distance (OKLCH with a hue weight) would pick the blue; I did not add one for one case. The integrator decides.
|
|
90
|
+
|
|
91
|
+
## Round 2b: the held-out result
|
|
92
|
+
|
|
93
|
+
The integrator's held-out run used the round 1 code, before the fixes above. Its misses are explained by them: the missed tap targets (the spacing exception and the "phone only" condition), the missed off-system colors (a literal that equals a token), and the missed `missing-pid` (a parent's `data-pid` counted). The 11 contrast false findings (8 on clean designs) were the missing `<body>` backdrop: a dark page's text was judged on white.
|
|
94
|
+
|
|
95
|
+
To prove the contrast rule on other styles, `design-lint.test.ts` has a page of 20 cases ("contrast is judged only where the background is certain"). Judged, with a certain background: light text on a dark section, a white card inside it (and pale text on that card, which is a finding), text in a scope that sets its own variables, a translucent parent over dark, a button label on its own fill, a ghost button. Not judged, because the background is not known: an overlay drawn by `::before` or `::after`, text over an image or a gradient, `backdrop-filter`, `mix-blend-mode`, `clip-path`, a mask, a positioned panel over the text, a parent with partial `opacity`, and screen-reader-only text (`clip`, `clip-path`, `text-indent`, 1 px). A placeholder is never judged (it is not text of the element). Two rules changed for this: partial opacity on the element or an ancestor now means "not known" (before, the faded color was judged), and a positioned or transformed box with a fill counts as something that may cover text.
|
|
96
|
+
|
|
97
|
+
Also checked: the docs page of the flagship (about 3,000 elements, light and dark, phone and desktop) gives two contrast findings, a swatch label at 3.59:1 and a field edge, both real. Logical properties (`padding-inline`, `border-block-start`) are read as literals too.
|
|
98
|
+
|
|
99
|
+
## Round 3: suggestions by role, real-world pages, ids, the scheme
|
|
100
|
+
|
|
101
|
+
1. **Suggestions by role.** The page script now groups a color by how it is used too (text, background, border, outline), so a color used as a background and as text in one scope is two findings, each with its own role. `lint.ts` gives every color token a role from the words of its path (`colorRoleOf`: border, text, background; none for a palette step such as `blue.500`). A text use looks first at text tokens, a background at background tokens, a border at border tokens. A token with no role may stand in. A role token wins when it is within 6 of the best stand-in. Only when no token of the role (or without a role) is within 20 does it offer a token of another role, and then the message says so ("It is a text token, and the system has no background token this close"). Tested with `#1c1e26` used as a background next to a near background token, and with none.
|
|
102
|
+
2. **25 real-world pages** are in `test/fixtures/design-lint-pages/` with the findings that I checked by hand (`expected.json`, run by `test/design-lint-pages.test.ts`): utility classes (Tailwind-like), Bootstrap-like markup, a long docs page, a dashboard, a form, marketing pages in light and dark, a blog with an overlay, pricing, chat, kanban, a shop, a newsletter table, custom toggles, a sticky header with a fixed button, a theme set by attribute, `light-dark()`, CSS nesting with layers and container queries, a status table, tabs and an accordion, overlapping avatars, a hero with a background image, an RTL form, a footer; plus the flagship's ten component specimens composed into one page (light and dark). **False findings before: 51 over the runs (3 causes). After: 0.** The causes: (a) a faint token color (`#343b5812`, alpha 0.07) was read from the canvas, which loses digits at low alpha (the token read as `rgb(57 57 85 / 0.07)`, the page's own `rgb(52 59 88 / 0.07)`), so the hover state looked off-system (12 findings): hex and `/ alpha` colors are now read exactly; (b) a specimen of the focus state (class `is-focus`) has its ring at rest, so focusing it changed nothing (36 findings): a focus-named class or `data-focus` is skipped; (c) a 43.99 px box, from fractional text widths, was reported as 44×44 under 44 (3 findings): sizes are compared in whole pixels. Also tightened without a case in the set: a native range slider is a browser control (like a checkbox without a label); hidden overflow of decoration (a glow or blob that runs past the edge and holds no text, control, or image) is not a finding, hidden text is.
|
|
103
|
+
What the pages still report is true: a link 21 px tall inside a flex label, footer links 28 px tall, a page 415 px wide in 390, a `code` with light text on a light fill, a heading level skipped, `Inter` used and not loaded. In the flagship page the code block's inner `pre` and `code` use the browser's `monospace` (the browser's rule beats the component's `font-family` on the parent: a real finding for the flagship), the menu row's hover text is 4.48:1 in dark, and the switch button is 20 px tall.
|
|
104
|
+
3. **The scheme.** `test/design-check-scheme.test.ts` calls the dock's route (`system/check`) with `colorScheme` light, dark, and none, on a page whose grey text reads on the light canvas and not on the dark one: light and none give no finding, dark gives the contrast error, and the report names the scheme it ran in.
|
|
105
|
+
4. **Ids.** Every finding has `id`: `<rule>-<10 hex>`, a hash of the rule, the scope (the `data-pid`, else the selector), and the value; a repeat in one report gets `-2`. It does not change with the scheme, the viewport, or the wording, so a pin can follow a finding across runs; a changed value is a new id. `CheckFinding.id` is new and optional in `system-types.ts` (one added field), and `cleanReport` in `system-routes.ts` passes it through (one added line): both are other streams' files, for the integrator to check.
|
|
106
|
+
|
|
107
|
+
5. **Every suggestion is an edit** (second judge). The message names the CSS property, the token, its value, and what it replaces: `Set \`color: var(--color-text-muted)\` (#5a5f73) instead of #7ba3f8.`(the property follows the use:`color`, `background-color`, `border-color`, `outline-color`); `Set \`font-family: var(--font-body)\` instead of Georgia, serif.`; `Set \`padding\` to var(--space-4), 16px, instead of 15px.`(all the properties that hold the value, or`font-size`, `border-radius`); for contrast, the color that passes with its ratio; for a target, `Set \`min-width: 44px; min-height: 44px\``; for a heading, the tag to use; for an image, the `alt`to add.`suggestion`stays the bare`var(--token)`for tools. Covered by "every suggestion is an edit" in`design-lint.test.ts`.
|
|
108
|
+
|
|
109
|
+
## Round 3b: modes beyond light and dark
|
|
110
|
+
|
|
111
|
+
`mode` (a name from `system.modes`) is an option of `checkDesign`, and an argument of `design_preview`, `design_export`, and the export route. A named mode: sets `data-theme="<mode>"` on the root before the walk (it replaces a `data-theme` that the page has), draws the page in the mode's scheme (`system.schemes[mode]`; the given `colorScheme` is only the fallback), and compares with that mode's tokens. The name is validated (`The design system has no mode "x". Modes: light, dark, high-contrast.`), and a mode with no system is an error. `modeFor` now returns `{ mode, scheme, theme?, named }`. `CheckReport.mode` is new (optional, `system-types.ts`: for the integrator): the mode compared with, absent without a system; the report's `colorScheme` is the scheme that was drawn. Without a name nothing changes (a dark scheme takes the `dark` mode). Exports now draw in the light scheme unless a mode says otherwise: before, they followed the server's own preference (a dark machine gave a dark PNG). Tested with the flagship's `high-contrast` (drawn dark): the check, the preview (report line and screenshot, also with the checks off), the export tool and route.
|
|
112
|
+
|
|
113
|
+
## Round 4: the contract for one-tap fixes (written first, for stream U)
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
// src/server/design/fix.ts
|
|
117
|
+
export function applyExactFixes(
|
|
118
|
+
content: string,
|
|
119
|
+
findings: CheckFinding[],
|
|
120
|
+
system: DesignSystem,
|
|
121
|
+
): { content: string; applied: number; skipped: { id: string; reason: string }[] };
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- `content` is the page's HTML. `findings` are the report's (a finding is **fixable** when it has `fix`, new in `system-types.ts`: `CheckFix { kind, properties, literal, token, cssVar, mode }`; an off-system finding whose literal equals a token exactly has it; U shows a Fix button for these and a Fix all button that passes every fixable finding). `system` is checked again: the token must exist and still equal the literal in `fix.mode`.
|
|
125
|
+
- It rewrites only a literal (a color, a `px` length, a whole `font-family` list) that equals the token, only in `<style>` elements and `style` attributes, only in a declaration of a property named by `fix.properties`, and only when the place is certain: an inline style is certain when exactly one element has the finding's `data-pid`; a rule is certain when it is the only one that sets that property to that literal, or its selector is the finding's selector. It never touches scripts, comments, strings, `url()`, `content`, a `var()` fallback, custom property definitions, `@font-face`, `@keyframes`, text, or an attribute that is not `style`.
|
|
126
|
+
- The answer is the new HTML, how many replacements were made, and one `{ id, reason }` for each finding that was skipped (`id` is the finding's id). It is a pure function: no browser, no files. A second call with the same findings changes nothing (the literals are gone).
|
|
127
|
+
- The value is the same in the mode that was checked and follows the token in the others: say so in the button's text.
|
|
128
|
+
|
|
129
|
+
### Round 4: what was built
|
|
130
|
+
|
|
131
|
+
- **`applyExactFixes`** (`src/server/design/fix.ts`), as above. Findings that carry `fix` (new `CheckFix` in `system-types.ts`) are the off-system findings whose literal is a token's to the last digit (a color within 0.3 on the OKLab scale, a length within 0.01 px, a whole `font-family` list). It reads the page with a small scanner (comments, scripts, strings, `url()`, `<textarea>`, `<title>` are skipped; `"` in a `style` attribute counts as a quote) and edits only `<style>` elements and `style` attributes. `applied` counts replacements. Certain places: the inline style of the one element with the finding's `data-pid`; a rule whose selector is the finding's (the selector as written: `.a`, `[data-pid="x"]`); the only place in the page that sets the property to the literal; or several places when at least as many findings with the same literal were given ("fix them together"). Else a skip with the number of places in the reason. Tests: `test/design-fix.test.ts` (hostile pages: the literal in a script, a comment, `content: ""`, a URL, a `var()` fallback, a custom property, `@font-face`, `@keyframes`, a shorthand, `!important`, an entity-quoted font, an unclosed style or comment, a tag hidden in a comment, a 2 MB page, a second call), and a full loop with the browser: check, fix, check again, nothing fixable is left.
|
|
132
|
+
For `U` (done by me, in `system-routes.ts`): `cleanReport` passes `fix` (shape-checked and cut), `mode`, and the new rule `reduced-motion` (also in `RULES` of `check.js`). U calls `applyExactFixes(content, report.findings, system)` and writes the new content as a new version.
|
|
133
|
+
- **Reduced motion** (`reduced-motion`, a warning, one finding for the page). The exact rule: an element (not hidden) has a `transition-duration` longer than 500 ms (for a property that is not `none`), or an `animation-duration` longer than 500 ms, or an animation that repeats forever (`animation-iteration-count: infinite`, any speed), and the page's own CSS has no `@media` rule whose condition names `prefers-reduced-motion` (`reduce` or `no-preference`, anything inside it): that rule is taken as "the page thought of it". A style sheet from another origin cannot be read, so the finding is not made when one exists. The message gives the CSS to add: `@media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; animation-iteration-count: 1 !important; transition-duration: 0.01ms !important; } }`. The value is the longest time (`800ms`), and the element is the first one found. Motion is read before the check's own calm style goes in.
|
|
134
|
+
- **Non-text contrast** (WCAG 1.4.11, `contrast`, warnings, 3:1): (1) a form field's edge, as before; (2) the **focus ring**: the ring that the focus draws (an outline, or a spread-only shadow, that was not there at rest; the browser's own `auto` ring is left alone) against what is around it (the parent's backdrop; inside the box for a negative offset); a double ring passes by its best layer; (3) an **icon-only control** (a control with an SVG and no text): the strokes and fills of the icon against the backdrop, judged only when every color it paints fails, and a shape's default black fill counts only when the icon says so. Nothing is judged when the backdrop is not certain (the same rules as text), or when a paint cannot be read (a gradient). With a system, the message names a token that reaches 3:1.
|
|
135
|
+
**A bench conflict, with evidence:** the bench's clean design `clean-pricing` has a hero with `background: var(--color-accent-default)` and a button inside it whose focus ring is `outline: 2px solid var(--color-focus-ring)` (`--color-focus-ring` is `--color-blue-500`, the same blue as the hero): the ring is 1.00:1 against its background, so it cannot be seen. That is a real accessibility defect in a design that the bench calls clean, and the rule reports it (a warning on `hero-cta`; the bench counts two extra findings, one for each scheme). I did not work around it: the design should use an inverse ring in the hero, or the bench should not call it clean. The integrator decides.
|
|
136
|
+
- **`check-cli.ts`** (for the docs): `node src/server/design/check-cli.ts <page.html> [--system <folder>] [--mode <name>] [--viewport mobile|tablet|desktop|WxH] [--scheme light|dark] [--json]`. `--system` is a project folder with `.pi/design/`, or that folder itself. The files next to the page are its bundle (at most 200 files, 5 MB each, 20 MB in all; no links, no dot folders, no `node_modules`), so `ds/tokens.css` and images load; with a system, `ds/tokens.css` and `ds/components.css` are added when the folder has none. It runs offline. Exit 0: no error (warnings are printed); 1: at least one error; 2: bad arguments or files. Output: one block for each finding (`level rule selector`, then the message), then one line of totals; `--json` prints the report. In a CI job: `node node_modules/pi-pocket/src/server/design/check-cli.ts site/index.html --system . --mode high-contrast`. Tested in `test/design-check-cli.test.ts`.
|
|
137
|
+
|
|
138
|
+
## Round 5
|
|
139
|
+
|
|
140
|
+
1. **Only what the author set is judged.** A value that the browser gives an element by itself is not the page's: a button's border and padding, a heading's size and margins, a link's blue, the default serif, black text (white in a dark page). The page script reads each tag's defaults from a probe of the same tag in a shadow tree (the page's style sheets do not reach it; the probe has the page's `color-scheme`, a link has an `href`, an input has its `type`, and the default font size is the keyword, so that monospace is 13px as it is for the page). A property that is not inherited is the author's when it differs from the tag's default (a length that is the same number of ems as the default is the default); an inherited one (color, font size, font family) when it changes from the parent's to something that is not the tag's default, or is inherited from such a place. This covers colors (text, background, border, outline; a border in the text color is the text color's), font family, font size, spacing, and radii. An unstyled control (no padding, border, or font size of its own: a plain `button`, `input`, `select`, `textarea`, `summary`) is also not judged as a tap target. Contrast is still judged on what is drawn. Tests: `test/design-semantics.test.ts` (a plain button, input, select, textarea, fieldset, hr, details, headings, a link, and code give no finding in light and dark; the same with an author's border, padding, radius, size, and color are judged).
|
|
141
|
+
2. **Suggestions: the role first, and honest about change.** A color gets, in this order: a token of its role (text, background, border, from the words of the token's path); a semantic token with no role (an accent); a palette step; any token (with the note that its role differs). A role token wins unless another is more than 12 nearer on the distance scale. When the value changes (not a literal that equals a token), the message says how: `The closest token is #5a5f73, which is darker.` (`slightly`, `much`; or `different in hue, at the same lightness`). A length says `The closest step is 1px smaller.`
|
|
142
|
+
3. **Page semantics** (new rules, `system-types.ts`, `RULES`, and the labels of the check list): `missing-lang` (error: no `lang` on `<html>`), `missing-label` (error: a visible field with no `<label>`, `aria-label`, `aria-labelledby`, `title`, or placeholder; hidden, submit, button, reset, and image inputs are exempt), `missing-label` too (error: a link, `role=button`/`link`, button, or summary with no text, `aria-label`, `aria-labelledby`, `title`, label, image `alt`, or SVG title), `missing-main` (warning: no `<main>` or `role=main`; not for a deck). A placeholder counts as a name, so that a finding is a sure one.
|
|
143
|
+
4. **`input-zoom`** (warning, only when the viewport is under 600 px wide): a text field (text, email, password, search, tel, url, number), a `textarea`, or a `select` with a font size under 16px. iOS Safari zooms the page in when it gets the focus. The browser's own 13.33px counts, because the page can fix it. With a system the message names the smallest font-size token of 16px or more.
|
|
144
|
+
5. **CLI**: `npm run design:check -- <page.html> …` (script `design:check` in `package.json`). `--help` prints the usage and says that it needs Chromium, Chrome, Brave, or Edge (or `PI_POCKET_BROWSER`); without one the exit code is 2.
|
|
145
|
+
6. **`lint-page.ts` is split by concern**, with no change in behavior (the script string is byte for byte what it was, checked before the split): `lint-page.ts` (types and the order of the parts), and the parts `-setup` (the input, helpers, the motion scan, the calm style), `-values` (colors, the system's values, selectors, groups, and what the author set), `-literals` (what the page wrote as literals), `-states` (the backdrop behind each element), `-elements` (the per-element walk), `-checks` (images, semantics, tap targets, overflow, headings, fonts), `-focus` (icons, focus rings, the answer). They are one function body; the order is fixed.
|
|
146
|
+
|
|
147
|
+
What the flagship page shows now (true findings): the input specimen is 13px (`input-zoom` on a phone), and the code block's inner `pre` is the browser's monospace.
|
|
148
|
+
|
|
149
|
+
### Round 5, second part (held-out set 3: precision 0.055, 96 false findings, almost all browser defaults)
|
|
150
|
+
|
|
151
|
+
- **The rule is now exact: a value that no author CSS sets is never an off-system finding.** With the page's rules known, "set by the author" is a fact about them, not a guess from the browser's defaults: the page script collects every style rule of the page (style elements, linked sheets, `@import`, active `@media` and `@supports`; up to 4,000), indexes them by the id, class, or tag of each selector's last compound, and asks, for each element and property, whether a rule that matches it, or its `style` attribute, sets that property (or a shorthand or logical form of it: `padding` for `padding-top`, `border` for `border-top-color`, `font` for `font-size`, `all`). A property that is inherited (color, font size, font family) counts when the element sets it, or when it keeps its parent's value and the parent's was set by the author; a value that differs from the parent's with no rule behind it is the browser's (a link's blue, a nested `h1`'s size, which the probe could not know). Nested `h1` (18.7px), `button`/`input` faces, `td` padding, `fieldset`, lists, and the legacy markup (`<font color>`, `cellpadding`, `bgcolor`) are no longer reported; the page `test/design-semantics.test.ts` keeps all of these on purpose and is clean in light, dark, phone and desktop.
|
|
152
|
+
- **A sheet linked from the bundle is now read.** The sandbox makes the render's own server another origin, so the browser refused to show the rules of a linked sheet (this also hid literals and `prefers-reduced-motion` rules in linked sheets). The script now fetches the sheet's text and parses it with a constructed sheet. A sheet that cannot be read at all (another site's: the check is offline) makes the rules unknown; the browser's defaults (the probe from the first part, and no legacy markup) then stand in, so the plain page stays clean. The motion rule says nothing when a sheet is unreadable, as before.
|
|
153
|
+
- **Rule names, as the integrator asked:** `missing-lang` (no `lang` or an empty one on `<html>`) and `missing-label` (a field, button, link, or switch with no accessible name: label, `aria-label`, `aria-labelledby`, `title`, text for buttons and links, an image's `alt`, an SVG title; a button inside a label is named by it). They replace my `form-label` and `accessible-name`. `missing-main` stays (a warning). The names (with `missing-main`) are in `CheckRule` (`system-types.ts`), `RULES` of `system-routes.ts`, and the labels of `check.js`. The switch and the other ARIA widget roles (`switch`, `checkbox`, `radio`, `tab`, `menuitem`) are in the check.
|
|
154
|
+
|
|
155
|
+
### Round 5, third part (the three rulings)
|
|
156
|
+
|
|
157
|
+
- **A placeholder is not a label** (WCAG 1.3.1, 3.3.2). A field whose only name is its placeholder is a `form-label` error; the message says to add a `<label>` or an `aria-label`. A `title` still names a field (the last resort in WCAG).
|
|
158
|
+
- **ARIA widgets need a name.** `accessible-name` (error): a link, button, summary, `role=button`, `link`, `switch`, `tab`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, or `option` with no text, `aria-label`, `aria-labelledby`, `title`, label, image `alt`, or SVG title. `form-label` (error): a `role=textbox`, `searchbox`, `combobox`, `slider`, `spinbutton` (their content is their value, so it does not name them), or a `role=checkbox` or `radio` with neither a name nor text. The rule names are `form-label` and `accessible-name` again, as in this ruling (superseded: see the fourth part, one `missing-label`).
|
|
159
|
+
- **`input-zoom` judges only a font size that the author set** (the same test as the off-system values, `inheritedAuthored`). The browser's 13.33px on an unstyled field is not the size that iOS goes by. A styled field under 16px on a viewport under 600px stays a warning.
|
|
160
|
+
|
|
161
|
+
### Round 5, fourth part (one `missing-label` again; longhands)
|
|
162
|
+
|
|
163
|
+
- **Rule names, final:** the bench uses `missing-label`, `missing-lang`, and `missing-main`, so `form-label` and `accessible-name` are gone again and `missing-label` is the one rule for a field, an ARIA widget, a link, a button, a tab, a menu item, a switch, or a summary with no name (the message tells a field, "has no label", from the others, "has no accessible name"). A placeholder is not a name; `input-zoom` judges only a size the author set (also `font: inherit` of a smaller size).
|
|
164
|
+
- **A longhand that no author rule sets is the browser's.** The author index used one setter list for a whole family, so one `margin-top` made `margin-bottom` look authored (the paragraph's own 1em, 14px, was reported). Each computed longhand now has its own list of properties that set it: itself, the shorthands that carry it (`margin`, `border`, `border-color` for a color, `border-top`, `border-top-color`, `border-radius`, `gap`, `grid-gap`, `outline`, `background`, `font`, `all`), and the logical forms of its side (`margin-block-end`, `margin-block`, `padding-inline-start`, `border-inline-end-color`, `border-start-start-radius`; left and right swap in a right-to-left page). `inset` is not judged. The test sets one longhand at a time (and a shorthand, and the logical forms) and checks that only what the author set is judged.
|
|
165
|
+
|
|
166
|
+
### Round 5, final names
|
|
167
|
+
|
|
168
|
+
**Final decision of the integrator: the rules are `form-label` (a field, or a widget that stands in for one: textbox, searchbox, combobox, slider, spinbutton, checkbox, radio) and `accessible-name` (a link, button, summary, tab, menu item, option, or switch), plus `missing-lang` and `missing-main`. There is no `missing-label`.** Everything above that says `missing-label` is superseded. A placeholder is not a name; the longhand fix of the fourth part stays.
|
|
169
|
+
|
|
170
|
+
### Round 6 (stopped at the wrap-up; what is in)
|
|
171
|
+
|
|
172
|
+
- **Suggestions** (`lint-suggest.ts`): an exact match wins (a role token, an accent, a palette step, another role's token, a component's last); otherwise the nearest token of the use's role in the hue family (OKLCH: a hue limit, a share of the chroma, a neutral for a neutral, of the system's own neutral hue); never a component's token for a color that no token equals; a failing contrast gets a passing token of its hue, else a text token and the message says the hue changes; "the same color" is said only for the same 8-bit value. Tests: `design-suggest.test.ts` (the judge's three cases too).
|
|
173
|
+
- **Grouping**: findings of one rule with the same value, suggestion, and message are one finding with `elements` (a pin for each); its id covers all of them. `applyExactFixes` counts the elements.
|
|
174
|
+
- **Accepted findings**: `CheckOptions.accepted` (ids); the report has `accepted` (the findings, kept apart) and `summary.accepted`; they are not in the counts. Shape for stream U: store `accepted: string[]` for each design, send it as `accepted` in the check body (the route checks it: up to 200 ids), draw `report.accepted` apart. The CLI takes `--accept <id>`.
|
|
175
|
+
- **Not judged**: `summary.notJudged.contrast = { count, elements }` and a sentence in the preview and the CLI.
|
|
176
|
+
- Not done: nothing was left half done, but the full suite was not run after the last edits.
|
|
177
|
+
|
|
178
|
+
### Text for `docs/features.md` (the integrator merges it)
|
|
179
|
+
|
|
180
|
+
In the Design bullet, replace the checks sentences: **Checks.** `design_preview` (and **Check** in the System view, and `npm run design:check -- page.html [--system folder] [--mode name] [--viewport mobile|tablet|desktop|WxH] [--scheme light|dark] [--json]` for a CI job) renders a design in a private Chromium and reports what is wrong, most severe first: values that are not design-system tokens (and literals that equal a token, which do not follow it), with the token to use and the edit to make; contrast of text (4.5:1, 3:1 for large text) and of what is not text (a field's edge, a focus ring, an icon-only control: 3:1); tap targets (24 px, and 44 px as a warning); sideways overflow; alt text, field labels, names of links and buttons, heading order, the page language, a main landmark; fonts that did not load; a missing viewport tag; text fields under 16px on a phone (iOS zooms); missing `data-pid`s; elements with no visible focus style; and long motion with no `prefers-reduced-motion` rule. Only what the page's author set is judged: the browser's own defaults (a plain button's border, a heading's size, a link's blue) are not. A finding for a literal that equals a token exactly has a fix: **Fix** in the System view rewrites it to `var(--token)` in the page's `<style>` elements and `style` attributes, where the place is certain. The CLI needs Chromium, Chrome, Brave, or Edge on the machine (or `PI_POCKET_BROWSER`), runs offline, prints each finding and a total, and exits 0 with no error, 1 with an error, 2 for a wrong argument or no browser.
|
|
181
|
+
|
|
182
|
+
## Duplicates with stream T's `color.ts` (done)
|
|
183
|
+
|
|
184
|
+
`lint-color.ts` now imports from `color.ts` and the duplicates are deleted: `luminance` and `contrastRatio` (a small wrapper `contrastOf` takes 0 to 255 channels and calls T's `contrastRatio`), `colorCss` (now `colorObjectCss`; the hex fallback for an unknown space stays), and `formatColor` (uses `toHex` for opaque colors; a translucent one is `rgb(r g b / a)`). Kept in `lint-color.ts` because `color.ts` has no equal: `toOklab` and `colorDistance` (OKLab distance with alpha), `dimensionCss`, `familyList`, `isGenericFamily`, `lengthKind`, `tokenSet`, and the token types. The tuple type is now `RgbaTuple` (T's `Rgba` is an object, 0 to 1).
|
|
185
|
+
|
|
186
|
+
Other bench notes: the full tree has three failing tests that are not from this stream and fail without my changes: `design-docsite` (1), `design-guide` (3), and `design-system-bench` ("with nothing in the tree every phase scores 0": the contrast phase now scores 1 from the bench's own system).
|