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,303 @@
|
|
|
1
|
+
# Design systems, stream T (tokens engine): notes
|
|
2
|
+
|
|
3
|
+
Branch `ds/tokens`. The engine, the tool, the scan, and the `ds/` auto-attach are built and tested.
|
|
4
|
+
`system-types.ts` and a first working `loadDesignSystem` were committed early (`5440256`).
|
|
5
|
+
The other streams can import them now.
|
|
6
|
+
|
|
7
|
+
## What I built
|
|
8
|
+
|
|
9
|
+
| File (all in `src/server/design/` unless noted) | What it does |
|
|
10
|
+
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
11
|
+
| `system-types.ts` | The shared types. Changes listed below. |
|
|
12
|
+
| `tokens.ts` | The contract: `loadDesignSystem`, `writeDesignSystem`, `compileDesignSystem`, `systemSummary`, plus `DesignSystemError` (has `.problems`), `problemLine`, `defaultModeName`, `DESIGN_DIR`. |
|
|
13
|
+
| `tokens-model.ts` | DTCG parse, types, references, tiers, modes, contrast, validation, and the `DesignSystem` build. Pure. |
|
|
14
|
+
| `tokens-values.ts` | One converter for each DTCG type (both value forms) to CSS. Every message says how to fix the value. |
|
|
15
|
+
| `tokens-compile.ts` | `tokens.css`, `tailwind.css` (v4), `tokens.resolved.json`, `components.css`. Pure. |
|
|
16
|
+
| `tokens-io.ts` | Bounded, symlink-safe reads and atomic writes of `.pi/design/`. `readDesignFile`, `hasDesignFolder`. |
|
|
17
|
+
| `tokens-summary.ts` | `systemSummary(system, maxBytes)`. |
|
|
18
|
+
| `tokens-base.ts` | Limits and small helpers. `utf8Cut` and `boundedText` moved here; `system.ts` re-exports them. |
|
|
19
|
+
| `components.ts` | The component specimen parser. |
|
|
20
|
+
| `color.ts` | Color math: every CSS syntax, DTCG color objects, WCAG 2.2 contrast, Oklch, `color-mix()`. V can reuse it (`parseColor`, `toHex`, `contrastRatio`, `toOklch`). |
|
|
21
|
+
| `scan.ts`, `scan-files.ts`, `scan-parse.ts`, `scan-facts.ts`, `scan-import.ts`, `scan-colors.ts`, `scan-scales.ts`, `scan-infer.ts` | The structured scan (see below). |
|
|
22
|
+
| `system.ts` | The `design_system` tool. The 0.26 file functions are unchanged. |
|
|
23
|
+
| `../extensions/artifacts.ts` | The `ds/` auto-attach. |
|
|
24
|
+
|
|
25
|
+
### Changes in `system-types.ts` (all additive except `schemes`)
|
|
26
|
+
|
|
27
|
+
- `ModeValue`: `literal` (CSS with every reference resolved, so a swatch needs no variable), `hex` (colors), `parts` (a typography token's members as CSS), `contrast` (`{ on, ratio, min, pass }` in that mode).
|
|
28
|
+
- `ResolvedToken.tailwind` (an explicit Tailwind variable name).
|
|
29
|
+
- `DesignSystem.schemes`: **new required field**. Whether each mode is `light` or `dark`. A test fixture that builds a `DesignSystem` by hand needs it.
|
|
30
|
+
- `SystemChange`: `name`, `description`, `remove`, and `set[].type` / `set[].description`. The fields are applied in this order: `tokens`, `modes`, `name`/`description`, `set`, `remove`, `components`, `guidelines`.
|
|
31
|
+
- `ModeValue.literal`, `hex`, `parts`, and `contrast` are optional in the type but the engine always sets `literal`.
|
|
32
|
+
|
|
33
|
+
### The `design_system` tool
|
|
34
|
+
|
|
35
|
+
Actions: `read`, `write`, `scan`, `init`, `set`, `validate`, `compile`, `component`, `guidelines`.
|
|
36
|
+
|
|
37
|
+
- `read`: the summary (fenced as project data), or `file` for one file of the folder (a whitelist of names). With no folder it reads the 0.26 file, as before.
|
|
38
|
+
- `scan`: the structured report with the DTCG draft, fenced.
|
|
39
|
+
- `init`: `tokens` and `modes` (DTCG objects), or `fromScan: true` (and `path`). `changes` apply after, so one call saves a scan and corrects a role. It **refuses to overwrite** a system unless `replace: true`.
|
|
40
|
+
- `set`: `changes: [{ token, value, mode?, type?, description? }]` and `remove: [{ token, mode? }]`. A `mode` that is new makes `tokens.<mode>.json`. A value can be a whole token object (`{ $value, $type }`).
|
|
41
|
+
- `validate`: reports, writes nothing. `compile`: rewrites `dist/`.
|
|
42
|
+
- `component`: `slug` and `content` (the specimen HTML), or `drop: true`. `guidelines`: `content`.
|
|
43
|
+
- `write` (the 0.26 file) is refused while `.pi/design/` exists, with a message that names the new actions.
|
|
44
|
+
- Not replay-safe, as before (a restart gives "interrupted" rather than a second write).
|
|
45
|
+
|
|
46
|
+
### The `ds/` auto-attach
|
|
47
|
+
|
|
48
|
+
`publish()` in `artifacts.ts`: when an HTML page contains `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css`, the current files are compiled from the sources in `.pi/design/` (never stale) and added as assets under those names. Not added when the call brings an asset of that name or lists it in `removeAssets`. The result text says what was attached, says so when the project has no system, and says when the system has errors. The work happens before the commit, so a replayed call finds the version it wrote (tested).
|
|
49
|
+
|
|
50
|
+
### The scan
|
|
51
|
+
|
|
52
|
+
Reads CSS, SCSS, Less, HTML/Vue/Svelte `<style>` and `style=""`, CSS-in-JS templates and style objects, Tailwind v4 `@theme` and v3 `theme.extend` (a static literal reader, no code runs), JS/TS theme objects, and token files (DTCG, Style Dictionary, Tokens Studio). A project with 8 or more tokens in a token file gets them back as they are.
|
|
53
|
+
|
|
54
|
+
- Variables are grouped by scope: default, dark (`.dark`, `[data-theme=dark]`, `prefers-color-scheme: dark`), explicit light, or a component (reported, not drafted). A dark-first project (dark default plus a light scope) is detected: its default mode is `dark` and the other file is `tokens.light.json`.
|
|
55
|
+
- Colors: all syntaxes, `color-mix()` and `var()` computed like the browser (checked against Chromium), shadcn-style `H S% L%` channels, color names where a color is a value. Near duplicates (Oklab distance under 0.0065, about 2 levels per channel) merge; variables are never merged.
|
|
56
|
+
- Roles (background, surface, text, muted, border, accent, danger, warning, success): by the name of a variable first (a scored word match, with color sanity: hue for the status colors, chroma for the accent, contrast for the text), by use second (the root background, the most used text, the most used chromatic color, the hue nearest the status centers). Output as `color.bg.page`, `color.bg.surface`, `color.text.primary`, `color.text.muted`, `color.border.default`, `color.accent.default`, `color.danger|warning|success.default`, plus `color.text.on-accent`, each an alias of a palette primitive. Contrast pairs are declared on the text roles.
|
|
57
|
+
- The project's own variable names are kept (`radius.md`, `space.4`, `font.sans`, `color.brand.500`); what it does not name is read from use (type scale with a base size and a ratio, a 4 px spacing scale with the off-grid values reported, radii, shadows parsed into layers, durations, easings, breakpoints, weights, line heights). Tailwind utility classes (`text-sm`, `rounded-lg`, `p-4`) fill the scales for a Tailwind project.
|
|
58
|
+
- The draft is run through the engine and any token it refuses is dropped, so `init fromScan` always saves a system that loads.
|
|
59
|
+
- Safety as before: bounded walk (400 files, 3000 candidates, 20 000 entries, depth 8, 200 KB a file, 8 MB in all), no symlink followed, files ranked so the theme is read before a deep component, report fenced and defanged.
|
|
60
|
+
- `scanTokens(root)` still returns `files`, `partial`, `variables`, `colors`, `fonts`, `radii`, and now `draft`, `inferred` (roles, scales, notes), and `tailwind`. `draftDesignSystem` (the 0.26 Markdown draft) is gone: nothing used it.
|
|
61
|
+
|
|
62
|
+
## What differs from the plan
|
|
63
|
+
|
|
64
|
+
- A **contrast failure is a warning**, not an error. A person who picks a failing color in the System view must still be able to save. Both are in `problems`; the bench should count the pass or fail in `ModeValue.contrast`.
|
|
65
|
+
- `writeDesignSystem` refuses a change only when it **adds** an error. A system that already has an error can be repaired one token at a time. It writes no file at all when it refuses.
|
|
66
|
+
- `tokens.css`: the default block is `:root, [data-theme="<default>"]`. Each mode block repeats every token whose **resolved** value differs, so a token that only holds `var(--x)` is declared again. Without that, a nested `[data-theme="dark"]` scope keeps the outer value (a custom property that holds `var()` is computed where it is declared). Checked in Chromium. The media query is `:root:not([data-theme])`, so an explicit `data-theme` always wins.
|
|
67
|
+
- The default mode's name is `$extensions["com.pi-pocket"].mode` in `tokens.json` (`light` when absent). A dark-first system sets it to `dark`.
|
|
68
|
+
- `tailwind.css` has the default mode in `@theme static { … }`, other modes as plain rules, and `@custom-variant dark` for `[data-theme="dark"]`. A token in a Tailwind namespace (`--color-*`, `--font-*`, `--text-*`, `--font-weight-*`, `--spacing-*`, `--radius-*`, `--shadow-*`, `--ease-*`, `--breakpoint-*`, `--leading-*`, `--tracking-*`) is declared under that name; if the name differs from the token's own variable, the own variable is declared too as `var(--tailwind-name)`, so `var(--space-4)` works in a Tailwind project. A typography token also gets `--text-<name>`, `--text-<name>--line-height`, and so on. `$extensions["com.pi-pocket"].tailwind` names a variable by hand.
|
|
69
|
+
- Typography tokens compile to `--type-body` (a `font` shorthand) and `--type-body-font-size` etc.
|
|
70
|
+
- Tokens may omit `$type` when the value shows it (a warning says which type was read). A unitless dimension is read as pixels (a warning).
|
|
71
|
+
- Extra files in `src/server/design/` beyond `tokens.ts`: the table above. They are all mine.
|
|
72
|
+
- Component specimens: scripts, inline event handlers, `@import`, and markup in the CSS are errors; raw colors, unknown `var(--…)`, and unscoped selectors are warnings.
|
|
73
|
+
|
|
74
|
+
## Stubs
|
|
75
|
+
|
|
76
|
+
None. I own the contracts. I did not touch `guide.ts` or `index.ts`: `designSystemTool()` is registered there as before.
|
|
77
|
+
|
|
78
|
+
## What I checked
|
|
79
|
+
|
|
80
|
+
- Tests: `design-color`, `design-tokens`, `design-tokens-write`, `design-system-tool`, `design-system-attach`, `design-scan-infer` (new), and the 0.26 `design-scan`, `design-system`, `design-system-safety` (kept; `design-scan` updated for the new scan). `npm run format`, `check`, `lint`, and the whole `npm test` are green (one browser test, `design-bridge-ui` "a deck shows one slide at a time", timed out once under load and passes alone).
|
|
81
|
+
- Colors against Chromium: 148 named colors, hex/rgb/hsl/hwb/lab/lch/oklab/oklch/`color()` conversions, and `color-mix()` results, read back from a canvas.
|
|
82
|
+
- The compiled CSS in Chromium: variables resolve, a nested `data-theme` scope recomputes the aliases, `color-scheme` follows, the `font` shorthand with `var()` is valid.
|
|
83
|
+
- The scan on four fixtures of my own (plain CSS with `.dark`, Tailwind v4, SCSS plus a TypeScript theme, a messy page with near-duplicate colors), on Pi Pocket's `web/` (dark first, `color-mix()`, `--err`/`--ok`/`--warn`: 9 of 9 roles) and on `site/`.
|
|
84
|
+
- A throwaway copy of the app (`node test/serve.ts 8911 127.0.0.11`) boots, and the `artifacts` module loads with its tools.
|
|
85
|
+
|
|
86
|
+
## What is weak
|
|
87
|
+
|
|
88
|
+
- The Tailwind output was never run through Tailwind (it is not installed here). It follows the v4 docs: `@theme static`, the namespaces, `--text-*--line-height`, `@custom-variant`.
|
|
89
|
+
- The scan's role rules are tuned on my fixtures and on two real folders. The bench (stream B) is the real test. Weakest spots: a project whose only surface is called `surface` (the scan makes it the page too), names it has never met, a dark mode written as separate `--dark-*` variables, a light override in a dark-first project that sets only some roles.
|
|
90
|
+
- Dark-mode uses of literal colors (not variables) are read only for dark-first-less projects (`.dark body { … }`, the media query). For a dark-first project, light uses are not.
|
|
91
|
+
- `color-mix()` in `lch`, `hsl`, and `hwb` is done as Oklch; the Oklab and sRGB cases match the browser.
|
|
92
|
+
- A multi-file write is atomic for each file, not as a set. A crash between two renames leaves new sources and an older `dist/`. A load compiles from the sources and never reads `dist/`, so nothing in Pi Pocket sees the mix; the next write fixes it.
|
|
93
|
+
- No `$extends`, no group aliases, no `string` token type, no `z-index` scale inferred by the scan (a `number` token holds one).
|
|
94
|
+
- `systemSummary` is a plain bounded list. It has no ranking by use yet.
|
|
95
|
+
|
|
96
|
+
## For the integrator and the other streams
|
|
97
|
+
|
|
98
|
+
- **G** (`guide.ts`): use `loadDesignSystem(cwd)`; when it returns a system, put `systemSummary(system, <budget>)` in the section (it is already defanged; fence it anyway), else keep the 0.26 text. The tool's `read` already fences its output as `<design_system_data>`.
|
|
99
|
+
- **U**: a token edit is `writeDesignSystem(cwd, { set: [{ mode, token, value }] })`. It throws `DesignSystemError` (message ready for a toast; `.problems` has `{ level, file?, token?, message }`) and writes nothing on an error. The result is the new `DesignSystem`. A swatch can use `ModeValue.hex` or `.literal`; the contrast badge is `ModeValue.contrast`.
|
|
100
|
+
- **V**: `color.ts` has the sRGB conversion and the WCAG ratio for "nearest token" suggestions. `system.tokens[i].modes[mode].hex` and `.literal` give the values to compare with.
|
|
101
|
+
- **B**: the scan result for a fixture is `scanTokens(root).inferred.roles` (role → `{ token, value, dark?, basis, source }`; `dark` is the other mode's value), `.draft.tokens` and `.draft.modes`, `.inferred.typeScale/spacing/radii/...`. Load a draft with `buildSystem` from `tokens-model.ts`, or save it with `writeDesignSystem`.
|
|
102
|
+
- `docs/features.md` (the Design bullet): `design_system` now reads, scans, and changes a structured system in `.pi/design/` (tokens in DTCG, modes, component specimens, guidelines, compiled to CSS variables, a Tailwind v4 theme, and JSON), and the artifact tools attach `ds/tokens.css`, `ds/tailwind.css`, and `ds/components.css` to a page that links them. The 0.26 single file still works while there is no folder.
|
|
103
|
+
|
|
104
|
+
## Group names of the scales, and the flagship check (added after the first report)
|
|
105
|
+
|
|
106
|
+
The scan writes these groups. The flagship uses the same ones or a close name, and `scaleOf(token)` (exported from `tokens.ts`, from `tokens-compile.ts`) is the one rule for a dimension token: `font.size.*` or `text.*` is the type scale, `space.*`, `spacing.*`, or `gap.*` is spacing, `radius.*`, `radii.*`, or `rounded.*` is corners, `breakpoint.*` or `screen.*` is breakpoints, and `container.*`, `tracking.*`, `blur.*`. `size.*`, `dim.*`, and `border.width.*` are dimensions that belong to no scale.
|
|
107
|
+
|
|
108
|
+
| Group | Type | The scan writes | The flagship uses |
|
|
109
|
+
| --------------------- | --------------------- | ------------------------------------------------------ | ------------------------------------------------- |
|
|
110
|
+
| `color` | color | `color.<hue>.<step>`, `color.bg.page`, `color.text.*`… | `color.*` |
|
|
111
|
+
| `text` | dimension | `text.sm`, `text.base`, `text.lg`… (font sizes) | `font.size.2xs` … `font.size.3xl` (also accepted) |
|
|
112
|
+
| `font` | fontFamily | `font.sans`, `font.mono`, `font.body`, `font.heading` | `font.family.sans`, `font.family.mono` |
|
|
113
|
+
| `weight` | fontWeight | `weight.regular`, `weight.bold` | `font.weight.regular` … (also accepted) |
|
|
114
|
+
| `leading`, `tracking` | number, dimension | `leading.normal`, `tracking.tight` | in `font.*` and `type.*` |
|
|
115
|
+
| `space` | dimension | `space.4` (16 px; step n is n × 4 px) | `space.*` |
|
|
116
|
+
| `radius` | dimension | `radius.sm`, `radius.md`, `radius.lg`, `radius.full` | `radius.card`, `radius.control`… (named by use) |
|
|
117
|
+
| `shadow` | shadow | `shadow.sm`, `shadow.md`, `shadow.lg` | `shadow.*` |
|
|
118
|
+
| `duration`, `ease` | duration, cubicBezier | `duration.fast`, `ease.standard` | `duration.*`, `easing.*` (both map to `--ease-*`) |
|
|
119
|
+
| `breakpoint` | dimension | `breakpoint.sm`, `breakpoint.md` | `breakpoint.*` |
|
|
120
|
+
| `type` | typography | none | `type.body`, `type.heading`… (composites) |
|
|
121
|
+
|
|
122
|
+
The flagship in `pi-pocket-ds-g` (380 tokens, modes `light`, `dark`, `high-contrast`, 10 components) loads with **no problem at all**, error or warning. Its default mode comes from `$extensions["com.pi-pocket"].mode`, `$type` and the tier come from the groups, and every composite (shadow, typography, border, transition, gradient) comes back resolved in every mode, with no reference left (a test checks this, including a string-form shadow and a `calc()` with a reference). Two changes came out of that run: a variable that a specimen sets in its own CSS (`--notice-bg: …`) is no longer reported as a missing token, and a string-form value now holds its references resolved.
|
|
123
|
+
|
|
124
|
+
`color.ts` exports `luminance`, `contrastRatio`, `over`, `parseColor`, `toHex`, `toOklab`, `fromOklab`, `toOklch`, `toOklchCss`, and `mixColors`.
|
|
125
|
+
|
|
126
|
+
## The bench (stream B): scan and format
|
|
127
|
+
|
|
128
|
+
I ran the bench on this branch (a copy of its folder in the worktree, not committed): `scan` **0.996**, `format` **1.0** (all seven systems: load, no error, round trip, idempotent, compiled, `dist/`, and every variable correct in Chromium in every mode, with the dark values by the media query alone). The other phases need `lint.ts`, `docsite.ts`, and the flagship, which are in other branches.
|
|
129
|
+
|
|
130
|
+
- **The exported scan function** is `scanDesignSystem(folder)` in `scan.ts`. It returns `{ tokens, modes }`: `tokens` is the `tokens.json` object and `modes` has one object for each mode file, by mode name. `scanTokens(folder)` returns the same draft in `.draft`, with the report data (`inferred`).
|
|
131
|
+
- **Role token paths**: `color.bg.page`, `color.bg.surface`, `color.text.primary`, `color.text.muted`, `color.border.default`, `color.accent.default`, `color.danger.default`, `color.warning.default`, `color.success.default`. The bench reads a role from the words of a path, so these are read as bg, surface, text, muted, border, accent, danger, warning, success (checked: all nine are right on three of four fixtures and eight of nine on the last). `color.text.on-accent` is text on a color, not a role. A color that is named for a role but is not the role itself is put one level down (`color.accent.hover`, `color.primary.dark`, `color.brand.default`), so it never takes the role's place when the bench picks the token nearest the plain name.
|
|
132
|
+
- **`tokens.css`** puts `:root` first (the default mode's block is `:root,` then `[data-theme="<default>"]`), then one `[data-theme="<mode>"]` block for each other mode, then `@media (prefers-color-scheme: dark)` (or `light`, for a dark-first system).
|
|
133
|
+
- **A second write with the same input changes no byte** in any file: a file with the same bytes is not written again (a test checks the modification times).
|
|
134
|
+
|
|
135
|
+
What the bench changed in the scan: the other mode's colors are written as they are in the mode file (not as new palette colors of the default mode); the draft keeps a color that the project uses once (as a literal in a rule); near-duplicate sizes, spacings (a pixel apart), radii, shadows, and breakpoints merge; a percent radius is a circle and not a size; the project's own pill value (`999px`) is kept; SCSS arithmetic (`$space-1 * 3`) is computed; a TypeScript theme object named for dark (`darkTheme`) is the dark mode; a list of numbers in a theme (`space: [0, 4, 8]`) is counted like a scale; Tailwind's arbitrary colors (`bg-[#fff4d6]`) count; the surface is the background of cards and panels; the text on the accent is a color the project already has.
|
|
136
|
+
|
|
137
|
+
Known misses (on the bench): the dark value of a role that the project sets only by use in a dark media query is named even when its hue differs from the light one (`messy` darkRoles precision 0.75); the link color of a dark mode has no token of its own.
|
|
138
|
+
|
|
139
|
+
## Round 2: the scan, held-out projects, and Tailwind compiled for real
|
|
140
|
+
|
|
141
|
+
**Numbers** (merged tree, `feat/design-system` at `f80d0a9`, bench copy in `test/design-system-bench/`, not edited): `scan` **1.0** (all four fixtures, every category), `format` **0.99** (1.0 on the seven other systems; the flagship loses 0.084 of its own score, see below). The reading of 0.869 that the integrator gave was taken before my commit `a6c9ed2` or on an older bench: on every tree that holds that commit, `scan` was 0.993 to 0.996 before this round's last commit, and colors precision was 1.0 on all four fixtures. The same checks on **seven projects I wrote myself** (the bench fixtures do not contain them, and no code names them): a shadcn/Next theme, a Material UI theme, a Bootstrap theme, a Vue base stylesheet, a brochure page with no variables, a Tailwind 3 project with a config and class names only, and native CSS with nesting. Their scan scores went from 0.714 and 0.928 (the two sets, before the round's changes) to 0.995 and 1.0. I wrote them so that I could not tune the scan to the four fixtures alone; the left-over 0.005 is my own Bootstrap expectation (a dark accent for the link color, see below).
|
|
142
|
+
|
|
143
|
+
What I changed, each as a general cause (no fixture name appears in the code):
|
|
144
|
+
|
|
145
|
+
- **A library prefix is not part of a name.** `--bs-body-bg`, `--ifm-*`, `--sl-*`, `--mui-*`, `--ant-*`, `--chakra-*`, `--mantine-*`, `--pico-*`, `--vt-*` read as `body-bg` and so on.
|
|
146
|
+
- **How a variable is used outranks its name.** A variable that is used as a background is not the text, and the reverse (`--text-light` used as a band color). The kinds of use are counted for each variable.
|
|
147
|
+
- **`secondary`/`tertiary` mean muted only after a word for text** (`text-secondary`); a `secondary` alone is a brand color. `paper`, `soft`, `mute` are surface words.
|
|
148
|
+
- **A surface that is the page's own color is not the surface** (`--surface-1` is the page, `--surface-2` the card). With no named background, the page is the most used root neutral.
|
|
149
|
+
- **`calc(var(--x) * 2)`, `rem`/`em`/`px` mixed, and `calc(var(--r) - 4px)`** are computed and counted as uses of the size they come to. They are deferred until all variables are known.
|
|
150
|
+
- **Scales merge what the project names and what it uses** (named `text.sm` plus a used 16px, in one scale). A bare `--radius` takes its name after the named ones, so `--radius-md` is never lost.
|
|
151
|
+
- **Theme libraries:** a Material UI `typography`, a scalar `spacing: 8` and `borderRadius: 4` (steps of a unit), and `shadows: [...]` (one token for each layer set, `none` skipped); `sx={{ p: 2 }}` numbers are steps of the theme, not pixels.
|
|
152
|
+
- **Tailwind's default colors by class** (`bg-slate-200`, `text-white`): the class is a use of the color. The palettes of Tailwind 3 (hex) and 4 (Oklch) are in `scan-tailwind.ts` (copied from the packages `tailwindcss` 3.4 `colors.js` and 4 `theme.css`, MIT; a new generator was not needed because the data does not change often). A name the project defines itself is its own, not the default.
|
|
153
|
+
- **Colors a hair apart are one color** (about two levels of a channel; the same gray a shade apart up to three levels). Pure white and pure black are decisions: only one level apart is the same.
|
|
154
|
+
- **Dark mode:** a dark value that already exists in the light palette is not used as a stand-in if that color is itself different in the dark (a light `ink-1` that has a dark `ink-1`). A role that use decided and a variable that holds it with a dark value gives the dark role.
|
|
155
|
+
- **A status color that is a shade of the accent** is decided by hue too (under 8°), so a red is not dropped next to an orange accent. **A chromatic dark color that is no role's** is the dark value of the light color of its hue (within 25°).
|
|
156
|
+
|
|
157
|
+
**Tailwind v4 compiled for real.** I installed `tailwindcss` and `@tailwindcss/cli` 4.3.3 in `/tmp/tw`, outside the repo (nothing was added to `package.json`), and compiled `@import "tailwindcss"; @import "./tailwind.css";` against a page that uses our names. The flagship's `tailwind.css` compiles with no warning, and the `--color-*`, `--spacing-*`, `--radius-*`, `--font-*`, `--text-*`, `--shadow-*`, and `--ease-*` namespaces all produce utilities: `bg-bg-page`, `text-text-primary`, `rounded-card`, `text-body`, `shadow-md`, `ease-out`, and `dark:` through `@custom-variant`. A `tailwind.css` from a scan draft compiles too. One thing is by design: a token named `ease.out` makes `ease-out`, so a project token `ease.standard` makes `ease-standard`, and nothing else.
|
|
158
|
+
|
|
159
|
+
**Weak spots left.**
|
|
160
|
+
|
|
161
|
+
- `messy` `darkRoles` was 0.75: the page's dark query turns the links light blue and leaves the buttons brown, and the scan named the link blue as the accent's dark value. Now a role keeps its hue across modes (a dark value 40° or more away in hue is not the role's), and that dark color goes on the light color of its hue (the link blue's token), so `darkColors` stays complete.
|
|
162
|
+
- In my Bootstrap project the scan gives a dark accent (`--bs-link-color` shifts to `#6ea8fe`) where my own expectation said none. Bootstrap's buttons stay the same, its links change. I kept it as the scan gives it.
|
|
163
|
+
- `format` on the flagship: **the bench probe reads `--space-0` as `0.4px` after a number token** in Chromium (the value of `font.tracking.wide`, probed a few tokens earlier; in the browser by hand, and with the same probe code on a short list, the compiled CSS gives `0px`). The compiled `tokens.css` is right: `--space-0: 0px`. This costs 0.084 on the flagship (4 of 1244 comparisons, and the media-dark check). It is a quirk of the probe order, not of the engine. I did not change the compile for it.
|
|
164
|
+
- Tests that fail on the merged tree without my scan changes were `design-system-routes` (5) and `design-system-ui` (1); after the second merge of `feat/design-system` (round 3) they pass. One deck test (`a deck shows one slide at a time`) timed out under load in one run and passes alone.
|
|
165
|
+
|
|
166
|
+
### `systemSummary`: the roles and the components survive a cut (asked by stream G)
|
|
167
|
+
|
|
168
|
+
The order is now: how to link it; the **semantic tokens** (colors first, then the other types); the **components**; the **scales** (raw sizes, fonts, motion); the **guidelines**; the **palette** (collapsed); and last the **component tokens** (set by one component). When the summary is cut (12,000 bytes in the guide), the cut falls at the end of that list, so the flagship's 52 semantic colors and all 10 components stay (before, the components, the guidelines and part of the tokens were lost at 12,000).
|
|
169
|
+
|
|
170
|
+
- **Use ranks a token inside its group.** A token's use is the number of components whose `tokens` list it, plus the number of tokens that are an alias of it. Ties keep the declared order. A system with no components keeps the declared order everywhere.
|
|
171
|
+
- **Descriptions go from the last token first.** When the whole summary does not fit, the descriptions (`// …`) stay on the tokens that come first (the most used), and are dropped from the others, until the header, the roles, and the components take four fifths of the space. The scales and the guidelines get the rest.
|
|
172
|
+
- **A system that has only raw colors** lists them as the roles (as before) and has no palette line.
|
|
173
|
+
- `test/design-tokens-summary.test.ts` has the tests (a cut at 3,600, 4,500 and 6,000 bytes holds every semantic color role and every component; the order; the ranking; the descriptions). I changed one line of stream G's `test/design-guide.test.ts`: its hostile description is now on `color.text.primary` (the most used token) and not on `color.bg.base` (used by nothing), since the unused token's description is dropped at 12,000.
|
|
174
|
+
|
|
175
|
+
## Round 2b: the integrator's held-out result (scan 0.544), and 15 more projects I did not write
|
|
176
|
+
|
|
177
|
+
The integrator's held-out projects scored 0.544 on the round 1 scan. I cannot see them, so I had other agents write projects for me, blind to the scanner (they did not read `src/`): 27 small projects in 9 batches, each with an `expected.json` in the bench's format, in the styles the integrator listed and in others (WordPress block theme, Angular Material, Bootstrap, Chakra, Mantine, Stitches, Vuetify, Docusaurus, Material 3, Svelte, daisyUI, Tailwind 3 and 4, Open Props, PostCSS, Less, Sass, styled-components, utility CSS). On those 27 projects the scan before this work (commit `9db9fc6`) scores **0.738**, and now **0.978** (colors P0.99/R0.97, roles P0.99/R0.98, dark colors R0.97, dark roles R0.95, shadows R0.99, spacing P0.96/R0.99, type R0.93). The first run of each batch was 0.5 to 0.9, and some projects scored 0. I fixed what each batch showed and then ran the next batch, so the last batches (g, h, i) are the best test of the earlier fixes: they scored 0.84 (g, i) on the first run, and 0.96 after their own fixes. The expectations of those agents are not always right (see the end), so I did not tune to the last percent. All the rules are general; none names a project.
|
|
178
|
+
|
|
179
|
+
Causes and fixes (1 to 4 are the integrator's list):
|
|
180
|
+
|
|
181
|
+
1. **Theme objects.** A theme object's scope comes from the nearest object around the key that has a mode word in its name (`darkTheme`, `light: {…}`, `themeDark`). A file that exports `darkTheme` first and `lightTheme` second has both modes, and light is the default. A dark-first object with a nested `light` block (or `colors: { light: {…}, dark: {…} }`) is dark first: the other mode is `light`, and the colors that change are literals in the default mode, so the palette has no dark-only grays. A mode block whose keys are colors needs no `colors` key around it. `const brand = {…}` above `colors: { brand }` is read (shorthand).
|
|
182
|
+
2. **Dark mode in other forms.** `--dark-bg`/`--bg-dark`/`$night-ink` are the other mode's values of the plain variable (sure when the plain one points at them in the dark scope; otherwise three pairs make a scheme, and `primary-dark` beside `primary-light` is a shade). A Sass role variable with a mode word and no dark scope anywhere (`$dark-background`, `$dark-text`) is that mode's role. A Sass map of modes `$themes: (light: (…), dark: (…))` and a map of names that hold modes. A file named for a mode (`dark.less`, `themes/night/colors.css`). `:root.dark`, `.theme-dark`, `[data-mode=dark]`, `[data-mantine-color-scheme=dark]`, `.v-theme--dark`, `.is-dark`, and the like. `@custom-media --dark (prefers-color-scheme: dark)`. `:global(.dark)` and `:global(:root)` (Svelte, CSS Modules). A custom property that is set only for the dark mode takes the Sass variable of the same name (`--bs-body-bg` and `$body-bg`) as its light value. A class that has a color in each mode (`.text-gray-900` and `.dark .text-gray-900`) pairs the two colors.
|
|
183
|
+
3. **Roles from use and from other names.** `subtle`, `faint`, `dim` alone are the quiet text; `ink-2`, `text-3` are not the text; `component-background` is the surface; `canvas`, `paper`, `ink`, `fg`, `outline`, `divider`, `critical`, `caution`, `positive` were already words. The quiet text is a gray that is clearly softer than the text, not a light link color. A hue beats a name: a color called `warn` that is red is the error color; a red, orange, or green used once is not the brand when all of the statuses are used once. `primary` still beats `accent-1` (a numbered one is one of a set). Classes on `<body>`/`<html>` and page wrappers (`.page`, `.wrapper`, `.layout`) style the whole page. A rule with one class counts by how often markup uses the class. A label color that a mode uses only as text (a dark label on a light button) is a color for the text on the accent. A card's own variable (`.card { --card-bg: #fff }`) is the surface.
|
|
184
|
+
4. **Scales in other places.** WordPress `theme.json` and `styles/*.json` (palette, font sizes, spacing sizes, shadows, `settings.custom`, and `styles` read as rules). Chakra `semanticTokens`. Sass maps (long ones, with multi-layer shadow values, and `map-merge(…, (…))`). Sass arithmetic and color functions in rules and in variables: `$unit * 2`, `rgba($black, .2)`, `darken`, `tint-color`, and `$black`/`$white` as defaults. CSS-in-JS in `.js`/`.ts` component files (styled-components, Emotion, `sx`, `makeStyles`). Fluid sizes `clamp(1rem, …, 1.5rem)` are steps at their smallest value. A numbered length family (`--size-1` to `--size-8`) is spacing when its properties are padding, margin, or gap.
|
|
185
|
+
|
|
186
|
+
Tests: `test/design-scan-infer.test.ts` has a test for each of these (20 new tests, each with its own small project).
|
|
187
|
+
|
|
188
|
+
What I believe is wrong in the agents' expectations (left as they are): Tailwind 3 `e1` lists spacing 8 and 12 and a 6px radius that no file uses; Bootstrap `f1` expects `shift-color(#6f42c1, -12%)` to be darker (Bootstrap's own `shift-color` tints a negative weight); `a2` and `d3` list no one-off values (a lone `padding-right: 20px`, a lone `font-size: 15px`), where the scan keeps them.
|
|
189
|
+
|
|
190
|
+
## Round 3: the integrator's items (code handoff, token model, agent experience)
|
|
191
|
+
|
|
192
|
+
Done on the merged tree (with `feat/design-system` merged again). Numbers on Pi Pocket's own system (348 tokens, 3 modes): `tailwind.css` 65.5 KB to 46 KB (381 variables, none declared twice, none pointing at itself or at a missing one); `tokens.resolved.json` 274 KB to 62 KB; the bench `format` phase is 1.0 on all eight systems (the flagship was 0.99).
|
|
193
|
+
|
|
194
|
+
**Code handoff**
|
|
195
|
+
|
|
196
|
+
1. **`tokens.css` holds the value of a primitive.** A primitive, or a step of a scale (`space.4`, `neutral.500`), that is a reference to another primitive (`{dim.16}`) is written as the value (`--space-4: 16px`), so DevTools shows `16px`. A role, or a component token, keeps `var()`: the reference is what a person wrote and what a mode changes. (The system in the tree has no `dim` group now, so its `tokens.css` already held values; a test has a `dim` group and checks the rule.)
|
|
197
|
+
2. **`tailwind.css` has one variable for each token.** In the Tailwind v4 namespace when one fits and no earlier token has it (`--spacing-4`, `--text-sm`, `--color-bg-surface`), else under the token's own name (`--button-padding-x`). A token whose own name is the Tailwind name keeps it. A reference follows the rename (`--color-card-border: var(--color-border-default)`). A type style is Tailwind's `--text-*`: `--text-label: var(--text-sm)` with `--text-label--line-height`, `--font-weight`, and `--letter-spacing`; it has no `--type-*` shorthand in this file. `tokens.css` keeps the tokens under their own names (`--space-4`), so a Tailwind project links both when it wants `var(--space-4)` or the components. One source of truth for `--text-*` against `--font-size-*`: the first token in file order that maps to a Tailwind name has it, a later one keeps its own name.
|
|
198
|
+
3. **`"tailwindReset": ["color"]`** in the root `$extensions["com.pi-pocket"]` of `tokens.json` (opt in; `true` is color) puts `--color-*: initial;` in `@theme`, so Tailwind's palette does not make `bg-red-500`. I compiled it with Tailwind 4.3.3 (in `/tmp/tw`, not in the repo): with the reset, `bg-red-500` makes no class; without it, it does.
|
|
199
|
+
4. **The `dark:` variant** follows `[data-theme="dark"]` when a `data-theme` is set, and the system's dark setting when none is: `@custom-variant dark { &:where([data-theme="dark"], …) { @slot; } @media (prefers-color-scheme: dark) { &:where(:not([data-theme]):not([data-theme] *)) { @slot; } } }`. Tailwind 4.3.3 makes both rules for `dark:bg-bg-surface`.
|
|
200
|
+
5. **`tokens.resolved.json` is compact**: one line for each token (`type`, `tier`, `cssVar`, `value` as CSS, or `values` by mode when they differ, `alias`, `contrast`, and a type style's `parts`). **`tokens.<mode>.resolved.json`** is new: a DTCG file for each mode (groups nest, `$type` and one `$value` for each token, references followed, `$description`, `$deprecated`). `CompiledFiles.modes` holds them; `writeDesignSystem` writes `dist/tokens.<mode>.resolved.json` and removes the file of a mode that is gone; `read file=dist/tokens.<mode>.resolved.json` shows it; the zip of the System view has them (a three-line change in U's `system-routes.ts`, which also sends `notes` and `overrides` with the system).
|
|
201
|
+
|
|
202
|
+
**Token model**
|
|
203
|
+
|
|
204
|
+
6. **A name that is its own value warns** (`space.16` = 16px, `radius.7` = 7px, `duration.140` = 140ms; also in rem and seconds): one warning for a group, with `fix`: rename to a role (`space.card`) or to a step of a scale (`space.4`). Zero, colors, and weights are not the case.
|
|
205
|
+
7. **`contrast: { on, min, exempt: "disabled" | "decorative" }`.** A failing exempt pair is not a warning: it is a note, `DesignSystem.notes` (`level: "info"`), which `validate` lists as "Notes (no action needed)". Notes are not in `problems`, so nothing that counts problems (the System view, the docs page, the summary) counts them and no stream's code had to change. A failing pair that is not exempt has a `fix` that names `exempt`. Another value of `exempt` is an error. `ResolvedToken.contrasts` has every pair (`contrast` is the first); a mode's `contrast` has `exempt`.
|
|
206
|
+
8. **For stream U:** `ModeValue.parts` for a shadow (`offset-x`, `offset-y`, `blur`, `spread`, `color` as CSS with `var(--…)`; `layer-2-blur` and so on for several layers; `inset`), not repeated in the stylesheet; `DesignSystem.overrides` (the tokens each mode's file sets, so the view can show "inherited" and use `remove`); `ResolvedToken.contrasts`.
|
|
207
|
+
|
|
208
|
+
**Agent experience**
|
|
209
|
+
|
|
210
|
+
9. **A parameter must fit its action**: `fromScan` with `set` is refused with "fromScan is a parameter of init, not of set. set takes: changes, remove." (the table is `PARAMETER_ACTIONS` in `system.ts`); an unknown action lists the actions; `path` with `init` needs `fromScan`.
|
|
211
|
+
10. **The 0.26 `write`** still works and is not in the description or in a field's text (the schema still has the literal, since the harness checks a call against it; a tool description cannot change with the folder).
|
|
212
|
+
11. **The scan** marks each role with a confidence (`high`: a name that says the role; `medium`: a name that is a hint, or the page and text by use; `low`: a guess from use, such as the most used chromatic color or a status color by hue) and where it comes from (`file:line` of the variable, or of the first use of the color; comments keep their line breaks now, so a line is the file's line). The report ends, after the data fence, with the exact next call (`Next call: design_system {"action":"init","fromScan":true}`, with `path` when the scan was of a folder), the roles that are not `high` with their reasons, a `set` call to correct one, and the roles with no color. A project with nothing to scan gets a `tokens` example.
|
|
213
|
+
|
|
214
|
+
Tests: `test/design-tokens-checks.test.ts` (new, 10), `test/design-tokens-write.test.ts` (the Tailwind, the DTCG, the reset, and the literal tests), `test/design-scan-infer.test.ts` (confidence, `file:line`, the next call).
|
|
215
|
+
|
|
216
|
+
## Round 3b: the held-out check (0.544, then 0.795), and ten more projects I did not write
|
|
217
|
+
|
|
218
|
+
The integrator's second held-out run was 0.795, against 0.995 on the bench. The bench is not the target any more: I wrote nothing for it this time. Three agents wrote 10 more projects blind to the scanner (`j`: SCSS with the dark mode in unusual forms; `k`: scales only as literals, in React Native, Vue, Angular, and nested SCSS; `l`: dark-first pages with many one-offs and status colors with no role names). Before this work (`efb5cc0`) the scan scores **0.844** on them; now **0.975** (colors P0.98/R0.89, roles P0.99/R0.97, dark colors R1.0, dark roles R1.0, spacing P0.94/R0.98, shadows P0.93/R1.0). The bench went from 1.0 to 0.998, and the 27 earlier projects from 0.978 to 0.976: the cost of the rules below on projects that I fitted before.
|
|
219
|
+
|
|
220
|
+
The four causes the integrator listed, and the other causes the new projects showed:
|
|
221
|
+
|
|
222
|
+
1. **Scales that are not custom properties.** Indented Sass (`.sass`) and Stylus (`.styl`) are read (they were not read at all: no braces). Angular `styles: [\`…\`]`in a`.ts`file. React Native:`paddingHorizontal`/`marginVertical`, and a shadow made of `shadowColor`, `shadowOpacity`, `shadowRadius`, and `shadowOffset`becomes one`box-shadow`. A shadow is a shadow by its value (offsets, a blur, a color) whatever the variable is called (`--drop-1`). `@function space($n) { @return $n * 4px }`and`map-get($spacers, 3)` in a rule are resolved. A value used once that is off the grid or under 4px (6px, 10px, a hairline) is no spacing step.
|
|
223
|
+
2. **Dark mode in SCSS.** `@include dark-mode { … }`, `@include theme(dark)`, `@include respect(x)` where `respect` is a mixin that wraps `@media (prefers-color-scheme: dark)` or `.theme-dark &` around its `@content` (found in any file first, since the mixin is defined in one file and included in others); `if($theme == dark, #1a1c21, #fff)`; `@if $theme == dark`. A deferred value (`rgba($black, .2)`, `$unit * 2`) keeps the mode of the rule it came from (it used to land in the default mode). Sass interpolation of one variable (`#{$dark-bg}`) is the variable. `@media (prefers-color-scheme: light)` is the light scope.
|
|
224
|
+
3. **Dark-first pages.** The scan decides the project is dark first by how the page is painted when no variable is called the background (`--base` on `body`); a dark-first project keeps every color that changes as a literal, so no dark-only gray is a primitive in the other mode's view; its one-offs (gradient stops, chart colors, badges) are left out; a Sass variable that a custom property is set from (`--bg: #{$dark-bg}`) is not a second token. In any project, a one-off used once is kept only while the palette has room (14 colors) and is more than a step away from a color the design has.
|
|
225
|
+
4. **Status colors with no role words.** A color that a variable names (`--stop`, `--go`, `--wait`) is a candidate for danger, warning, or success by its hue even when no rule uses it; a named color beats a literal used once; a color named for the accent and a suffix (`--glow-deep` beside `--glow`) is a step of the accent, but a color with a name of its own (`--go`) is not, though it has the accent's hue. The accent by use prefers a color that a variable names to a gradient stop. Also words: `faded`, `rim`, `edge`.
|
|
226
|
+
|
|
227
|
+
What is weak: the budget of 14 colors and the "one step" distance (0.025 in Oklab) are judgements; the earlier projects lose a little recall on one-off colors when the palette is large. A scale written only in a Sass function whose body is not `$n * <length>` is not resolved. A mixin that wraps the dark mode and is defined outside the scanned folder is not known (its name must say dark).
|
|
228
|
+
|
|
229
|
+
## Round 3c: four classes of input (the integrator's read of the held-out failures)
|
|
230
|
+
|
|
231
|
+
Held-out 0.795, then 0.869 at `e5e92b1`. The four faults were classes, not details of one project; each has a test in several forms in `test/design-scan-infer.test.ts` ("Round 3c").
|
|
232
|
+
|
|
233
|
+
1. **Types by value.** A shadow is any value of layers that each have two to four lengths, at most one color (first or last, a hex, a function, `var()`, a name), and perhaps `inset` (`looksLikeShadow`): `--elev-1`, `--elevation-2`, `--depth-3`, `--lift-1`, `--z1`, `--raise`, `--soft`. A `8px 8px 8px 8px` (a padding) and `none` are not. Durations (`120ms`, `.4s`), easings (`cubic-bezier()`, the keywords), and font stacks were found by value already; a radius is found by the property that takes it (`border-radius: var(--r1)`), since a length alone says nothing.
|
|
234
|
+
2. **Status words.** Success: `good`, `ok`, `positive`, `pass`, `valid`, `done`; danger: `bad`, `error`, `critical`, `negative`, `invalid`, `fail`, `wrong`; warning: `warn`, `caution`, `attention`; `note` and `notice` (and `info`) are not the brand. A status named only in the other mode (`.dark { --success: #4ade80 }`) gives the hue of its pair: the used color of that hue is the status, before the accent is chosen, and the name's value is its dark. A variable with no default value in a project whose default mode sets others is that mode's value, not the default's.
|
|
235
|
+
3. **Twins.** `--light-*`/`--dark-*` (prefix or suffix), a role set from them in each mode (`--bg: var(--light-bg)`; `.dark { --bg: var(--dark-bg) }`), one twin beside a role variable, and Sass `$light-*`/`$dark-*` behind `#{…}`: none is a color group of its own (no `color.dark.*`, `color.dark-good`). A Sass variable that a custom property is set from in either mode is that property.
|
|
236
|
+
4. **Vendor attributes and classes.** `[data-bs-theme]`, `[data-color-mode]`, `[data-mantine-color-scheme]`, `[data-joy-color-scheme]`, `[data-theme*=dark]`, `[data-md-color-scheme=slate]`, `.dark-theme`, `.theme--dark`, `.v-theme--dark`, `.ThemeDark`, `.DarkMode`, `html.theme-dark`, a root-like element under the dark class (`[data-bs-theme=dark] body`). Interpolation inside a longer value or with arithmetic (`0 1px 2px #{$ink}`, `#{$space * 2}`) is resolved through the Sass variables. A second variable with no name of its own (`--gap` beside `$space`) keeps its own name instead of being dropped.
|
|
237
|
+
|
|
238
|
+
The earlier commits `eeaef36` to `13f6251` (round 3b) cover the SCSS dark mixins, the indented syntaxes, the dark-first pages, and the scales without tokens; `feat/design-system` had merged `ds/tokens` only up to `efb5cc0` when the 0.795 was measured.
|
|
239
|
+
|
|
240
|
+
Also in round 3c, after the integrator's synthetic example (a dark-first page whose `--dark-paper`, `--dark-ink`, `--dark-ok` feed `--paper`, `--ink`, `--ok`, with the light values in `:root[data-mode="light"]`): the example already gave the right roles at `995c1d8` (the measurement was of `ca7b5bb`, before the twin rules). One more form is covered: a source variable that is a role variable's name with only mode words added (`--d-paper`, `--ok-dk`, `--dark-ok`, `--ok-dark`) and that is used only by that variable is not a token of its own, whatever the words are. The test runs four twin forms against five status words (ok, good, positive, pass, valid) and four light switches (`:root[data-mode="light"]`, `.light`, `[data-theme="light"]`, `html.theme-light`), and checks that the success role has the name's value in both modes, with `basis: name`, and that no token exists for a twin.
|
|
241
|
+
|
|
242
|
+
## Round 4: handoff, one JSON convention, agent experience, engineering
|
|
243
|
+
|
|
244
|
+
1. **Tailwind names by kind.** `tailwind.css` had `--font-leading-*` and `--font-tracking-*`; in Tailwind v4 `--font-*` is the family namespace, so they made `font-leading-tight`. A leading is `--leading-*`, a tracking `--tracking-*`, a weight `--font-weight-*`, a text style `--text-*`, a breakpoint `--breakpoint-*`, and so on over the whole table (`color font text font-weight tracking leading breakpoint container spacing radius shadow inset-shadow drop-shadow blur perspective aspect ease`; `animate` is not made). A token whose own name starts with a namespace of another kind gets `--ds-` in front, and a later token with a taken name keeps its own name only if that is in its own namespace. `test/design-tailwind.test.ts` checks each variable against the kind of its token and keeps the utilities of the flagship in `test/fixtures/design-system/pocket-tailwind-utilities.txt`: 703 names, each made by a real Tailwind 4 compile (`@tailwindcss/cli` over a page of those classes; none was missing, and `font-leading-*`, `bg-bg-*`, `text-text-*` were not made). The check against the fixture is the test that stands in for a compile in CI.
|
|
245
|
+
2. **Utilities that read.** A color role drops the word that the utility repeats (`color.bg.surface` is `--color-surface`, so `bg-surface`; `color.text.primary` is `text-primary`; `color.border.default` is `border-default`), and a trailing `default` goes (`color.accent.default` is `--color-accent`). When two roles would take one name the first keeps it and the other keeps its full name. `tokens.css` is unchanged. The docs page's Tailwind copy button and its "Use it" snippet use the same map (`tailwindNames`).
|
|
246
|
+
- Weak spot: Tailwind makes `bg-*`, `text-*`, and `border-*` for every color, so `bg-primary` (a text color as a background) exists.
|
|
247
|
+
3. **One JSON convention.** The per-mode DTCG files are the main output. `tokens.resolved.json` stays (the bench reads it, and the zip and the tool's summary list it) but says in its `about` that it is a compact summary, is listed last, and is named so in the docs. New: `tokens.studio.json`, one file in Tokens Studio's single-file format (a set for each mode with every token, references kept where the mode has one, a `$themes` array that turns one set on, `$metadata.tokenSetOrder`). The "Use it" blocks say how to load it. The code moved to `tokens-dtcg.ts`.
|
|
248
|
+
- Weak spot: the Studio format is built from its documentation, not loaded into Tokens Studio.
|
|
249
|
+
4. **The flagship's `dist/` is committed**, and `test/design-dist.test.ts` compiles the sources and compares each file byte for byte (`PI_UPDATE_DIST=1` accepts a change). `.prettierignore` keeps `npm run format` off it (prettier had reformatted the JSON, and the test failed).
|
|
250
|
+
5. **DTCG 2025.10.** Input already took the object forms. `$extensions["com.pi-pocket"].format: "2025.10"` writes `{ colorSpace, components, alpha, hex }` and `{ value, unit }` (also inside shadows, type styles, borders, gradients, and transitions) in the per-mode files; the default is `"2021"`, the string forms of the 2021 to 2024 drafts, and the file's `$description` says which. A file has one form throughout, whatever form the tokens were written in. 2025.10 has only px and rem for a dimension, so another unit (`em`, `%`) stays as text. A color object of another space keeps its space and gets a `hex`. An unknown value is a warning.
|
|
251
|
+
6. **The tool and the summary.** The description has one example call for each action, one line each (a test runs each and checks that none is refused for a parameter of another action). The top-level schema is still one object. The summary lists each component with its slug, its root element with its classes, and the other classes of its states (`pk-card__title is-hover`); names are project text, so only safe class names are shown.
|
|
252
|
+
7. **Engineering.** `scan-infer.ts` was 2,512 lines and `scan-facts.ts` 2,214; now 298 and 259. The inference has `scan-variables` (the winning declarations, twins, `var()` and Sass resolution), `scan-categorize`, `scan-tree`, `scan-sass-colors`, `scan-prepare`, `scan-roles` (the roles of each mode), `scan-palette` (palette and role tokens), and `scan-util`. The facts have `scan-facts-use` (declarations), `-theme` (JS theme objects), `-lists` (theme lists, modes, semantic tokens), `-wordpress`, `-sass`, and `-files`. No module imports in a cycle. Behavior is unchanged: the five fixture sets score as before (0.998, 0.991, 0.994, 0.976, 0.975) and the tests ran unchanged.
|
|
253
|
+
- Weak spot: `infer` is still a function of about 200 lines; `paletteTokens` is one function of about 400 lines whose phases share their locals.
|
|
254
|
+
|
|
255
|
+
## Round 4b: Tokens Studio and WordPress in the scan (a second held-out set, 0.818)
|
|
256
|
+
|
|
257
|
+
Two whole input formats were weak. Neither is tuned to a number: the fixtures are mine (`/tmp` sets plus `test/design-scan-studio.test.ts` and `test/design-scan-wordpress.test.ts`), and the round trip is a test.
|
|
258
|
+
|
|
259
|
+
**Tokens Studio** (`scan-import-studio.ts`, `scan-import-convert.ts`, `scan-import.ts`).
|
|
260
|
+
|
|
261
|
+
- A file is Tokens Studio when it has `$themes` or `$metadata` (or two or more top-level objects, one of them named for light or dark). Sets are its top-level keys; a folder with `$themes.json` or `$metadata.json` has a file for each set (`brand/acme.json` is the set `brand/acme`), and the walk now reads every `.json` beside those two files.
|
|
262
|
+
- Token files are collected first and sorted by `finishImports` once every file is in, because a folder's sets arrive in file order.
|
|
263
|
+
- Modes: the sets that a theme turns on (`enabled` or `source`), in `tokenSetOrder`, a later set over an earlier one. A theme named for dark, or one that turns on a dark set, is the dark mode; a theme with a mode word is preferred as the default. Themes in groups apply together (a Mode group and a Brand group: the first brand theme is in every mode). Other themes of the mode group (`High contrast`) are modes of their own. Without themes, the sets named for dark are the dark mode. A set's name is not part of a token's path (a file with no `$themes` and no `$metadata` keeps the old one-set reading, so its group names stay).
|
|
264
|
+
- Values: `value`/`type` and `$value`/`$type`, group types, references `{a.b}` and the oldest `$a.b`, followed across sets; math (`{a} * 2`, `{a}*4`, `{a} + {b}`, `round()`, `min`, `max`, `calc()`, with units: `16px * 2` is `32px`); `rgba({color}, 0.5)`; `modify` (`alpha`, `lighten`, `darken`, `mix`, in sRGB). A value that is only a reference stays a reference, so the aliases survive. Font weights by name (`Semi Bold` is 600), line heights and letter spacings in percent, type styles with their members followed, borders, and shadows (Tokens Studio's `x`, `y`) are put in the forms the engine reads. `text`, `asset`, `composition`, and similar types are left out. A loop or a missing target drops that token only.
|
|
265
|
+
- A Tokens Studio file counts as a token source whatever its size (the other token files need 8 tokens), and a token file may be 1.5 MB (a system of thousands of tokens is more than 200 KB).
|
|
266
|
+
- The dark file holds the tokens whose value differs from the default's; a token that only the dark mode has is left out, and the report says how many.
|
|
267
|
+
- Round trip: the file that Pi Pocket exports (`tokens.studio.json`) scans back to the same tokens in every mode (the flagship: 348 tokens, 3 modes, no difference).
|
|
268
|
+
- Weak spots: `lighten` and `darken` in Tokens Studio's `lch` or `hsl` space are done in sRGB (a different color); a theme that turns on sets of two brands at once uses both in order; names with spaces become hyphens.
|
|
269
|
+
|
|
270
|
+
**WordPress** (`scan-facts-wordpress.ts`).
|
|
271
|
+
|
|
272
|
+
- Style variations (`styles/*.json`, or a file with a `title`): dark when its title or file name says so, or when its base color is dark; any other look (`ocean`) is left out, where before it replaced the default. A dark-first theme with a light variation has light as its other mode.
|
|
273
|
+
- `spacingScale` (`operator`, `increment`, `steps`, `mediumStep`, `unit`) makes the sizes as WordPress does (slug 50 in the middle, 10 apart). `settings.color.gradients` and gradient variables in stylesheets are gradient tokens (the value is checked for safe characters). Families with only `fontFace` take the name there; a size with only `fluid.max` says it there; `border.radiusSizes`; `settings.custom` values are read by the first word of their path or by their syntax, and may refer to each other (`var(--wp--custom--font-size--base)`).
|
|
274
|
+
- WordPress's own names: `base` is the page and `contrast` is the text (only in a WordPress theme).
|
|
275
|
+
- A stylesheet read before `theme.json` has its `--wp--preset--*` names read too.
|
|
276
|
+
- Weak spots: a fluid size is its `size` (the largest), and the minimum is not a step of the scale; `spacingScale` rounds each size to two decimals (as I remember WordPress does; I could not check its source offline); a clamp() size is its smallest value, as everywhere in the scan.
|
|
277
|
+
|
|
278
|
+
## Round 5: ramps, names, the review list, typed values, one more split
|
|
279
|
+
|
|
280
|
+
1. **Numbered ramps** (`tokens-ramps.ts`). A color group whose children are numbers (`color.blue.100` to `900`) must go steadily lighter or darker: the validator compares Oklch lightness of the solid steps in every mode and warns with the two steps named (`step 200 (84%) is lighter than step 100 (79%), but the ramp gets darker as its numbers rise`) and a fix. A step may be as light as the one before within 0.4 points; a ramp whose ends differ by less than 5 points has no direction; groups of fewer than three steps, translucent steps, and names that are not numbers are left alone. It finds the flagship's ramps (100 and 200 are out of order in the seven hues), which stream G fixes; until then two flagship tests fail on the warning.
|
|
281
|
+
2. **Names** (`tokens-tailwind.ts`, `tokens-names.ts`). `dist/names.md` is generated: how each name comes out (the rules), then a table for each top group: token, `tokens.css` variable, `tailwind.css` variable, utilities. A role whose last segment says nothing alone (`default`, `primary`, `secondary`, `tertiary`, `base`, `main`, `normal`, `regular`, `standard`) takes the word of its group: `color.border.default` is `--color-border`, `color.text.primary` is `--color-text`, `color.bg.base` is `--color-bg`; a specific word still drops the group's (`color.bg.surface` is `--color-surface`, `color.text.muted` is `--color-muted`); a trailing `default` of another group goes (`color.accent.default` is `--color-accent`); the second of one name keeps its full name (`--color-text-secondary`). `bg-bg`, `text-text`, and `border-border` do stutter; they say what they are and `--color-primary` no longer reads as the brand. All 703 utilities of the flagship were made by a real Tailwind 4 compile again (fixture updated). The table has no values, so a change of a value leaves `names.md` as it is. The Tailwind names moved out of `tokens-compile.ts`.
|
|
282
|
+
3. **The review list.** The scan report starts with "Review these": roles chosen on weak evidence (low confidence, with the reason) and roles with no color, the scales that are a thin guess from use (fewer than three values or four uses, by category) and the spacing values that fit no step, tokens the engine refused, and what the walk left out with its reason: vendored code (`node_modules`, `vendor`, `third_party`), build output (`dist`, `build`), minified files (`.min.` files when the project has style files of its own, and any text with 500-character lines and almost no white space), a link that was not followed, a folder deeper than the limit, a file cut at its limit (with its size), and the files over the 400-file limit. A project with no style files says what was left out, as the place the design may be. A project that names everything has no list.
|
|
283
|
+
4. **Typed values** (`system-schema.ts`). The top-level schema is one object; `changes[].value` is a token value (a string, a number, a list, a color object, a `{ value, unit }`, or the members of a shadow, type style, border, or transition) or a whole token, `tokens` and `modes` are objects, and each parameter says "Used by …" from the table that refuses a parameter for the wrong action (a test checks the two agree). pi checks the call against the schema before the tool runs (`Value.Convert`): a number and a string keep their type; `true` and `null` become text and the engine then refuses them as before. The schema is 5.8 KB (it was 3.5 KB). `test/design-transcript.test.ts` walks the guide's three calls (scan, init from the scan, validate), publishes a page that links `ds/tokens.css`, and runs `checkDesign` in light and dark: no off-system finding.
|
|
284
|
+
5. **Engineering.** `scan-colors.ts` (42 KB) is a shim over `scan-color-base.ts`, `-names.ts`, `-roles.ts` (21 KB, `chooseRoles` is most of it), and `-palette.ts`. No behavior change: the scores are as before and the tests ran unchanged.
|
|
285
|
+
- Weak spots: `chooseRoles` is still one function of about 480 lines; `scan-parse.ts` and `scan-scales.ts` are over 900 lines.
|
|
286
|
+
|
|
287
|
+
## Round 5b: three more input formats (a third held-out set, 0.421)
|
|
288
|
+
|
|
289
|
+
1. **Style Dictionary sources** (`scan-import-sd.ts`; the shared evaluator moved to `scan-import-eval.ts`). Token files in several folders merge in source order, a later file over an earlier one, as Style Dictionary does: the order of the config's `source` (and `include`) globs when there is a config (`config.json`, or a JavaScript config such as `sd.config.mjs` whose lists are written out), else by path. The files of a config's globs are read wherever they are; a file outside them is not (`tokens/archive/old.json`). A config with a template in its globs (`tokens/${brand}/**`) is not read, and the usual folders are (`tokens/`, `properties/`, `brands/`, `themes/`, `design-tokens/`, `style-dictionary/`, at any depth). The classic format (`value`, `type`, `comment`, `attributes`, references `{color.base.red.value}` or `{color.base.red}`) and DTCG (`$value`, `$type`) both work, together. An untyped token gets its type from its category and value (`color`, `size`, `font`, `time`, a unit, a shadow), and a bare number is px or ms. A folder under `brands/` or `themes/` (or a file named for dark) is a mode: the same paths with other values; the first light, default, or alphabetical one is the default with the shared files, a dark one is `dark`, any other is a mode of its own. A project with a config is a token source however few tokens it has. Two files that both start with `color` are one group (before, the second replaced the first).
|
|
290
|
+
2. **Material 3** (`scan-import-material.ts`). `--md-sys-color-*` in a file for each scheme, in a class for each (`.light`, `.dark-medium-contrast`), with the scheme in the variable's suffix, or in a `prefers-color-scheme` block, and the Theme Builder's JSON (`schemes`, `palettes`). Roles: `surface` and `surface-container*` are `color.bg.*`, `on-surface` is `color.text.primary`, `on-surface-variant` is `color.text.muted`, `outline` and `outline-variant` are `color.border.default` and `.subtle`, `primary` is `color.accent.default`, `error` is `color.danger.default`; with no `background` role the surface is the page too. Secondary and tertiary are `accent-2` and `accent-3` (the words name quiet text here). Warning and success are not made up. A scheme with medium or high contrast is a mode (`light-medium-contrast`), with its color scheme set. Palettes are named by hue (`indigo`, with the neutral ones keeping `neutral` and `neutral-variant`) and the roles point at their steps; without palettes the role colors are primitives named as the scan names a palette. Shape, motion, and typeface properties become radius, duration, ease, and font tokens. Material's colors replace the scan's role groups; the project's own other colors stay. Fewer than eight roles are not a Material 3 export.
|
|
291
|
+
3. **Sass palettes** (`scan-sass-values.ts`, `-expr.ts`, `-stmt.ts`, `-eval.ts`). A real Sass evaluator for the parts that make a palette: `@each` (maps, lists, destructuring), `@for`, `@while`, `@if`/`@else`, `@function` and `@return`, `@mixin` and `@include` (a mixin of layout, with `@media` or `@at-root`, is left to the scan), `$x: … !default !global`, maps and lists (`map.merge`, `map.get` with nested keys, `map-get`, `nth`, `length`, `append`), strings with `#{}` in names, selectors, and values, arithmetic with units, `math.div`, and the color functions in Sass's own color model: `mix`, `lighten`, `darken`, `saturate`, `desaturate`, `adjust-hue`, `scale-color`, `adjust-color`, `change-color`, `rgba`, `transparentize`, `opacify`, `grayscale`, `complement`, `invert`, and `color.adjust`, `color.scale`, `color.change`, `color.mix`. Checked against Dart Sass 1.x: 42 color expressions and four whole palettes (nested maps, a function, a mixin) agree to one step of 255. A file with loops, a map built in code, a module function, or a color function in a function is run, in the order the files `@use` and `@import` each other, in one environment; its text becomes what Sass writes (a loop's output on the line of the loop, so that `file:line` in the report stays right) and the scan reads that. The variables a loop keeps for itself are not written. What cannot be run (an unknown function, an undefined variable) stays as written, and the rest runs; limits cap statements, iterations, work, and output. The report says that Sass was run.
|
|
292
|
+
- Weak spots: `@debug`, placeholders, `@extend`, and `@at-root` are not run; division of two plain numbers (`16px/2`) stays text as in a font shorthand; `%` and unit conversion between units (`1in + 2cm`) are not done; a color in a non-sRGB space (`oklch()` in Sass 1.79 and later) is left as written.
|
|
293
|
+
|
|
294
|
+
## Round 5c: four more classes of input (the third set again: 0.421, then 0.686)
|
|
295
|
+
|
|
296
|
+
I wrote my own projects for each class, in several forms, and checked the Sass ones against Dart Sass itself.
|
|
297
|
+
|
|
298
|
+
1. **Style Dictionary configs for modes** (`scan-import-sd-config.ts`). A project with `config.json` and `config.dark.json` (also `config-dark.json`, `sd.config.dark.js`, `dark.config.mjs`, `dark/config.json`, `themes/acme/config.json`), one script that exports a list of configs, a function that returns a config for each theme (`getConfig(theme)` called for `["light", "dark"]`, a `for` loop, `.forEach`, `.map`, a list named `themes`), or a `theme: "dark"` key. The base is the config with no mode (else the light one, else the first). A mode config reads the base config's files with its own `source` over them (`include` is the base; a file of another mode's folder is left out). The mode comes from the key, then the file's name or folder, then the folders of the globs; the word is `dark` or `light` for the words of them (`night`, `day`), else the word itself (a brand). A word that names a platform or a purpose is no mode (`config.web.json`, `config.android.json`, `build.prod.js`). A template name is filled in only when it stands for a mode (`theme`, `mode`, `brand`, `scheme`, `variant`, `skin`...) or its values have a mode word. The glob text is read from the raw file: the comment stripper took `/**/` in `tokens/${theme}/**/*.json` for a comment.
|
|
299
|
+
2. **Panda CSS and Chakra v3 semantic tokens** (`scan-facts-lists.ts`). `semanticTokens.colors.bg = { value: { base: "{colors.gray.50}", _dark: "{colors.gray.950}" } }`, in `defineConfig`, `createSystem`, `defineSemanticTokens`, `defineTokens.colors({…})` (a `const` with a call around its object), or `semanticTokens` as a shorthand. `base`, `_light`, `default` and `DEFAULT` are the default value; `_dark`, `_osDark`, `_night` (a condition the config defines: its selector says dark) are the dark one; an explicit dark beats `_osDark`; a state (`_hover`, `_focus`) is no mode; a condition inside a condition takes its base; `DEFAULT` in a group is the group's name. A reference is `{colors.gray.50}` into `tokens`, a path (`gray.50`), a color, or a keyword (`white`). `{ value: "#fff" }` is a leaf in `tokens` too (radii, fonts, sizes).
|
|
300
|
+
3. **Sass modules** (`scan-sass-modules.ts`, `scan-sass-run.ts`, `scan-sass-eval.ts`). Each stylesheet is a module with variables, functions, and mixins of its own. `@use "x" as p` and `p.$var`, `p.fn()`, `@include p.mixin`; `as *`; `@use "sass:color" as c`, `@use "sass:math" as *`, `math.$pi`; `@forward` with `as prefix-*`, `show`, `hide` (the names are the prefixed ones, as Sass has it), and a configuration that passes through it; `@use … with ($a: 1)` sets the `!default` variables (a configured module is a second copy; a plain `@use` after it gets that copy, as in one compilation); functions and mixins run in the module that declared them, with its configuration; private names (`$-x`, `$_x`) are not visible; `$list...` arguments. Paths find the partial, the index of a folder, the nearest of two, and the project's folders as load paths. The old flat environment stays as the fallback for a name no module explains (a package that is not in the repository, a build tool that compiles files together); a name that a module hides is not looked up there. The evaluated text of a stylesheet is now used also when it calls a function of the project's or includes a mixin that loops, or uses `ns.$var`, `@use … with`, `@forward … as/show/hide`. Checked against Dart Sass: five projects, 36 + 16 + 74 + 9 custom properties, and none differs by more than one step of 255.
|
|
301
|
+
- A scale that is present twice (a Sass map `brand-ramp` and the `--brand-50`…`--brand-900` that a loop makes from it) is one palette family: the shorter name.
|
|
302
|
+
4. **Ant Design** (`scan-facts-antd.ts`). The `token` of a `ThemeConfig` (a file of its own, a `ConfigProvider theme={{…}}`, an array of algorithms): `colorBgLayout` is the page, `colorBgContainer` a surface, `colorText`, `colorTextSecondary`, `colorBorder`, `colorPrimary` (accent), `colorError`, `colorWarning`, `colorSuccess`, the other `color*` seeds as palette colors, `fontFamily`, `fontSize` and its sizes and headings, `borderRadius` and its sizes, `lineHeight`, `boxShadow`, `motionDuration*`, and `sizeUnit` as the spacing base. An object whose algorithm is `darkAlgorithm` (without `defaultAlgorithm`), or whose name or file says dark, is the dark mode; `...shared` and `...lightTheme.token` spread the objects the file declares. The tokens of one component (`components: { Button: { colorPrimary, borderRadius } }`) are left out. Only a file that uses Ant Design (`antd`, `ThemeConfig`, `ConfigProvider`, an algorithm) is read. Quiet text a little under 3:1 on its page (a gray, `#8c8c8c`) keeps its role when its name says muted (before, any contrast under 3:1 cost 45 points).
|
|
303
|
+
- Weak spots: Ant Design's algorithm is not run, so a dark mode is only what a file says (an object with `darkAlgorithm` and no token for a color has the light one, and a switch at run time makes one mode); Panda `textStyles`, `layerStyles`, and recipes are not read; a Style Dictionary config that builds its `source` in code, or a template over two names (`${brand}/${theme}`), is not read; the cross-file spread (`...lightTheme.token`) is not followed, so a dark file has only its own overrides; Sass `meta.load-css`, `@use … as` with a URL, `.sass` files (indented) with `@use ... with` are not covered by the Dart Sass checks (the indented form is converted to braces first); `Run` (`scan-sass-run.ts`, the statements of one stylesheet) is still 1,000 lines.
|