Skip to content

Phase 32 slice C: unknown tokens and derived tints - #257

Merged
vicmaster merged 6 commits into
masterfrom
phase-32-slice-c
Nov 21, 2026
Merged

vicmaster merged 6 commits into
masterfrom
phase-32-slice-c

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Phase 32 slice C (docs/specs/PHASE-32-SPEC.md, FR-C1 to FR-C6, with the contracts pinned in the spec's M1 to M11 block, the as-built notes N1 to N4, and the two verify rounds recorded after them).

The problem

A misspelt $token was silent. gap: "$space-xxs" (the real token is $space-3xs) resolved to nothing, the renderer dropped it, and canvas_evaluate said READY. A token of the wrong kind rendered garbage the same way: fill: "$body" drew color: 16. Copy was resolved like style, so content: "$body" crashed the renderer and a price such as "$49" was one typo away from becoming a token. The tint layer and danger were seeded as dark values on every stamp, and no preset defines them, so apply_preset light after a stamp left dark chips on a light page.

What changed

  • unknown-token. A new default rule (structure, warning, −10, blocks presenting) on every $ref the resolver reads: a name no token defines, a token of the wrong kind for its prop (a typography or spacing token on a colour prop, a colour on a number prop, a whole token group), a ref on a prop that takes no token (fontFamily: "$display"), a name defined only in the dark layer, and a token whose value is itself a ref. It reads top-level props, padding / cornerRadius entries, border colours, chart series and segments, and modal and toast action colours, inside components too, reported once per place the ref is written.
  • A narrow rename fix. The suggestion names up to three defined tokens within two edits. When exactly one is closest, it is not another rung of a size ladder ($space-lg is never renamed to $space-md), and the ref sits on the stored node itself, canvas_autofix renames it. A padding array or border object is rewritten whole, so two typos in one array share one op.
  • Copy never resolves. One COPY_PROPS set (copy and enum props, plus content, text, name, closeLabel and the donut's centerValue / centerLabel) is skipped by the resolver, the token census and the rule.
  • Tints and danger derive. When no layer defines them, each tint derives from its ink with the generator's own tint rule, in the light or dark mode of the surface (bg-surface, surface, bg-primary, background, else white). A grey ink gets a grey tint. danger falls back to error, then #DC2626 on a light surface and #F87171 on a dark one. Stamps no longer seed them, and a stamp that reads one seeds the surface instead, so an unthemed stamp stays dark like its inks.
  • Old seeds count as unset. A canvas colour still holding one of the six old seed values (matched by name and value) is dropped when its tokens are read, so an inherited value or the derived one shows through. The stored JSON is untouched. get_variables, apply_preset, a canvas-scope generated system, the viewer's token source and generate_color_system's overwrote list all treat it as unset. A canvas holding a seed gets a new sha256r: version hash once, so an approval recorded on it reads STALE.
  • Token usage counts real tokens. The stat and the advisory read the merged tokens (a canvas that only inherits is no longer skipped) and count only refs that resolve.
  • Found in passing. Inline children of a batch_design insert have no id. The unknown-icon check crashed canvas_evaluate on one (on master too); both rules now report such a node on its nearest ancestor with an id, with no fix. The Tailwind importer no longer turns non-colour utilities (text-balance, bg-cover, text-sm/6, bg-red-500/20, bg-(--x)) into colour refs, and a theme colour with such a name still maps.

Decisions the spec text did not settle

  • danger falls back by mode, not to #DC2626 alone. #DC2626 is 3.91:1 on the unthemed scaffold surface #111111, where the old seed #F87171 is 6.83:1. A single literal would have turned every unthemed destructive label into a contrast failure.
  • A grey ink gets a grey tint. The tint rule keeps the ink's hue, and a pure grey has none: the unthemed text-secondary produced a maroon neutral tint. The generator's own output is unchanged; only the derivation uses the grey rule.
  • Single letters are ladder rungs. On an s / m / l ladder $space-m is a size, so it is never renamed to $space-md. A missed rename is cheaper than a wrong size.

Verdicts that moved

Test Before Now
test-patterns.ts web and mobile gate Applied a preset by replacing canvas.variables wholesale, which dropped every seeded spacing, radius and type token: the stamps rendered with those values missing and still scored 99. Applies the preset by merging, as apply_preset does. A new gate holds every structure, unthemed, under each preset and under a generated system, to zero unknown-token findings, with a twin that replaces the variables wholesale and must fail.
test-patterns.ts and the two test/browser desktop gates A component stamp's $bg-primary backdrop was undefined on an unthemed canvas and drew nothing. The harness defines the token it references. The tint predicate reads the tokens the render uses.
test-patterns.ts dark-tint twin Set accent-tint to the old seed. Uses a non-seed dark value; the seed itself now derives.
test-desktop-primitives.ts Pinned the 12% accent mix for the active fill. Pins the derived tint in the surface's mode, including the hsl, rgb, #RGB and named-accent cases.
test-structures.ts Expected danger among the seeded colours. Expects danger and the tints never seeded.

Measured against master, contrast findings fell under every theme: the old dark seeds failed the initials avatar unthemed and every tint chip under the light, material and minimal presets. Under the light preset the chips now fail only where the preset's own inks do (success #16a34a is 3.3:1 and error #ef4444 3.8:1 even on white), which the contrast check reports as before.

Not fixed here

lookupToken reads spacing before radius, so cornerRadius: "$md" under a preset that defines md in both renders the spacing value (16, not 8). The README's own get_variables example (cornerRadius: "$sm") hits it. The rule sees one number kind and stays silent. It predates this slice, and changing the lookup order changes existing renders.

Tests

  • New test/unit/test-unknown-token.ts: every FR-C1 to FR-C4 acceptance, each prop-table entry and copy prop, the fix's edges (distance, ties, ladder rungs, nested borders), origins through components, masters, overrides and id-less nodes, the kill switch, and the autofix ops applied through batch_design.
  • New test/unit/test-derived-tints.ts: FR-C5 and FR-C6, the surface chain and its aliases, alpha and grey inks, each of the six seeds with a one-digit-off twin, preservation and the version hash, and a sweep holding every structure to no contrast error against a derived tint.
  • test/unit/test-tailwind-map.ts: the non-colour utilities, with theme-colour twins.
  • Full tier: 147/147 (unit, browser and e2e) on 124b865 locally. Type check of the tests is clean.
  • Verification: a pre-freeze verifier broke the draft contracts on paper (14 findings, 9 confirmed, all folded in before the build). Round 1 ran four verifiers (spec conformance, mutation testing, a review attacking the gate, the docs-steward) and a cold-reader; round 2 re-verified the fix diff. Every fix landed with a test that fails on the previous snapshot. The last fix round was proved that way but not re-verified by an agent.

Docs

The canvas_evaluate, canvas_autofix, apply_structure, apply_preset, get_variables and colour-system docstrings, the INSTRUCTIONS and init gotchas, GUIDELINES (new sections on the derived tint layer and unknown tokens, the autofix list and fix workflow), README (the rules table, the structure category, the autofix list, get_variables, apply_preset, apply_structure, the tint layer) and VISION (slice C ticked, plus the two follow-ups it closes).

A $ref no token defines, of the wrong kind, or on a prop that takes none is an
unknown-token warning with a rename fix when one name is closest. Copy props
never resolve. The tint layer and danger derive from the inks in the surface's
mode instead of dark seeds, and old seeds count as unset.
@vicmaster
vicmaster merged commit 280a6cd into master Nov 21, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-32-slice-c branch November 21, 2026 20:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant