Skip to content

spec: Phase 32, the Phase 30 and 31 follow-ups - #254

Merged
vicmaster merged 2 commits into
masterfrom
phase-32-spec
Nov 20, 2026
Merged

vicmaster merged 2 commits into
masterfrom
phase-32-spec

Conversation

@vicmaster

@vicmaster vicmaster commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Planning artifact for Phase 32 (v2.5), which clears the follow-ups Phases 30 and 31 left open. No code: docs/specs/PHASE-32-SPEC.md plus the VISION entry.

The thesis: five of the seven open follow-ups are quiet false passes, where canvas_evaluate says READY on a screen that is wrong. Each was reproduced on master. Reproducing them found more than the follow-up lines said. Contrast and spacing never look inside a component instance, so 1.14:1 text inside one passes. Seeded dark tints and danger survive a light preset. select draws its border in $border at 1.46:1, and no check measures it. Before the fixes, the 140 tests that sit loose in the repo root move into folders that set their tier, so every later slice lands its tests in the new layout.

Slices

A. Tests in folders. test/unit, test/browser, test/e2e and test/manual set the tier, which replaces the text-matching Chrome markers in the runner. Unit tests run with both Chrome path variables pointed at a missing binary, so a unit test that launches Chrome fails and the runner says it belongs in test/browser. Tests are type-checked under strict for the first time, which means fixing 54 errors in 21 files. Files named by phase or issue are renamed by subject.
B. One tree. Instances are expanded and resolved once, and the renderer and every rule read that tree. A disabled control inside a component now dims, and contrast, spacing and cliché checks see inside components. A finding inside an instance keeps the instance as its nodeId and adds innerNodeId for the node inside.
C. Tokens. A new unknown-token warning fires on any $ref the merged tokens do not define or that is the wrong kind for its prop. It autofixes only when one name is clearly nearest. Copy props such as content are never resolved, which fixes a renderer crash on content: "$body". Tints and danger derive from the applied palette, on new stamps and on canvases that already hold the old seeds.
D. Desktop-app checks. select draws a $border-strong boundary and joins the boundary check. An active tree-row draws a bar that the indicator check measures. Stress widens nav-item and tabs counts.
E. Phone targets. link and text-input join the 44px phone check, and text-input gains size: "lg" at 44px. modal and toast take a controlSize, and the phone check measures their buttons.

Decisions

Every fork in the spec's Clarify section is settled. Each one rests on evidence, on a precedent already in the code, or on Victor's call.

  1. The instance fix covers every rule, not only rendering (Victor). A render-only fix would dim the disabled button but leave contrast and spacing blind inside every component.
  2. Only tree-row gets an indicator bar (Victor). Contained tabs keep their filled segment, whose fill and heavier weight already mark the active tab. The docs say why they are not measured.
  3. Old seed values count as unset (Victor). A stored tint or danger that exactly equals its old seed is dropped before tokens merge, so it derives or inherits. A user who typed one of those six exact values by hand loses it.
  4. End-to-end tests run in the full tier only (Victor). Five of them need no Chrome and leave the local fast loop. CI still runs them, on Node 24 only.
  5. The overlay prop is controlSize, with button's size names (Victor). size already means width on modal, and a touch: true flag could not express a height between 24 and 44.
  6. Test files keep the test- prefix (no problem to solve). Dropping it was cosmetic. The folders, the guard and the type check work either way, and dropping it would add a rename to all 140 files on top of the move.
  7. Interactive tests go in test/manual (follows from the folder rule). The folder sets the tier, so any other home for the two interactive tests would need an exception list again.
  8. unknown-token is a warning (precedent). An icon name that resolves to nothing is already a structure warning, and a token name that resolves to nothing is the same failure. A warning blocks presenting, which a typo must.
  9. Two Phase 31 decisions are reversed (evidence). Phase 31 left select out of the boundary check and gave tree-row no indicator, as scope calls. The 1.46:1 select border shows what that cost, and neither follow-up can be fixed without reversing them.

The main risks, plainly

  • Slice A is a very large diff with no behaviour change. About 140 files move and every import line changes. The PR is reviewed through its file list, and a branch open at the same time would conflict on every moved file.
  • Seeing inside instances moves verdicts. Scaffolds built from components may gain findings they were blind to. Those are fixed in the scaffolds, and the slice B PR lists every verdict that moved.
  • Version hashes change once. Dropping old seeds changes the tokens of every canvas that holds one, so that canvas gets a new sha256r: hash and a recorded approval of it reads STALE. That is correct because its render changes, and the release notes have to say so.
  • unknown-token fires on stored canvases. A canvas carrying a typo today gains a warning and stops being READY.
  • CLAUDE.md and .claude/ are gitignored. Slice A updates their test paths locally, outside its PR.

Verification

Two independent verifiers checked the first draft in parallel. One checked every code reference and reproduced the behaviour claims. The other checked the test-move facts and tried to break every pass/fail rule. A third verifier checked the revised draft. Every finding they raised is resolved in the text. Corrections included a test tsconfig that would have rejected every file and a Chrome guard that 15 browser tests bypassed. The verifiers also found an autofix example that could never fire, and a tint derivation that would have drawn light chips on dark pages.

@vicmaster
vicmaster merged commit 4a97b14 into master Nov 20, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-32-spec branch November 20, 2026 14:18
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