pi-pocket 0.27.0-beta.1 → 0.27.0-beta.3

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.
Files changed (203) hide show
  1. package/docs/design/design-system.md +165 -0
  2. package/docs/design/ds-notes-b.md +61 -0
  3. package/docs/design/ds-notes-g.md +170 -0
  4. package/docs/design/ds-notes-t.md +303 -0
  5. package/docs/design/ds-notes-u.md +220 -0
  6. package/docs/design/ds-notes-v.md +186 -0
  7. package/docs/design/ds-rounds.md +160 -0
  8. package/docs/design/ds-u-bridge.patch +732 -0
  9. package/docs/examples/design-system/README.md +15 -0
  10. package/docs/examples/design-system/pocket/.pi/design/components/badge.html +112 -0
  11. package/docs/examples/design-system/pocket/.pi/design/components/button.html +203 -0
  12. package/docs/examples/design-system/pocket/.pi/design/components/card.html +125 -0
  13. package/docs/examples/design-system/pocket/.pi/design/components/code-block.html +155 -0
  14. package/docs/examples/design-system/pocket/.pi/design/components/input.html +156 -0
  15. package/docs/examples/design-system/pocket/.pi/design/components/menu-row.html +167 -0
  16. package/docs/examples/design-system/pocket/.pi/design/components/notice.html +171 -0
  17. package/docs/examples/design-system/pocket/.pi/design/components/segmented.html +120 -0
  18. package/docs/examples/design-system/pocket/.pi/design/components/switch.html +117 -0
  19. package/docs/examples/design-system/pocket/.pi/design/components/tool-step.html +163 -0
  20. package/docs/examples/design-system/pocket/.pi/design/dist/components.css +730 -0
  21. package/docs/examples/design-system/pocket/.pi/design/dist/names.md +495 -0
  22. package/docs/examples/design-system/pocket/.pi/design/dist/tailwind.css +1132 -0
  23. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.css +1126 -0
  24. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.dark.resolved.json +2022 -0
  25. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.high-contrast.resolved.json +2022 -0
  26. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.light.resolved.json +2022 -0
  27. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.resolved.json +371 -0
  28. package/docs/examples/design-system/pocket/.pi/design/dist/tokens.studio.json +5915 -0
  29. package/docs/examples/design-system/pocket/.pi/design/guidelines.md +81 -0
  30. package/docs/examples/design-system/pocket/.pi/design/tokens.dark.json +182 -0
  31. package/docs/examples/design-system/pocket/.pi/design/tokens.high-contrast.json +185 -0
  32. package/docs/examples/design-system/pocket/.pi/design/tokens.json +2034 -0
  33. package/docs/extensions/browser-modules.md +1 -1
  34. package/docs/extensions/people-values.md +1 -0
  35. package/docs/extensions/policies/api-stability.md +3 -0
  36. package/docs/extensions/reference/api-versions.md +2 -0
  37. package/docs/extensions/reference/glossary.md +1 -1
  38. package/docs/extensions/reference/host.md +16 -1
  39. package/docs/extensions/reference/pocket.md +1 -1
  40. package/docs/features.md +12 -7
  41. package/docs/map.md +20 -12
  42. package/package.json +2 -1
  43. package/src/server/app.ts +1 -0
  44. package/src/server/commands.ts +123 -2
  45. package/src/server/design/check-cli.ts +283 -0
  46. package/src/server/design/color.ts +654 -0
  47. package/src/server/design/components.ts +328 -0
  48. package/src/server/design/docsite-assets.ts +29 -0
  49. package/src/server/design/docsite-color-section.ts +366 -0
  50. package/src/server/design/docsite-color.ts +303 -0
  51. package/src/server/design/docsite-components.ts +89 -0
  52. package/src/server/design/docsite-core.ts +634 -0
  53. package/src/server/design/docsite-css-base.ts +397 -0
  54. package/src/server/design/docsite-css-content.ts +477 -0
  55. package/src/server/design/docsite-css-phone.ts +251 -0
  56. package/src/server/design/docsite-css-reference.ts +374 -0
  57. package/src/server/design/docsite-css-specimens.ts +465 -0
  58. package/src/server/design/docsite-js-code.ts +96 -0
  59. package/src/server/design/docsite-js-core.ts +72 -0
  60. package/src/server/design/docsite-js-demos.ts +24 -0
  61. package/src/server/design/docsite-js-links.ts +25 -0
  62. package/src/server/design/docsite-js-nav.ts +73 -0
  63. package/src/server/design/docsite-js-stages.ts +81 -0
  64. package/src/server/design/docsite-js-table.ts +81 -0
  65. package/src/server/design/docsite-markdown.ts +221 -0
  66. package/src/server/design/docsite-motion.ts +110 -0
  67. package/src/server/design/docsite-reference.ts +269 -0
  68. package/src/server/design/docsite-sanitize.ts +193 -0
  69. package/src/server/design/docsite-shadows.ts +45 -0
  70. package/src/server/design/docsite-space.ts +289 -0
  71. package/src/server/design/docsite-type.ts +167 -0
  72. package/src/server/design/docsite.ts +508 -0
  73. package/src/server/design/export.ts +86 -9
  74. package/src/server/design/fix.ts +666 -0
  75. package/src/server/design/guide.ts +137 -22
  76. package/src/server/design/index.ts +368 -15
  77. package/src/server/design/lint-color.ts +293 -0
  78. package/src/server/design/lint-page-checks.ts +204 -0
  79. package/src/server/design/lint-page-elements.ts +252 -0
  80. package/src/server/design/lint-page-focus.ts +165 -0
  81. package/src/server/design/lint-page-literals.ts +293 -0
  82. package/src/server/design/lint-page-setup.ts +102 -0
  83. package/src/server/design/lint-page-states.ts +121 -0
  84. package/src/server/design/lint-page-values.ts +329 -0
  85. package/src/server/design/lint-page.ts +101 -0
  86. package/src/server/design/lint-suggest.ts +340 -0
  87. package/src/server/design/lint.ts +1136 -0
  88. package/src/server/design/render.ts +370 -18
  89. package/src/server/design/scan-braces.ts +115 -0
  90. package/src/server/design/scan-categorize.ts +187 -0
  91. package/src/server/design/scan-channels.ts +113 -0
  92. package/src/server/design/scan-color-base.ts +209 -0
  93. package/src/server/design/scan-color-names.ts +403 -0
  94. package/src/server/design/scan-color-palette.ts +91 -0
  95. package/src/server/design/scan-color-roles.ts +565 -0
  96. package/src/server/design/scan-colors.ts +22 -0
  97. package/src/server/design/scan-facts-antd.ts +171 -0
  98. package/src/server/design/scan-facts-files.ts +300 -0
  99. package/src/server/design/scan-facts-lists.ts +538 -0
  100. package/src/server/design/scan-facts-sass.ts +113 -0
  101. package/src/server/design/scan-facts-theme.ts +400 -0
  102. package/src/server/design/scan-facts-use.ts +674 -0
  103. package/src/server/design/scan-facts-wordpress.ts +374 -0
  104. package/src/server/design/scan-facts.ts +285 -0
  105. package/src/server/design/scan-files.ts +384 -0
  106. package/src/server/design/scan-import-convert.ts +277 -0
  107. package/src/server/design/scan-import-eval.ts +583 -0
  108. package/src/server/design/scan-import-material.ts +745 -0
  109. package/src/server/design/scan-import-sd-config.ts +370 -0
  110. package/src/server/design/scan-import-sd.ts +381 -0
  111. package/src/server/design/scan-import-studio.ts +242 -0
  112. package/src/server/design/scan-import.ts +336 -0
  113. package/src/server/design/scan-infer.ts +313 -0
  114. package/src/server/design/scan-js-eval.ts +1267 -0
  115. package/src/server/design/scan-palette.ts +485 -0
  116. package/src/server/design/scan-parse.ts +1134 -0
  117. package/src/server/design/scan-prepare.ts +402 -0
  118. package/src/server/design/scan-render-pages.ts +367 -0
  119. package/src/server/design/scan-render-probe.ts +229 -0
  120. package/src/server/design/scan-render.ts +524 -0
  121. package/src/server/design/scan-review.ts +54 -0
  122. package/src/server/design/scan-roles.ts +259 -0
  123. package/src/server/design/scan-sass-colors.ts +275 -0
  124. package/src/server/design/scan-sass-eval.ts +269 -0
  125. package/src/server/design/scan-sass-expr.ts +911 -0
  126. package/src/server/design/scan-sass-modules.ts +353 -0
  127. package/src/server/design/scan-sass-run.ts +1003 -0
  128. package/src/server/design/scan-sass-stmt.ts +256 -0
  129. package/src/server/design/scan-sass-values.ts +886 -0
  130. package/src/server/design/scan-scales.ts +983 -0
  131. package/src/server/design/scan-tailwind.ts +34 -0
  132. package/src/server/design/scan-theme-shapes.ts +579 -0
  133. package/src/server/design/scan-tree.ts +290 -0
  134. package/src/server/design/scan-util.ts +44 -0
  135. package/src/server/design/scan-variables.ts +470 -0
  136. package/src/server/design/scan.ts +539 -203
  137. package/src/server/design/system-schema.ts +68 -0
  138. package/src/server/design/system-types.ts +279 -0
  139. package/src/server/design/system.ts +502 -93
  140. package/src/server/design/tokens-base.ts +123 -0
  141. package/src/server/design/tokens-compile.ts +440 -0
  142. package/src/server/design/tokens-dtcg.ts +354 -0
  143. package/src/server/design/tokens-io.ts +417 -0
  144. package/src/server/design/tokens-model.ts +1163 -0
  145. package/src/server/design/tokens-names.ts +112 -0
  146. package/src/server/design/tokens-ramps.ts +112 -0
  147. package/src/server/design/tokens-summary.ts +317 -0
  148. package/src/server/design/tokens-tailwind.ts +324 -0
  149. package/src/server/design/tokens-values.ts +921 -0
  150. package/src/server/design/tokens.ts +533 -0
  151. package/src/server/docs.ts +8 -0
  152. package/src/server/extension-points.ts +5 -0
  153. package/src/server/extensions/artifacts.ts +87 -2
  154. package/src/server/extensions/design/app.js +280 -0
  155. package/src/server/extensions/design/canvas.js +142 -17
  156. package/src/server/extensions/design/check.js +656 -0
  157. package/src/server/extensions/design/color.js +383 -0
  158. package/src/server/extensions/design/data.js +102 -7
  159. package/src/server/extensions/design/devices.js +26 -0
  160. package/src/server/extensions/design/docks.js +117 -3
  161. package/src/server/extensions/design/index.js +171 -219
  162. package/src/server/extensions/design/messages.js +49 -0
  163. package/src/server/extensions/design/parts.js +15 -1
  164. package/src/server/extensions/design/paths.js +4 -0
  165. package/src/server/extensions/design/picker.js +123 -0
  166. package/src/server/extensions/design/specimen.js +55 -0
  167. package/src/server/extensions/design/state.js +72 -7
  168. package/src/server/extensions/design/style.css +546 -0
  169. package/src/server/extensions/design/system-actions.js +214 -0
  170. package/src/server/extensions/design/system-api.ts +62 -0
  171. package/src/server/extensions/design/system-data.js +315 -0
  172. package/src/server/extensions/design/system-preview.js +41 -0
  173. package/src/server/extensions/design/system-routes.ts +1122 -0
  174. package/src/server/extensions/design/system-sections.js +1344 -0
  175. package/src/server/extensions/design/system-ui.js +32 -0
  176. package/src/server/extensions/design/system-view.js +1196 -0
  177. package/src/server/extensions/design/system-widgets.js +942 -0
  178. package/src/server/extensions/design/system.css +2313 -0
  179. package/src/server/extensions/design/system.js +1479 -0
  180. package/src/server/extensions/design/unsaved.js +20 -0
  181. package/src/server/extensions/design/views.js +2 -2
  182. package/src/server/extensions/design/workspace.js +200 -105
  183. package/src/server/extensions/design.ts +89 -6
  184. package/src/server/extensions/pip.ts +15 -2
  185. package/src/server/host.ts +13 -1
  186. package/src/server/http/artifact-inspect.ts +338 -24
  187. package/src/server/http/conversation-routes.ts +10 -0
  188. package/src/server/pip.ts +71 -14
  189. package/types/pocket.d.ts +17 -1
  190. package/web/app.js +11 -2
  191. package/web/artifact-bridge.js +34 -1
  192. package/web/composer.js +42 -1
  193. package/web/files-panel.js +4 -1
  194. package/web/sessions.js +53 -9
  195. package/web/sheets/file.js +19 -6
  196. package/web/sheets/people.js +8 -2
  197. package/web/sheets/session.js +256 -46
  198. package/web/sheets.js +21 -6
  199. package/web/store.js +4 -0
  200. package/web/style.css +83 -1
  201. package/web/theme.js +13 -0
  202. package/web/transcript.js +16 -2
  203. package/web/ui.js +4 -1
@@ -0,0 +1,165 @@
1
+ # Design systems in Design mode (hill climb)
2
+
3
+ Status: in progress, on `feat/design-system` (off 0.27.0-beta.1). This page is the plan, the contracts between the streams, and the rubric that scores each round. Streams write what they built, and what differs from this page, in `docs/design/ds-notes-<stream>.md`.
4
+
5
+ ## Goal
6
+
7
+ Make Pi Pocket the best place to **build, keep, and use a design system** with an agent, and prove it with a flagship system (Pi Pocket's own) made with the tools. Today the "design system" is one 16 KB Markdown note in the prompt (`.pi/design-system.md`): nothing compiles it, nothing shares it between designs, nothing checks that designs follow it, and people cannot see or edit it. The end result must be **professional to use**: on par with Figma variables + Tokens Studio + Storybook + zeroheight, for the parts that it covers.
8
+
9
+ ## What "done" looks like (the user stories)
10
+
11
+ 1. "Scan my project and make a design system." Pi runs a scan, gets a **structured** draft (palette, semantic roles, type scale, spacing, radii, shadows, motion, light and dark), names the roles, and saves a valid token set in one or two calls.
12
+ 2. A person opens **Design → System** and sees the system: color roles as swatches with contrast badges, the type scale as specimens, spacing, radii, shadows, motion, in light and dark. They change a token in place (a color picker, a number) and every open design updates live; **Save** writes the file with no Pi run.
13
+ 3. Pi makes a design that **links the system** (`ds/tokens.css`). The design uses only system values. `design_preview` reports any value that is not a token, with the nearest token to use, and any contrast, tap-size, or overflow problem.
14
+ 4. A person opens a design and taps **Check**: findings show as pins on the canvas, each with a fix suggestion and a **Send to Pi** button.
15
+ 5. Components: the system holds component specimens (button, input, card, …) with their states (default, hover, focus, disabled, error). The System view shows them as a state grid; Pi reuses their markup.
16
+ 6. **Publish** the system as a documentation page (an artifact: shareable with a link, exportable), and **export** it for code: CSS variables, a Tailwind v4 `@theme` file, and resolved JSON.
17
+ 7. Old projects with only `.pi/design-system.md` keep working.
18
+
19
+ ## Files on disk (in the session's folder)
20
+
21
+ ```
22
+ .pi/design/
23
+ tokens.json DTCG token file: the default mode (light). Primitives, semantic roles, component tokens.
24
+ tokens.<mode>.json Overrides for one mode (dark, high-contrast, a brand), same paths, only what changes.
25
+ components/<slug>.html One component specimen per file (format below).
26
+ guidelines.md Prose: voice, layout rules, do and don't. Bounded (16 KB).
27
+ dist/ Generated. Never edit by hand.
28
+ tokens.css :root (default) + [data-theme="<mode>"] + @media (prefers-color-scheme: dark) when a dark mode exists.
29
+ tailwind.css Tailwind v4 @theme block: one variable for each token, in the Tailwind namespace of its kind
30
+ (--spacing-4, --text-sm, --leading-tight, --tracking-wide); a color role drops the word that the
31
+ utility repeats (color.bg.surface is --color-surface, so bg-surface), and a role that is only default,
32
+ primary, or base takes its group's word (color.border.default is --color-border, color.text.primary is --color-text). A token that fits no namespace
33
+ keeps its own name. A dark: variant for [data-theme] and the system's dark setting.
34
+ tokens.<mode>.resolved.json
35
+ The main JSON output. DTCG, one file for each mode, with one $value for each token and every
36
+ reference followed (Style Dictionary reads it). String forms by default; see "format" below.
37
+ tokens.studio.json For Tokens Studio: one file with a token set for each mode and a $themes array that turns one on.
38
+ names.md Every token with its variable in tokens.css and in tailwind.css, and its Tailwind utilities; the rules for how
39
+ the names come out. Generated: look a class up here (bg-surface is color.bg.surface).
40
+ tokens.resolved.json A compact summary for scripts, secondary to the DTCG files: one line for each token.
41
+ components.css The CSS of every component specimen, scoped by class.
42
+ .pi/design-system.md The 0.26 format. Still read when .pi/design/ is absent.
43
+ ```
44
+
45
+ ### Token format
46
+
47
+ - **W3C Design Tokens (DTCG)**: groups are objects, a token has `$value` and `$type` (inherited from a group), optional `$description`, `$deprecated`, `$extensions`. References are `{group.token}`. Accept both the 2025.10 object forms (color `{ colorSpace, components, alpha?, hex? }`, dimension `{ value, unit }`) and the older string forms (`"#7aa2f7"`, `"16px"`).
48
+ - Types: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, shadow, typography, border, transition, gradient, strokeStyle.
49
+ - **Tiers**, by top-level group or `$extensions["com.pi-pocket"].tier`: `primitive` (raw palette and scales), `semantic` (roles: `color.bg.surface`, `color.text.primary`, `color.accent.default`, `space.4`, `font.body`…), `component` (`button.primary.bg`). Semantic tokens should reference primitives.
50
+ - **Modes**: the default mode is `tokens.json`; `tokens.<mode>.json` holds overrides. Mode names: lowercase slug.
51
+ - **Contrast pairs** (optional): `$extensions["com.pi-pocket"].contrast: { on: "{color.bg.surface}", min: 4.5 }` on a text color: the validator checks it in every mode. A list of pairs is allowed. `exempt: "disabled" | "decorative"` leaves a pair out of the warnings (WCAG exempts both): a failing exempt pair is a note (`notes` of the system), not a warning.
52
+ - **Names**: a token named for its own value (`space.16` = 16px, `duration.140` = 140ms) gets a warning, with a fix: name it for a role (`space.card`) or a step of a scale (`space.4`).
53
+ - **DTCG draft of the output** (optional): `$extensions["com.pi-pocket"].format` on the root of `tokens.json`. `"2021"` (the default) writes the string forms of the 2021 to 2024 drafts in `tokens.<mode>.resolved.json`: `"#7aa2f7"`, `"16px"`, `"150ms"`. `"2025.10"` writes the object forms: a color is `{ colorSpace, components, alpha, hex }` (sRGB, or the space the token was written in), and a dimension or duration is `{ value, unit }` (2025.10 has px and rem for a dimension and ms and s for a duration; another unit stays text). A file has one form throughout, whatever form the tokens were written in. `tokens.studio.json` is always in the string forms.
54
+ - **Tailwind names**: `tailwind.css` puts a token in the namespace of its kind: `--color-*`, `--font-*` (families), `--text-*`, `--font-weight-*`, `--tracking-*`, `--leading-*`, `--breakpoint-*`, `--container-*`, `--spacing-*`, `--radius-*`, `--shadow-*`, `--inset-shadow-*`, `--drop-shadow-*`, `--blur-*`, `--perspective-*`, `--aspect-*`, `--ease-*`. A token whose own name would be read as a namespace of another kind (`--font-leading-tight`) gets `--ds-` in front. A color role drops the word that the utility repeats (`color.bg.surface` is `bg-surface`); one that is only `default`, `primary`, `secondary`, `tertiary`, `base`, `main`, `normal`, `regular`, or `standard` takes the word of its group (`color.border.default` is `--color-border`, `color.text.primary` is `--color-text`), and the second of one name keeps its full name (`--color-text-secondary`). `tokens.css` keeps the full names. `dist/names.md` lists them all.
55
+ - **Tailwind reset** (optional): `$extensions["com.pi-pocket"].tailwindReset: ["color"]` on the root of `tokens.json` puts `--color-*: initial;` in `tailwind.css`, so Tailwind's default palette does not leak into utilities. `true` is `["color"]`; the other names are `font`, `text`, `font-weight`, `spacing`, `radius`, `shadow`, `ease`, `breakpoint`, and `all`.
56
+ - A primitive, or a step of a scale (`space.4`), that refers to another primitive (`{dim.16}`) is written in `tokens.css` as the value (`--space-4: 16px`), so that DevTools shows `16px`. A role or component token keeps `var()`.
57
+ - CSS variable name: the path joined by `-`, with `--` in front (`color.bg.surface` → `--color-bg-surface`). A reference compiles to `var(--…)`, so a mode override of a primitive flows through.
58
+
59
+ ### Component specimen format
60
+
61
+ ```html
62
+ <script type="application/json" id="pocket-component">
63
+ {
64
+ "name": "Button",
65
+ "description": "…",
66
+ "states": ["default", "hover", "focus", "disabled"],
67
+ "usage": { "do": ["…"], "dont": ["…"] },
68
+ "tokens": ["button.primary.bg", "…"]
69
+ }
70
+ </script>
71
+ <style>
72
+ /* the component's CSS: uses only var(--…) tokens; scoped to its class */
73
+ </style>
74
+ <template data-state="default">…markup…</template>
75
+ <template data-state="hover">…markup, with a state class such as .is-hover…</template>
76
+ ```
77
+
78
+ ## Contracts between the streams
79
+
80
+ All shared types live in **`src/server/design/system-types.ts`** (written in round 0, owned by T; others import it and must not change it without a note). The functions:
81
+
82
+ - **T** `src/server/design/tokens.ts`
83
+ - `loadDesignSystem(cwd: string): DesignSystem | undefined` (bounded, symlink-safe reads; `undefined` when `.pi/design/` is absent).
84
+ - `compileDesignSystem(system): CompiledFiles` and `writeDesignSystem(cwd, change): DesignSystem` (validate, write atomically, recompile `dist/`).
85
+ - `systemSummary(system, maxBytes): string` (compact text for the prompt: token names by role with values, modes, components, rules).
86
+ - **V** `src/server/design/lint.ts`
87
+ - `checkDesign(bundle, system | undefined, options, host, signal): Promise<CheckReport>` (renders in the private Chromium and walks the DOM).
88
+ - **G** `src/server/design/docsite.ts`
89
+ - `renderSystemDoc(system): { html: string; assets: { name: string; content: string }[] }` (the documentation page).
90
+ - **U** uses all three through routes in `src/server/extensions/design.ts`.
91
+
92
+ Until a stream's real function lands, the others use a small local stub with the same signature, and say so in their notes.
93
+
94
+ ## Streams
95
+
96
+ | Stream | Branch | Worktree | Owns (plus new tests and its notes file) |
97
+ | ----------------------------- | ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
98
+ | T: tokens engine | `ds/tokens` | `pi-pocket-ds-t` | `system-types.ts`, new `tokens.ts`, `system.ts`, `scan.ts`, the `design_system` tool, and the `ds/` auto-attach in `src/server/extensions/artifacts.ts` |
99
+ | V: verify and export | `ds/verify` | `pi-pocket-ds-v` | new `lint.ts`, `render.ts`, `export.ts`, `pptx.ts`, `index.ts` (`design_preview`, `design_export`, export route) |
100
+ | U: System view | `ds/ui` | `pi-pocket-ds-u` | `src/server/extensions/design.ts`, everything in `src/server/extensions/design/` |
101
+ | G: guide, docs page, flagship | `ds/guide` | `pi-pocket-ds-g` | `guide.ts`, new `docsite.ts`, `docs/examples/design-system/` (the flagship), `test/fixtures/design-system/flagship/` |
102
+ | B: bench | `ds/bench` | `pi-pocket-ds-b` | `test/design-system-bench/` (fixtures, expected values, runner), `test/design-system-bench.test.ts` |
103
+
104
+ Worktrees are in `/mnt/games/Development/`. Rules: the house rules in `AGENTS.md`; the stream rules of `docs/design/design-mode.md` (own files only, no new npm dependencies, erasable TypeScript, document kinds unchanged except new ones at the end, `npm run format`, `npm run check`, `npm run lint`, `npm test`); **never edit `/mnt/games/Development/pi-pocket`** (the live server); never restart the live server; never push. Commit on your branch. Throwaway copies: `node test/serve.ts <port> 127.0.0.<n>` with T 8911/.11, V 8912/.12, U 8913/.13, G 8914/.14, B 8915/.15. The `browser` tool is one Chromium that people watch and other streams share: navigate, check, leave.
105
+
106
+ ## The scan (T)
107
+
108
+ Today: hex only, 60 variables in walk order, one flat list, first value of a variable only, `.ts` theme files and dot folders skipped. Needed:
109
+
110
+ - All color syntaxes (hex 3/4/6/8, rgb/rgba, hsl/hsla, oklch/oklab, lab/lch, named only when used as a value). Normalize for counting.
111
+ - Variables grouped by the selector or file that sets them; `.dark`, `[data-theme=…]`, and `@media (prefers-color-scheme: dark)` values become a **dark mode**.
112
+ - Tailwind v4 `@theme`, Tailwind v3 `theme.extend` (static parse, no execution), SCSS/Less variables, token files (DTCG, Style Dictionary, and Tokens Studio: every token set, the modes from `$themes`, references across sets, math such as `{spacing.base} * 2`, color modifiers; one file or a folder with `$themes.json` and `$metadata.json`), Style Dictionary sources (token files in several folders, the config's `source` globs in order, classic and DTCG formats, brands and themes as modes, and a config for each mode: `config.dark.json`, a list of configs, a function that returns one for each theme), Material 3 exports (`--md-sys-color-*` in a file or a class for each scheme, and the Theme Builder's JSON: contrast schemes are modes), SCSS palettes made with loops, maps, and color functions (run as Sass runs them, with the module system: `@use … as ns`, `@forward … show/hide/as`, `@use … with`), Panda CSS and Chakra v3 `semanticTokens` with conditions (`base`, `_dark`, `_osDark`), Ant Design `ThemeConfig`, WordPress `theme.json` (palette, gradients, fluid font sizes, font families, spacing sizes and `spacingScale`, shadows, `settings.custom`, and `styles/*.json` variations: a dark one is the dark mode), CSS-in-JS objects in `.ts/.js` theme files (static).
113
+ - Ranking by use (references count), not by walk order. Values kept to 200 characters.
114
+ - Inference of roles (background, surface, text, muted, border, accent, danger, warning, success) from names and use, of the type scale, the spacing scale (a base unit and steps), radii, shadows, durations and easings.
115
+ - Output: a **DTCG draft** (`tokens.json` and `tokens.dark.json` contents) plus the human report. Untrusted data stays fenced as today.
116
+
117
+ ## Verification (V)
118
+
119
+ - `design_preview` gains `checks` (default on), `tweaks` (values to apply), `colorScheme` (`light` | `dark`), `page` (a second HTML page of the bundle), and `actions` (an ordered list of `hover | click | focus` on a selector before the screenshot).
120
+ - `CheckReport.findings`: `off-system-color`, `off-system-font`, `off-system-size` (font size, spacing, radius not on a scale), `contrast` (WCAG 2.2 AA: 4.5, 3 for large text and UI parts), `tap-target` (< 24 px; warn < 44 px), `overflow` (horizontal scroll at the viewport), `image-alt`, `heading-order`, `font-fallback` (declared font not loaded), `missing-viewport`, `missing-pid` (warning). Each: level, selector, pid, value, the nearest token (`var(--color-text-muted)`), and a short fix.
121
+ - Export fixes from the critique: deck PNG uses the requested slide (or every slide, zipped); export applies tweak values and the custom size; a page's PDF uses the viewport's width; PPTX notes drop `style` and `script` text and images render at 2×.
122
+ - Renders queue instead of failing the third.
123
+
124
+ ## The System view (U)
125
+
126
+ - The design picker gets a pinned **Design system** item. Opening it shows the System view with sections: **Colors** (roles grouped, swatches, hex/oklch, the alias chain, contrast badges against their pair, light/dark side by side), **Type** (specimens of the scale), **Spacing, Radii, Shadows, Motion** (visual specimens), **Components** (state grid, each specimen in the sandboxed frame), **Guidelines** (rendered Markdown).
127
+ - **Edit in place** for people who can steer: color picker and text field, number fields with units, an alias picker. Changes preview live on the open design (CSS variables through `pocket-tweak-set`) and on the specimens; **Save** writes through T's `writeDesignSystem` (a route with steer access, validated, atomic) and shows the result; **Discard** reverts. Undo and redo for unsaved changes.
128
+ - **Check** on any design: runs V's `checkDesign`, lists findings, shows them as pins (`pocket-highlight`), and **Send to Pi** puts one message with all findings in the message box.
129
+ - **Publish docs** makes the documentation artifact (G's `renderSystemDoc`) and **Export for code** downloads `dist/` as a zip.
130
+ - Phone first: one column, sticky section tabs, 44 px targets. Viewers see everything read-only.
131
+ - Also fix from the critique: open the phone frame on a phone; a focus mode that hides the chat.
132
+
133
+ ## Guide, docs page, flagship (G)
134
+
135
+ - **Guide** (`guide.ts`): a page skeleton (viewport meta, `<link rel="stylesheet" href="ds/tokens.css">` when a system exists, `data-pid`s, a tweaks manifest bound to tokens, a `pocket:tweak` listener example), craft rules (type scale, 4/8 spacing, contrast, states for every interactive element, focus rings, responsive breakpoints, real copy, no lorem ipsum), how to use the system (only `var(--…)`, components' markup), how to verify (preview with checks, fix every error), and the preview's limits. When a system exists: T's `systemSummary` instead of the whole file. Keep the stable part first for the prompt cache.
136
+ - **Docs page** (`docsite.ts`): a self-contained documentation page for a system, at the level of a professional design-system site (zeroheight, Storybook docs, Radix colors pages): navigation, overview, color roles with contrast tables, type specimens, spacing and radii visuals, shadows, motion demos, component state grids with code snippets, light/dark switch, copy-to-clipboard of token names. Phone and desktop.
137
+ - **Flagship**: Pi Pocket's own design system (Tokyo Night, Geist + JetBrains Mono, the radii and spacing in `web/style.css` and `web/themes/pocket/theme.css`), complete: primitives, semantic roles, light and dark, a type scale, spacing, radii, shadows, motion, at least 8 component specimens with states, guidelines. It is the reference example (`docs/examples/design-system/pocket/.pi/design/`) and the bench's main fixture.
138
+
139
+ ## Bench (B)
140
+
141
+ `node test/design-system-bench/run.ts [--out dir]` prints a JSON score and writes screenshots. It needs no model. It measures:
142
+
143
+ 1. **Scan accuracy**: 4 synthetic fixture projects (plain CSS with `:root` + `.dark`; Tailwind v4 `@theme`; SCSS variables + a `.ts` theme object; a messy real-world page with inline styles and many near-duplicate colors), each with a hand-labelled `expected.json` (roles, scales, modes). Precision and recall of colors, roles, type scale, spacing scale, radii, dark mode.
144
+ 2. **Format**: the flagship and each fixture's saved system load, validate with no error, round-trip (load → write → load is equal), and compile; the CSS parses in Chromium and every variable resolves in every mode.
145
+ 3. **Lint**: 6 seeded designs with known violations (`expected-findings.json`): precision and recall per rule, and zero findings on 2 clean designs that use the flagship correctly.
146
+ 4. **Contrast**: the share of declared contrast pairs that pass in every mode of the flagship.
147
+ 5. **Rendering**: screenshots of the docs page and the System view (mobile 390×844 and desktop 1440×900, light and dark) for the judges.
148
+
149
+ ## Rubric (each round)
150
+
151
+ A panel of two independent judges (different models) scores 0–10 per line with evidence; a line's score is the lower of the two. Target: **every line ≥ 9**. The bench's numbers feed lines 2, 3, 4.
152
+
153
+ 1. **Token model**: DTCG compliance, tiers, aliases, modes, coverage (color, type, space, radius, shadow, motion, breakpoints, z-index), validation messages.
154
+ 2. **Import (scan)**: bench precision/recall ≥ 0.9 on colors and roles, ≥ 0.85 on scales; a draft that needs little editing.
155
+ 3. **Enforcement**: lint precision ≥ 0.95, recall ≥ 0.9, zero false findings on clean designs; fixes name the right token.
156
+ 4. **Accessibility**: contrast pairs pass in every mode; checks cover contrast, targets, focus, alt, headings.
157
+ 5. **Agent experience**: tool schemas and messages are clear; the guide makes Pi produce on-system, polished designs in few calls (judged from tool transcripts and outputs).
158
+ 6. **People experience**: the System view is beautiful, fast, clear, and fully usable on a phone; editing a token is direct and safe; undo works.
159
+ 7. **Documentation output**: the docs page looks like a professional design-system site, in light and dark, on phone and desktop.
160
+ 8. **Code handoff**: the CSS, Tailwind, and JSON outputs are correct, readable, and drop-in.
161
+ 9. **Engineering**: tests, safety (untrusted data, bounds, symlinks), house style, `npm run check`, `npm run lint`, `npm test` green, docs (`docs/features.md`) updated.
162
+
163
+ ## Process
164
+
165
+ Round 0: this page, `system-types.ts`, worktrees. Round 1: the five streams build in parallel. Then the integrator merges into `feat/design-system`, runs the bench, and asks the judges. Each next round takes the lowest-scoring lines and fixes them, smallest change first, and keeps a change only when the score goes up (or a line rises and none falls). Stop when every line is at 9 or more, or two rounds bring no rise. The integrator records each round's scores in `docs/design/ds-rounds.md`.
@@ -0,0 +1,61 @@
1
+ # Stream B (bench): notes
2
+
3
+ Branch `ds/bench`. All files are in `test/design-system-bench/` and `test/design-system-bench.test.ts`, plus this page. Nothing outside them changed. The scoring rules are in `test/design-system-bench/README.md`.
4
+
5
+ ## What it is
6
+
7
+ `node test/design-system-bench/run.ts [--out dir] [--only scan,format,lint,contrast,docs] [--flagship dir] [--no-browser] [--reference]` prints one JSON object (`scores`, `targets`, every metric, `notes`) and writes the docs screenshots (390×844 and 1440×900, light and dark), each scan draft and each lint report to `--out` (default `/tmp/ds-bench`). It runs in about one second on the current tree and about five with everything present. No model, no server.
8
+
9
+ | Phase | Rubric line | Score (0 to 1) |
10
+ | -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | scan | 2 | Mean F1 over colors, roles, type, spacing, radii, dark colors, dark roles, shadows, fonts |
12
+ | format | 1, 8, 9 | Mean over systems of: load, no error, names agree, compile, round trip, idempotent write, `dist/`, CSS parses, defined, valid, correct, dark by media |
13
+ | lint | 3 | F1 of precision and recall over 30 seeded findings, counting every false finding on the clean designs |
14
+ | contrast | 4 | Share of declared pairs that pass in every mode. **Earns 0 until the flagship is in the tree** |
15
+ | docs | 7 | Eight checks plus the seven expected sections; the PNGs are for the judges |
16
+
17
+ Baseline on this tree (`ds/bench` on `107048c`, nothing from T, V, G, or U): overall 0.087; scan 0.435 using the 0.26 scan (`scanTokens`) as a baseline (colors P 0.87 R 0.95; roles P 0.83 R 0.31; type R 0.50; spacing R 0.29; radii R 0.70; dark colors and dark roles 0; shadows R 0.50; fonts P 0.60); every other phase 0 with a note.
18
+
19
+ ## What is in it
20
+
21
+ - **Fixtures** (`fixtures/`): `plain-css` (`:root` + `.dark`), `tailwind-v4` (`@theme` with oklch/hex/hsl, shadcn-style roles through `@theme inline`, `--spacing` base unit), `scss-ts` (SCSS variables, one computed, plus a TS theme with light/dark and an object spread), `messy` (one page, two stylesheets, inline styles, near-duplicate colors, mixed units, a small dark media query). Each has a hand-labelled `expected.json` and traps (comments, data URIs, `&#169;`, `href="#menu"`, a vendored file in `node_modules/`, line-height companions, IE hacks). The `node_modules` trap is committed with `git add -f`. The Tailwind oklch values were converted by hand with a separate program; the test checks the bench's converter against them.
22
+ - **Lint** (`lint/`): the bench's own small system (`lint/system/.pi/design/`), its golden `tokens.css`, six seeded designs (30 findings, all twelve rules), two clean designs (light and dark). Each design is a folder with `index.html` and `expected-findings.json`.
23
+ - **Format** (`format/`): `classic` (string forms) and `modern` (2025.10 object forms, composite types, references inside composites, three modes, `$root`, `$deprecated`) as hand-written systems for T.
24
+ - **Runner and libs** (`run.ts`, `lib/`): own color math (ΔE 2000, WCAG), own DTCG reader, scoring, a headless Chromium on `src/server/browser/` only, the CSS check, the five phases.
25
+ - **Reference code** (`lib/reference*.ts`): an engine (load, write, compile), an oracle scan, a linter, and a docs page, all built on the bench's reader. `--reference` runs the bench on them and must print 1 everywhere. This is the proof that the expected values are right: a plain, independent linter finds exactly the 30 seeded findings, and nothing on the clean designs.
26
+ - **Test** (`test/design-system-bench.test.ts`, 26 tests, about 10 s): color math, the reader, every scoring rule on small hand cases, the fixtures against their own sources (every expected color is written in the sources; every color in the sources is expected), the nearest-token check of each expected fix, the golden CSS is current, the floor (nothing in the tree gives 0, with notes, no throw), the ceiling (reference gives 1), and a sabotaged reference that must score lower.
27
+
28
+ ## What differs from the plan
29
+
30
+ - **Lint runs on the bench's own system for good**, not on the flagship. The expected findings name values and tokens (`#2b6ae0` is near `--color-accent-default`), so they must not move when G changes the flagship. The plan said to switch later; I did not, and added `lint.cleanOnFlagship`: when the flagship defines every `var(--…)` that the clean designs use (the plan's names: `--color-bg-default`, `--color-text-primary`, `--font-size-md`, …), the clean designs are also checked against its own CSS and the findings are reported (not scored). G can make that run by following the names in `lint/system/golden/tokens.css`.
31
+ - **The system handed to `checkDesign` is read by the bench**, not by T's `loadDesignSystem`, so a T bug cannot lower V's score. The format phase checks T's reader on the same system (`bench-lint`).
32
+ - **Contrast earns 0 without the flagship.** Its pass rate for the bench system is still shown. With the flagship in the tree and T missing, the bench reads the flagship itself.
33
+ - The runner does **not** screenshot the System view (U): it needs a running app. The docs page is covered.
34
+ - `--reference` uses the bench system as the flagship, so the ceiling is reachable.
35
+
36
+ ## Contracts the bench assumes (T, V, G, check these)
37
+
38
+ - **Scan (T).** The plan does not fix its name. `lib/modules.ts` looks in `scan.ts` (then `tokens.ts`) for the first of `scanDesignSystem`, `scanProjectTokens`, `scanToDtcg`, `scanDraft`, `draftTokens`, `scanForDesignSystem`, `scanProject`, calls it with the project folder (a copy without `expected.json`; sync or async; 60 s), and reads the result as a DTCG draft: `{ tokens, modes }`, `{ tokens, dark }`, `{ files: { "tokens.json", "tokens.dark.json" } }`, or JSON text. **If T names it otherwise, add the name to `SCAN_NAMES`.** Until then the 0.26 `scanTokens` is the baseline.
39
+ - **Naming in a draft** (the bench scores by name and type): roles as `color.bg.*`, `color.surface.*`, `color.text.*`, `color.text.muted`, `color.border.*`, `color.accent.*`, `color.danger.*`, `color.warning.*`, `color.success.*`; type sizes as `dimension` tokens with `font`/`text`/`type` in the path (`font.size.md`) or `typography` tokens; `space.*`; `radius.*`; `shadow.*`; `fontFamily` tokens. A palette step such as `color.blue.500` is not a role. Pair tokens (`primary-foreground`, `text.on-accent`) have no role. A dark mode is `tokens.dark.json` (or the second mode). See the README for every rule.
40
+ - **Engine (T).** `writeDesignSystem(cwd, { tokens, modes, components, guidelines })` must accept the files as read; `load` after `write` must be JSON-equal; a second `write` of the same change changes no byte; `dist/` holds `tokens.css`, `tailwind.css`, `tokens.resolved.json`. The CSS must be `:root {…}` for the default mode, `[data-theme="<mode>"] {…}` for each other mode, and, for a mode named `dark`, the same inside `@media (prefers-color-scheme: dark)`; every variable must resolve to a valid value for its type (a composite such as `typography` is not checked). `DesignSystem.name` must be the same for two copies of a folder with the same name.
41
+ - **Lint (V).** `checkDesign(bundle, system, options, host, signal)`. The bundle is `{ meta, version, content, assets: [{ name: "ds/tokens.css", type, bytes }] }`. Options shapes tried, in order: `{ viewport: { width, height }, colorScheme }`, `{ viewport: "WxH", colorScheme }`, `{ width, height, colorScheme }`. The system's default mode is `system.modes[0]`; the run for `colorScheme: "dark"` must use the dark values (the bench's CSS has the media query). Findings are matched by rule + `pid` (or a selector holding `data-pid="…"`) + value. Page-level findings (`overflow`, `missing-viewport`) need no pid. The bench's rule definitions are in the README ("The bench's definition of each rule"): V may disagree with one; then change the definition and the expected file together, with a reason, not just the code. Two traps found while building the reference: read authored values from `cssText` (a shorthand holding `var()` reads back as empty longhands), and compare `scrollWidth` with the width that was asked for, not `innerWidth` (a phone zooms out to fit wide content).
42
+ - **Docs (G).** `renderSystemDoc(system)` → `{ html, assets }`, no request leaves the page (the bench refuses every address but its own and counts 404s), works at 390 px with no horizontal scroll, has a `nav`, headings that name colors, type, spacing, radii, shadows, motion, components, at least 1,500 characters and 1,800 px of height at 1440 px, and names at least five tokens. Dark is set by `prefers-color-scheme` and by `data-theme="dark"` on `<html>`; either must change the page.
43
+ - **Flagship (G).** Found in `test/fixtures/design-system/flagship/` or `docs/examples/design-system/pocket/`, either as a project (`.pi/design/tokens.json`) or as the contents of `.pi/design/` (`tokens.json` at the top). `--flagship <dir>` overrides.
44
+
45
+ ## What I checked
46
+
47
+ - `npm run format:check`, `npm run check`, `npm run lint` clean; `npm test` 945 of 945 pass (the new file adds 26 tests).
48
+ - `node test/design-system-bench/run.ts --reference`: 1 in every phase, every target true. A run with nothing in the tree: 0 with notes. A run with modules that throw or return garbage: no crash, a note, 0.
49
+ - By hand: the docs PNGs of the reference page; the lint reports; the Tailwind oklch hexes against an independent Python conversion.
50
+ - I did not start `node test/serve.ts`: the bench needs no app.
51
+
52
+ ## What is still weak
53
+
54
+ - **Roles by name is a heuristic.** It decides roles from the words in a token's path. It is documented and tested, but a scan that names a role in a way the word lists do not know loses points that a person would give. The lists are in `lib/score.ts`; widen them when a stream's names are reasonable.
55
+ - **Four fixtures are few.** The score is the macro mean of four projects, and `messy` is hard on purpose. One fixture failing moves a category by 0.25. More fixtures (Less, Vue single-file components, a Bootstrap-style project) would help the next round.
56
+ - **`messy` encodes a judgment**: values within about one step are merged (`near`). A scan that keeps every raw value loses precision on that fixture only.
57
+ - **The docs phase is structural.** It cannot judge beauty; the judges read the PNGs. The section check is a regular expression on headings.
58
+ - **The format phase scores `typography`, `border`, `transition`, and `gradient` tokens only for load and compile**, not for CSS values: their CSS form is the engine's choice.
59
+ - **`font-fallback` depends on the machine** not having the first family ("Bellweather Serif", a made-up name). The other rules do not depend on the machine's fonts.
60
+ - **`focus-visible` is the least pinned rule** (the plan's list does not name it, `CheckRule` does). One seeded case: a button with `outline: none`.
61
+ - **The bench has no timeout for synchronous engine calls** (`load`, `write`): a loop there hangs the run. The scan and the check have limits.
@@ -0,0 +1,170 @@
1
+ # Stream G notes: the guide, the docs page, and the flagship
2
+
3
+ Branch `ds/guide`. Stream G owns `guide.ts`, `docsite.ts`, `docs/examples/design-system/`, and `test/fixtures/design-system/flagship/`.
4
+
5
+ ## What was built
6
+
7
+ ### The flagship (`docs/examples/design-system/pocket/.pi/design/`)
8
+
9
+ Pi Pocket's own system, derived from `web/style.css`, `web/themes/pocket/theme.css`, and `web/theme-surface.js`. A copy is in `test/fixtures/design-system/flagship/` (a test checks that the two are the same files).
10
+
11
+ - `tokens.json` (the light mode, 380 tokens in all, DTCG with string forms), `tokens.dark.json` (Tokyo Night, the app's own palette), `tokens.high-contrast.json` (text at 7:1).
12
+ - **Primitives**: `color.neutral` (17 steps), seven hue ramps (`blue red yellow orange green cyan magenta`, 10 steps each: 300 is the app's own Tokyo Night value, 700 reads on light grounds and under white text), `color.alpha.*` overlays, a pixel ramp `dim.*`, `font.*` (family, weight, size, leading, tracking), `duration.*`, `easing.*`, `z.*`.
13
+ - **Semantic roles**: `color.bg|text|border|accent|danger|warning|success|info|brand|spark|code|shadow.*`, `space`, `radius` (the app's `--r-*`), `size`, `breakpoint`, `border.width`, `shadow.*` (the app's `--shadow`, `--pop`, the focus ring), `type.*` (11 text styles), `motion.duration|ease|transition.*`.
14
+ - **Component tokens**: `button input switch segmented badge card notice menu step code-block`.
15
+ - **Contrast**: 20 declared pairs, 60 checks across the three modes, all pass. `test/design-flagship.test.ts` also checks every text role on every ground (4.5:1; 7:1 in high contrast), the status colors on their washes, and the field border and focus ring at 3:1.
16
+ - **Components** (10, with 2 to 5 states each): button, input, switch, segmented control, badge, card, notice, menu row, tool step, code block. Each CSS reads only `var(--token)` (no literal color or size), and its `tokens` list is exactly the tokens it reads (a test checks both).
17
+ - `guidelines.md` (6.4 KB): principles, color, type, space, elevation, motion, accessibility, voice, do and don't.
18
+
19
+ ### The docs page (`src/server/design/docsite.ts` and three helpers)
20
+
21
+ `renderSystemDoc(system): { html, assets }` returns one self-contained page (about 730 KB for the flagship; `assets` is empty). Helpers I added, all mine: `docsite-assets.ts` (the CSS and the scripts as text), `docsite-color.ts` (color parsing, WCAG contrast, OKLCH text), `docsite-markdown.ts` (a safe Markdown renderer for `guidelines.md`).
22
+
23
+ - Sections: overview (stats, a swatch strip, validation notes), Color (roles as cards with hex, OKLCH, alias chain, and contrast badges; the palette as ramps; a text-on-ground matrix; the table of declared pairs), Typography (typefaces, weights, text styles, size scale), Space and layout (spacing, sizes, breakpoints, radius, borders, layers), Shadows, Motion (durations and easings with Play buttons and curves, transitions with a hover demo), Components (each as a state grid, do and don't, tokens used, and tabs of the escaped markup and CSS with Copy), Guidelines, All tokens (a filterable table), and Use in code (the compiled CSS files).
24
+ - A switch for each of the system's modes. The page follows the mode: light or dark chrome, by the luminance of the system's ground color. A value that differs by mode is written once for each mode and shown by the mode in force, in CSS alone, so no work is done in script and the switch is instant. The accent of the chrome is the system's own accent when it reads at 4.5:1 on the page.
25
+ - Copy any token name, CSS variable, or CSS code with a tap. A filter box (and `/`) hides what does not match. Scroll spy on the navigation. Phone: a drawer for the navigation, color cards as rows, tables as cards, 44 px targets.
26
+ - **Safety.** No network: a page policy (`default-src 'none'`, no fonts, images, or scripts from outside), no `<link>`, no `@import`. All text is escaped. A token value that could end a declaration or a block (`{ } ; < > \`, `url(`, `@import`, comments) never reaches a style; a custom property name that is not plain is replaced. Component markup and CSS run only in an `iframe` with `sandbox="allow-scripts"` (never `allow-same-origin`), a policy of its own with a random nonce that only the frame's own script has, and `default-src 'none'`: scripts, event handlers, and requests in a component do nothing. The frame and the page talk by `postMessage` (the page checks `event.source` and the shape); no message can make a frame taller than 4,000 px. Markdown links keep only `https:` and `#` addresses.
27
+ - **Bounds.** 3,000 tokens, 60 components, 16 states of one; lists of 120 specimens, 240 color cards, and 480 palette steps; a page over 1.8 MB (an artifact holds 2 MB) shrinks the token table until it fits.
28
+
29
+ ### The guide (`src/server/design/guide.ts`)
30
+
31
+ Rewritten as the plan says. The first part (about 4.8 KB) is the same for every session, so the provider's prompt cache holds it: the canvas, the page skeleton, `data-pid`, the tweaks manifest, decks, variations, the craft rules (phone first, type scale, 4 px grid, contrast, states, real copy, motion, alt text), the check before replying (`design_preview` at two sizes, fix every error, the preview's limits), and feedback and handoff. After it comes one of: how to use the system plus the system's summary (about 8 KB at most), the 0.26 file as before, a notice that `.pi/design/` is unreadable, or the offer to scan. A test checks that the opening is the same in every case.
32
+
33
+ ### Tests
34
+
35
+ `test/design-docsite.test.ts` (10 tests: every section and link, modes, no external request, hostile text in every place, empty and huge systems, color math, Markdown, and a Chromium run that loads the page, sizes the frames, switches the mode, filters, and shows that a component's script does not run), `test/design-flagship.test.ts` (4), and 5 new tests in `test/design-guide.test.ts`. `npm run check`, `npm run lint`, and the whole `npm test` (938 tests) pass.
36
+
37
+ ## Stubs used (delete when stream T lands)
38
+
39
+ - `src/server/design/tokens-stub.ts`: `loadDesignSystem(cwd)` and `systemSummary(system, maxBytes)` with the signatures of the contract. Bounded, symlink-safe reads; resolves references per mode; `problems` is empty and `compiled` is a rough copy. **Integration:** when `tokens.ts` lands, change the one import in `guide.ts` (`import { loadDesignSystem, systemSummary } from "./tokens.ts"`), delete the stub, and `test/design-system-loader.ts` already prefers the real loader when the file exists (it falls back only on "file not found").
40
+ - Guide expectations of T's `systemSummary`: names by role with the default mode's values, the modes, the components with their states, and the guidelines (cut first), at most `SUMMARY_BYTES` (8,000); the guide wraps it in `<project_design_system>` and says it is untrusted. If the real summary is longer, the guide cuts nothing: T's function must keep to `maxBytes`.
41
+
42
+ ## What differs from the plan, and why
43
+
44
+ - **The default mode is named `light`.** T names the default mode; the flagship says so with `$extensions["com.pi-pocket"].mode: "light"` in `tokens.json` (the stub reads it). Without it a loader would call the mode `default`; the docs page copes with either. T: please read that key, or choose the name by another rule and tell me.
45
+ - **Reference-only tokens carry an explicit `$type`.** DTCG lets a token that is only a reference omit it, but a loader may not infer it; the flagship's 83 component tokens state it, so the file is valid for a strict reader.
46
+ - **Tier is set on groups** (`$extensions["com.pi-pocket"].tier` on a group, inherited). Every semantic token is a reference and every primitive a raw value, so a loader that infers the tier gets the same result.
47
+ - **The docs page does not use `compiled.css`.** It builds its own scoped variables from `ResolvedToken.modes[*].css` (so that one page can show every mode at once, and component frames get only the variables they need). It uses `compiled.css`, `tailwind`, and `components` only as text in the "Use in code" section. `assets` is empty: the page needs no file beside it.
48
+ - **Component frames use `allow-scripts` with a nonce**, not `allow-same-origin` with no script as first built: the artifact viewer serves the page with a sandbox policy, and a nested frame cannot get back the origin that its parent lacks, so the page could not measure the frame. Checked in the real viewer route, in the private renderer (`design_preview`), and in `file://`.
49
+ - **No `dist/` in the flagship folder.** It is generated by T's compile; bench: the fixture loads and compiles in memory.
50
+ - **Guide mentions V's new `design_preview` options** (`colorScheme`, asking for a hover, a focus, a tweak value, or a second page "in the call") and `ds/tokens.css` and `ds/components.css` in the bundle (T's `ds/` auto-attach) without their exact argument names. If V names them otherwise, the sentences in `GUIDE` and `USE` need the names; the tests check the sentences' parts.
51
+
52
+ ## Needs from other streams
53
+
54
+ - **T**: read `$extensions["com.pi-pocket"].mode` for the default mode's name (or tell me the rule); inherit `$type` and the tier from groups; infer a missing `$type` from the referenced token; `$value` of a composite (typography, shadow, transition) comes back with every reference resolved, as the stub does; `ModeValue.css` of a reference is `var(--…)`. The docs page reads `value` for colors and dimensions and `css` for the variables. The flagship should load with no error and, ideally, no warning from T's validator: please send me what it says.
55
+ - **V**: the docs page is a good fixture for `checkDesign` (it has a lot of off-system chrome on purpose: the page chrome is not on the system it documents). It must not be checked against the flagship.
56
+ - **U**: "Publish docs" calls `renderSystemDoc(system)` and publishes `html` as an artifact (2 MB limit: the function keeps to 1.8 MB). The page's section ids are `overview color typography layout shadows motion components guidelines tokens code`, and each component is `comp-<slug>`, in case U wants to link to one.
57
+
58
+ ## What I checked
59
+
60
+ - `npm run check`, `npm run lint`, and `npm test` (938 pass).
61
+ - By hand on a throwaway copy (`node test/serve.ts`-style, port 8914): the page as an artifact at `/a/<session>/<id>/<version>` in the shared Chromium, at 390×844 and 1440×900, in light, dark, and high contrast; the mode switch (also in the frames), the drawer, the filter, copy, the Play buttons, and the frame sizes. Also `design_preview` on the published page at mobile and desktop (no console error, no failed request).
62
+ - The flagship's 60 contrast checks in the tests and the matrix in the page.
63
+
64
+ ## What is still weak
65
+
66
+ - No syntax color in the code blocks of the docs page (plain monospace).
67
+ - The page is large (730 KB for 380 tokens, mostly the token table and the escaped component code); a system of a few thousand tokens loses table rows (it says so).
68
+ - The tweaks manifest and `pocket-tweak-set` are not used by the docs page: it has no knobs.
69
+ - The stand-in `systemSummary` cuts the guidelines at a quarter of the budget, in the middle of a sentence; T's version should cut at a line.
70
+ - Not checked on a real iPhone; the drawer and the frames were checked in an emulated phone only.
71
+ - The components were checked by eye in three modes at desktop width; the hover and focus states are drawn by classes (`.is-hover`, `.is-focus`) and also work as real `:hover` and `:focus-visible`, but a coarse pointer was not tested.
72
+ - The shared Chromium showed `scroll-behavior: smooth` mid-scroll in screenshots; the page keeps it (it turns off under reduced motion).
73
+
74
+ ## Round 2 (after merging `feat/design-system`)
75
+
76
+ Four tests failed with the real engine. Causes and fixes:
77
+
78
+ 1. **docsite "asks for nothing"** (test expected the stub's behavior). The real `compiled.tailwind` has a comment that says `@import "tailwindcss"`; the page prints it as escaped text in a code listing. The code is right. The test now looks for `@import` only inside `<style>` elements of the page and of the frames. Not a weaker check: a style with `@import` still fails.
79
+ 2. **guide "holds its summary"** (test expected the stub's summary text). The real summary has other words, and `defang` turns the `<link …>` tag in it into `‹link`, which would mislead Pi. **Code fix:** `USE` now states the `<link rel="stylesheet" href="ds/tokens.css">` tag itself, outside the fence. The test now checks the engine's phrases.
80
+ 3. **guide "hostile system"** (test expected guidelines in the summary; the real summary does not include them, Pi reads them with `design_system read file "guidelines.md"`). The test now puts the hostile text in a token note, which the summary does carry. Same checks: one closing tag, text kept inside the fence.
81
+ 4. **guide "broken .pi/design"** (the stub threw; the real loader returns a system with `problems`). A broken system is now an `N errors` line in the summary, and the guide tells Pi to run `design_system validate` and say so. `.pi/design/` wins over the old file even when broken. The symlink check stays: nothing from the link's target reaches the prompt.
82
+
83
+ Other changes:
84
+
85
+ - `guide.ts` names the real arguments: `design_preview` (`colorScheme`, `tweaks`, `actions`, `page`, `slide`, `fullPage`; `checks` is on by default), `design_export` (`tweaks`, `viewport`, `slide` as a number or `"all"`), and `design_system` (`scan`, `init` with `fromScan`, `changes`, `replace`, `modes`; `set`, `component`, `guidelines`, `validate`, `read` with `file`). A test checks that each argument the guide names is in the schema in `index.ts`. `ds/tokens.css`, `ds/tailwind.css`, and `ds/components.css` are named as the files the app attaches.
86
+ - `SUMMARY_BYTES` is 12,000 (was 8,000): at 8,000 the real summary showed only colors, then cut. T's summary lists primitives (`dim`, `font`, `easing`, `z`) before roles (`space`, `radius`, `type`) and the component list after the component tokens; **T: list roles and components first.** The guide then needs no larger budget.
87
+ - **Flagship:** the engine gave 2 warnings (`--notice-*` and `--step-ink`, custom properties local to a component). I rewrote `notice.html` and `tool-step.html` to use tokens only, regenerated their `tokens` lists, and copied the files to `test/fixtures/design-system/flagship/`. `loadDesignSystem` now returns **0 problems** (0 errors, 0 warnings), and `design-flagship.test.ts` asserts `problems` is empty.
88
+ - `npm run format`, `npm run check`, and `npm run lint` pass. The full `npm test` had 1,105 of 1,106 passing; the one failure (`design-bridge-ui`: a deck shows one slide at a time) timed out under load and passes alone (18 of 18).
89
+
90
+ ## Round 3
91
+
92
+ - **Token names.** Durations are roles now: `duration.stagger 24`, `fast 150`, `base 175`, `slow 420`, `slower 540`, `spring 560` (the app's 140 and 410 are rounded to 150 and 420, so that hover and exit share one token and enter and glide share one). `motion.duration.*` and the transitions point at them. The pixel ramp `dim.*` (named by value) is gone: `space`, `radius`, `size`, `breakpoint`, and `border.width` hold their pixel values as primitive scales (steps and roles, not values), and the two odd sizes components needed are `space.hair` and `size.dot`. The alpha overlays are `color.alpha.light|dark.faint|soft|medium` (were 7, 10, 17). `radius.sheet` and `radius.float` stay: both are 12 px today; `float` says in its description that it is a role of its own. 348 tokens now.
93
+ - **Disabled text.** `color.text.faint` is `color.text.disabled`, described as disabled controls only. A placeholder uses `color.text.muted` (a placeholder is not exempt). The engine has no exemption flag yet, so the token declares no contrast pair. **When T adds one, the flagship change is:** add `"$extensions": { "com.pi-pocket": { "contrastExempt": "disabled" } }` (T's key name) to `color.text.disabled` in `tokens.json`, and the same fixture copy.
94
+ - **Docs page, phone.** The header keeps the system name; the three-way switch is a menu (`select`) on a phone. The overview cards are two columns. Hero swatches are labelled chips (the short name under each, the full name in a tooltip, a tap copies it).
95
+ - **Role cards.** Groups of one or two cards share one grid ("Brand · Spark · Shadow").
96
+ - **Copy.** Each color card has `CSS var`, `Tailwind` (`bg-`, `text-`, or `border-` plus the name after `--color-`, which the compiled `@theme` makes a utility), and `JSON` (`color.bg.surface.$value`) buttons.
97
+ - **Footer and ratios.** The footer has the name, the token count, the modes, the components, and the date. A ratio has one decimal, cut and not rounded (4.48 shows as 4.4, never 4.5), everywhere.
98
+ - **Counting rule (first version; replaced by the headline rule at the end of these notes) (agreed with U; U's `sectionOf` in `extensions/design/system.js` is the source, and `sectionOf` in `docsite.ts` is the same rule).** Each token is in exactly one section, chosen by its type (and for dimensions and numbers by the words of its path), whatever its tier: a component's tokens count too. The token sections are Color, Typography, Spacing, Radii, Shadows, Motion, and Other; their counts add up to the system's token count (a test checks it). A token with no specimen of its own is listed in a "More tokens" table at the end of its section, so every counted token is on the page. **Components** counts components (not tokens), **Guidelines** has no count, and **All tokens** counts all tokens. The docs page now has the same seven token sections as the view (it had "Space and layout" and "Other tokens").
99
+ - **Guide.** The no-system text says to make a system in three calls: `scan`, `init` with `fromScan` and `changes` for every role the scan guessed or marks uncertain, then `validate`. (The scan's output already says to save with `init fromScan`; the guide adds the correction and the check.)
100
+ - **Still weak.** The page is 840 KB (component colors and the "More tokens" tables). The durations section shows both the primitive and the semantic durations, which repeat. No syntax color in code listings.
101
+
102
+ ### Round 3, second judge's items
103
+
104
+ - **Grammar.** `plural(n, noun)` and `article(word)` (in `docsite-markdown.ts`) make every counted phrase ("1 mode", "2 modes", "All 20 contrast checks meet their minimum", "The contrast check meets its minimum"), and a test reads every generated sentence of the flagship and of a one-of-each system for "a" before a vowel, "an" before a consonant, a plural noun after 1, and a singular after another number. The flagship's "The border of a info message" is "an info message" now.
105
+ - **Hero.** The flagship's description is one sentence (the sources are in the README), the lead text balances its lines, and on a phone the stat cards are a wrapping row that fills (3 and 2) and an odd last overview card takes the whole row.
106
+ - **Guide.** The system tail ends with `SYSTEM_EXAMPLE`: a short card design with the `ds/` links, roles through `var(--…)`, a component's markup and classes, `data-pid`s, a tap-size line, and a tweaks manifest bound to tokens. A test renders it with the flagship in Chromium (light and dark) through `checkDesign`: no error, no tap-target or off-system finding (a `font-fallback` warning stays, because the flagship's Geist is not in the bundle). The stable part still comes first.
107
+
108
+ ### Round 3, stream V's two findings
109
+
110
+ - The code block's inner `pre` and `code` took the browser's `monospace`: the component CSS now sets `font: inherit` on them, so they use `font.family.mono`.
111
+ - The hint of a hovered menu row in dark was 4.48:1 on the alpha hover overlay (an overlay has no opaque ground, so no pair could be declared on it). `menu.row-hover` now points at `color.bg.selected`, the opaque ground that `color.text.muted` already declares its pair on (4.5:1 in every mode, checked by the validator and the tests). `test/design-lint-pages.test.ts` now expects no `monospace` finding and no contrast finding in light and dark.
112
+
113
+ ## Round 4
114
+
115
+ - **Exempt pair.** The flagship's `color.text.disabled` declares `contrast: { on: "{color.bg.surface}", min: 4.5, exempt: "disabled" }`. The engine notes it (`DesignSystem.notes`, one `info`) and `problems` stays empty. The tests skip an exempt pair in the "passes in every mode" checks and assert that it is exactly this one.
116
+ - **Docs page.** The contrast table shows an exempt pair with the ratio in every mode and an "exempt (disabled)" label (a failing ratio is not a failure there; a passing one, such as high contrast, shows its level), and it is counted in neither number of "60 of 60". A color card says "exempt (disabled); would need 4.5:1 on …". `DesignSystem.notes` show in a small "N notes from the validator" area under the problems. A token with several pairs (`contrasts`) gets a row for each.
117
+ - **Use in code.** Three "use it" blocks: CSS (link `tokens.css`, `var()`, `data-theme`), Tailwind v4 (`@import "tailwindcss"; @import "./tailwind.css";` and a utility), and JSON (Style Dictionary config over a `tokens.<mode>.resolved.json`, and Tokens Studio's load). Under them, the generated files as folds: `tokens.css`, `tailwind.css`, `components.css`, the compact `tokens.resolved.json`, and a `tokens.<mode>.resolved.json` for each mode (the first 6 KB of each, with the size). The page is 968 KB for the flagship.
118
+
119
+ ## Round 4 (second part)
120
+
121
+ - **Blank component frames: a real defect, now gone.** The bench's tiles are captures of a part of the page that is below the fold (`Page.captureScreenshot` with a clip and `captureBeyondViewport`). A sandboxed `iframe` (no `allow-same-origin`, so an opaque origin) is drawn by its own renderer process, and that process does not paint a frame that was never scrolled into view: the capture showed the frame's white panel. Scrolled into view, or looked at in the viewer, the frames painted (that is what the other judge saw), so it was a defect of every capture (the bench, `design_preview` with `fullPage`, a PDF export). Proof: the bench's components tiles were white before this change and show all states after it.
122
+ - **Fix.** The states are drawn in the page itself, in a shadow root, with no frame. The page keeps the markup and CSS once, as escaped text in the code listings under each component; the page's script parses each state in an inert document (`DOMParser`: nothing runs or loads), removes `script`, `iframe`, `object`, `embed`, `link`, `meta`, `base`, `template` and the like, every `on…` attribute, and every address except `#…` and small `data:image/…`, and puts the result in a shadow root with the component's CSS. Links and forms in a specimen go nowhere. The shadow root takes the page's custom properties, so the mode switch recolors the states with nothing sent to them. Hard edges: the page's policy has `default-src 'none'`, no `frame-src`, `form-action 'none'`, `base-uri 'none'`, and images and fonts as data only. (Superseded by the security fix below: the strip is now an allowlist, and script runs only with a nonce.) It is checked in the artifact route with its sandbox header (all 10 stages drawn).
123
+ - **For stream B.** Each state is drawn when the page's script has run, on load. The page sets `data-ready` on every `.comp-stage` and `data-docs-ready` on `<html>` when all are drawn: a capture can wait for `html[data-docs-ready]`. Nothing else needs waiting for (no frame to load or to size).
124
+ - **Page size: 968 KB to 559 KB** for the flagship (the test asserts under 600 KB). No `srcdoc`, no per-frame token copy, no per-frame script; the search reads each item's own text, not a copy (`data-s`); a token chip copies its own text; a color card's three copy buttons are made from three attributes; a mode is `data-m="1"`; the generated files show their first 8 KB with the size (the whole files are in `dist/`).
125
+ - **Hero swatches** are chosen by role (background, surface, text, muted, border, accent, danger, warning, success, info, brand, code), labelled by the one-word role, with the full token name as the tooltip and the copied text. **Shadow tiles** align at the top. **Spacing** steps are in two columns and the bars are in proportion to the longest step (so a row is used); sizes are in two columns. **Radii** are grouped by use (marks and tags, controls, containers, round), each group with a line on why.
126
+ - **Split.** `docsite.ts` is the page (456 lines); the sections are `docsite-color-section.ts`, `docsite-type.ts`, `docsite-space.ts`, `docsite-shadows.ts`, `docsite-motion.ts`, `docsite-components.ts`, `docsite-reference.ts`, over `docsite-core.ts`. The split commit (2074c59) was checked byte for byte against the file before it on three systems (the flagship, a small system, and an empty one; nonces and the date normalized).
127
+
128
+ ## Round 4: the security review's finding (SMIL and more), fixed
129
+
130
+ The review found that the first sanitizer was a denylist: `<animate attributeName="href" values="javascript:…">` (and `set`) inside an SVG link passed, a click ran the script, and `script-src 'unsafe-inline'` allowed it. The fix is in layers:
131
+
132
+ - **An allowlist, not a denylist** (`docsite-sanitize.ts`). The page parses a state in an inert document and builds a _new_ tree: only an element and an attribute on a list are copied. HTML: text, table, form-control, and sectioning elements (no `form`, `iframe`, `object`, `embed`, `link`, `meta`, `base`, `template`, `script`). SVG: shapes, text, gradients, `use` (only to `#id`), and a few filter primitives; no `animate`, `set`, `animateTransform`, `animateMotion`, `mpath`, `discard`, `foreignObject`, `image`, or `script`; MathML is dropped whole. Attributes: `class id role title lang dir tabindex hidden style`, `aria-*`, `data-*`, a list for HTML (no `action`, `formaction`, `srcdoc`, `target`, `autofocus`) and a list for SVG presentation (no `attributeName`, `to`, `from`, `by`, `begin`, `dur`; `values` only on `feColorMatrix`). An address (`href`, `xlink:href`) is kept only as `#id`, and `src` only as a small `data:image`. A presentation attribute with `url()` keeps only `url(#id)`. A `javascript:` or `data:text` value is dropped from any attribute. The `style` attribute, a `<style>`, and the component's CSS lose `@import` and every `url()` but `#id` and a small image. Nodes and depth are bounded.
133
+ - **A nonce policy.** The page's script-src is `'nonce-…'` only, with a new nonce for each page on the page's two scripts. A `javascript:` address is no script of the page, so the policy blocks it too, and a probe that gets past the allowlist still runs nothing. The artifact viewer's bridge is the first thing in the page, before the policy, so it has run: I checked in the viewer's frame route (sandbox flags as the viewer's) that the bridge connects (`pocket-bridge` with its port), the mode switch, the copy buttons, the navigation, and the component states all work.
134
+ - **The click guard** finds a link by `localName` (HTML and SVG), and a click in a specimen never follows an address.
135
+ - **Containment.** The shadow root is on a box inside the stage, and the stage has `contain: layout paint`, `overflow: hidden`, and `isolation: isolate`: a component whose CSS makes `:host` fixed, huge, and `!important` is placed against its own stage and clipped to it, and cannot cover the page or take a click.
136
+ - **Tests** (real Chromium, real mouse events through `Input.dispatchMouseEvent`, each probe a component): SMIL `animate` and `set` and the other animation elements on `href`; an SVG `<a>` with `xlink:href` and `href` script addresses; `use` to an external address; `foreignObject` with HTML, a handler, and a script; `math` with an `href`; a `style` attribute and CSS with `url()` and `@import`; a `:host` overlay; a form with `action` and `formaction`; HTML links, images, a frame, an object, an embed, `meta refresh`, `base`, and `link`. Each asserts that the shadow root holds none of it, that no global was set, that the page did not move, and that nothing covers the page. I checked that the probes bite: with a weakened sanitizer the tests fail. A test also checks that the allowlists name no animation, frame, form, or action.
137
+
138
+ ## The counting rule (final, the same as the System view's)
139
+
140
+ **A section's headline count is its role tokens (the semantic tier; a section with none counts its primitives), and the palette (the primitives of a section that also has roles) and a component's own tokens are counted inside the section, each in its own line; the three add up to the section's tokens, every token is in exactly one section (`sectionOf`), and the sections add up to the system's tokens.** The navigation, the overview cards, and the one line under each section's title (`52 roles · 97 palette colors · 62 component colors`) use it: the flagship's Color is 52 (not 211), and its 97 and 62 are in the section. Components counts components, and All tokens counts every token. A test (`design-docsite`) checks the headline, the line, and the sums against the rule for every section.
141
+
142
+ ### Hardening: the CSS cleaner (the reviewer's finding A, and B)
143
+
144
+ `cleanCss` was a regex denylist: it missed CSS escapes (`@\69mport`, `u\72l(`) and `image-set("https://…")`, and Chromium tried to load such an image (the page's `img-src data:` blocked it). It is now a parser that keeps what is safe: it reads the CSS as rules and declarations (aware of strings, parentheses, and braces), decodes the escapes of each declaration and checks the decoded text, and drops a declaration whole when it holds `image-set`, `image(`, `cross-fade(`, `element(`, `src(`, `paint(`, `expression(`, `behavior:`, `-moz-binding`, `javascript:`, or a `url()` whose argument is not `#id` or a small `data:image` (png, gif, jpeg, webp). Only `@media`, `@supports`, `@keyframes` (and `-webkit-`), and `@container` rules stay (their rules cleaned too); `@import`, `@font-face`, `@namespace`, `@property`, `@page`, `@layer`, `@document`, and all others go, also when written with an escape. Harmless escapes stay (`content:"\2713"`, `.sm\:flex`). A style attribute goes through the same rules (`cleanDeclarations`). Nesting is bounded, and broken or unterminated text never throws and keeps no bad text. Tests: `test/design-docsite-sanitize.test.ts` runs the page's own script in Node and asserts the output for every input class above (finding B), and a Chromium probe (`css-fetch`: image-set, `-webkit-image-set`, cross-fade, element, src, escaped `url` and `@import`, `@font-face`, in a style attribute, a style element, an SVG presentation attribute, and the component's CSS) asserts that nothing is in the shadow root, that no request failed or was blocked (`failedRequests`) and none was made (`performance` entries), and that the computed styles are `none`. With the check switched off the probe fails.
145
+
146
+ ### T's docs-page changes, ported into the split files
147
+
148
+ T's round 4 patch (`ds-t-docsite.patch`, now deleted) is in `docsite-core.ts` (`twVar` in the context, from `tailwindNames` of `tokens-compile.ts`), `docsite-color-section.ts` (`copyRow(ctx, token)`: the Tailwind class comes from the compiled theme's name, so `bg-surface` and `text-primary`, while the CSS-var button still copies `var(--color-bg-surface)`), and `docsite-reference.ts` (the Tailwind utility from the same names; the block "JSON (DTCG)" with the Style Dictionary config and the 2025.10 note; a "Tokens Studio" block; `tokens.studio.json` in the file list; `tokens.resolved.json` last, as a compact summary). The tests changed as the patch says.
149
+
150
+ ## Round 5
151
+
152
+ - **Ramps.** Every hue (`blue red yellow orange green cyan magenta`) is one regular ramp of 11 steps (50, 100, 200 … 900, 950) that falls in OKLCH lightness at each step (a test checks it for every ramp, neutrals too). Tokyo Night's own accent is the ramp's step **400** (`color.blue.400` is `#7aa2f7`), so the app's colors are on the ramp and not beside it; the other steps are made around it (lightness runs evenly from 0.955 down to 0.25 on each side of it; chroma follows a bell). Roles pick their steps by contrast (a script searched each hue and mode; the tests hold every pair: 4.5:1, 7:1 in high contrast). Neutrals keep the app's own grays: steps of 100 up to 700 and of 50 to 950; `350` and `650` are gone, and `550` and `750` stay as half steps with a description that says why (550 is the one gray that reaches 3:1 on light and dark grounds; 750 is the dark mode's raised ground).
153
+ - **Space, size, and corners.** `space.*` is the 4 px scale only (11 steps) and `size.*` is heights, targets, icons, and the avatar. The gaps of the layout are `layout.gap.in|out` (roles that point at a step); `space.hair`, `size.dot`, `size.step-mark`, and `size.switch.*` moved to the components that own them (`badge.padding-y`, `badge.dot`, `button.focus-offset`, `step.mark-size`, `switch.width|height|thumb`, `segmented.gap`, `menu.padding`). `space` and `size` are the semantic tier (a design reads a step as it is; there is no pixel layer under them). Corners are a scale `radius.scale.xs|sm|md|lg|xl|full` (2, 4, 6, 8, 12, 999) and ten roles that point at it. **Three roles moved from the app's own corners**: `seg` 5 to 4 px, `control` 7 to 6 px, and `window` 10 to 8 px (the same as a card); each says so in its description.
154
+ - **Docs: "Use in code".** The Style Dictionary block is plain valid JSON (the explanation is beside it); the Tokens Studio block is a real piece of `tokens.studio.json` (the first set with a token, the first theme, the order of sets, cut from the generated file); the four cards are as tall as the tallest in a 2 by 2 grid, and their code scrolls with its scroll bar in view.
155
+ - **Docs: "All tokens".** A column for each mode (each with its own swatch), a search of names and values, a type filter and a tier filter, a count; the page's own filter reads values too. On a phone the table draws 60 rows and more as it is scrolled (or tapped), and a search draws them all first. Every section, component, and sub-heading has a link (an icon on hover or focus, always faint on touch); a tap copies the address; an address with a hash opens the folds around its target.
156
+ - **Engineering.** `docsite-assets.ts` is 26 lines: the CSS is five parts (`docsite-css-*.ts`) and the script is six (`docsite-js-*.ts`), joined; the text of `DOC_CSS` and `DOC_JS` was checked equal to the old file's before any other change (commit 63e7843). The page is 592 KB (a test holds it under 600 KB): rows no longer carry a type, a tier, or a variable chip that the script can make, heading links draw their icon in CSS, and a generated file shows its first 4 KB.
157
+ - **Summary budget.** The system summary (12 KB) now has room for no token notes with this flagship (T's rule: notes go last-first), so the hostile-text test puts its text in the system's own description, which the summary always carries.
158
+ - **Found by stream V's page check.** With the new ramps the dark accent wash (`color.accent.soft`, step 900) made muted text on a selected card 4.33:1; every dark status wash is step 950 now (5.5:1 or more for muted text), and `test/design-lint-pages.test.ts` holds it. **The Tailwind fixture** `test/fixtures/design-system/pocket-tailwind-utilities.txt` was regenerated by a real Tailwind 4.3.3 compile (candidates from the test's model, compiled in `/tmp/tw` outside the repo; all 718 were made, none missing). The bench test "the component check reads each stage's shadow root" has a race of its own (its page sets `data-docs-ready` 300 ms after load, and the test waits 300 ms for it to be absent), so it can fail under load and passes alone.
159
+
160
+ ### Merged with T's round 5
161
+
162
+ `ds/tokens` is merged into this branch. The flagship has no warning under T's ramp check (all ramps are steady in lightness). `dist/` (with the new `names.md`) and the fixture copy are updated, and the Tailwind utilities fixture is again from a real Tailwind 4.3.3 compile (718 of 718 made). The docs page lists `names.md` in the files of "Use in code" and links to it from the Tailwind card. No utility name is written in the page's code: the copy buttons, the Tailwind snippet (a color class and a padding class), and the file list all come from `tailwindNames` (a class is left out when the system has no token for it).
163
+
164
+ ## Round 6
165
+
166
+ - **Code color.** `docsite-js-code.ts` is a tokenizer of about 60 lines for CSS, JSON, HTML (with CSS: the `web` language of the two "use it" cards), and JS. It reads `pre.snip[data-lang]`, and builds the code from text nodes and `<span class="sx-…">` elements (never `innerHTML`), so project text stays text; a test puts a hostile description in `tokens.css` and checks it. The colors are the system's `color.code.*` tokens, set as `--sx-*` on the code section (the CSS falls back to the page's own colors when the system has none), and the panel's ground is the system's `color.code.bg`, so a mode that changes the tokens changes the code. A listing over 20 KB stays plain. The cards have their own height, and the code has less empty space at the top. JSON snippets use two-space indents (four made the Tokens Studio snippet run off the card).
167
+ - **All tokens.** A value that is the same in every mode is one cell across the mode columns ("in every mode", with a rule), which also made the page 12 KB smaller. On a wide screen the token column is wide enough for the name and its variable on one line.
168
+ - **Shadows.** A shadow shows its layers as a small table: x, y, blur, spread, and a swatch with the color and its opacity (`#282846 14%`), in the Shadows section and in the token table.
169
+ - **Flagship grounds.** Light `color.bg.sunken` is a new half step `color.neutral.150` (#dcdee6, a shade darker than the canvas, with muted text at 4.6:1 on it; 200 is too dark); `color.bg.selected` is `color.blue.100` (an accent tint); `color.code.bg` is the sunken role. `raised` is the same white as `surface` in light mode, and canvas/base/sunken are one black in high contrast: both said in the descriptions, and a test holds that nothing else is equal in light and dark. Muted text on the selected tint is 4.5:1 (it was 4.7:1 on the gray).
170
+ - **Open with T.** `dist/README.md` and the full comments in `tokens.css` are T's (the compiler writes both). I asked in a message.