Skip to content

Add the desktop-app rules (Phase 31 slice C) - #247

Merged
vicmaster merged 4 commits into
masterfrom
phase-31-slice-c
Nov 13, 2026
Merged

vicmaster merged 4 commits into
masterfrom
phase-31-slice-c

Conversation

@vicmaster

Copy link
Copy Markdown
Owner

Slice C of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-C1 to FR-C10): the rules that judge a desktop-app canvas as an application. The spec's "Slice C — as built" block records every decision the spec left open and two spec changes, S2 and S3, both approved before they were built.

What changes

  • Eight desktop-app rules. Each finding carries its rule id, and the surface report lists them in rulesOn on desktop-app canvases only:
    • desktop-app-target: the existing 24px click-target floor under a rule id. It warns in fast mode and is an error in detailed mode when the target's 24px circle reaches a neighbour.
    • desktop-app-handbuilt-target (info, never blocks): a frame below 32px shaped like a button is named, with the primitive to rebuild it as. The shapes are an icon, an icon with a label of up to three words, or a bordered, padded frame holding one short label.
    • desktop-app-icon-label: an icon-only button or link with no ariaLabel warns, and so does a collapsed nav-item with no label.
    • desktop-app-current: checks that the current location is unambiguous.
      • Within one pane, two active nav-items at the same depth warn, and so do two or more nav-items with none active. A pane is a frame with overflow: "auto", or the root.
      • A tabs node with no active tab, or more than one, warns.
      • Two active rows in one tree warn.
    • desktop-app-type-ladder: replaces the adjacent-ratio check on desktop-app.
      • Small sizes may step by up to 4px, so 12/13/14 pass.
      • Larger sizes step by a ratio of 1.1 to 2.5, so 14 to 32 passes and 13 to 36 warns.
      • Text below 11px warns, and so does prose below 12px and the body role below 13px.
    • desktop-app-row-rhythm: applies to tables.
      • A header row more than 1px taller or shorter than the body rows warns.
      • An odd body row is an info.
      • Detailed mode also reports a cell off its column's left edge as an info.
    • desktop-app-truncation: a truncating column header warns, and an ellipsis with no title is an info. Detailed mode adds two more:
      • a tablist whose every label is cut warns
      • an ellipsis that leaves fewer than four characters is an info
    • desktop-app-primary-count (info): two or more primary buttons in one pane. Primaries inside a grid of three or more same-shaped cards don't count.
  • Form coverage counts text-inputs. A form of three or more input controls asks for an error variant, now with text inputs counted, on every type. Drift's control list is unchanged.
  • An icon-only link is measured at its glyphs (14px wide, or 30 with the external glyph) instead of being treated as unknown width. This applies on web too.
  • link renders ariaLabel as aria-label and title, like button (spec change S3).
  • Layout snapshots record each primitive's labels. A primitive's own labels (character count, scroll width, client width) are recorded on every tablist and on any primitive with a cut label, so detailed mode can judge truncation per tab. snapshot_layout documents the field.
  • Agent surfaces updated:
    • the canvas_evaluate, snapshot_layout and batch_design docstrings
    • the server instructions and the usability gotcha
    • docs/GUIDELINES.md (a section per rule, with what a pane and prose mean)
    • the README rule table
    • VISION.md

Decisions worth a look

  1. Spec change S2: hand-built text buttons. The spec's acceptance for hand-built targets named the baseline viewer's toolbar. That toolbar imported as bordered frames holding one text label each, with no icons, so the rule as written could never fire on it. The rule now also matches a bordered, padded frame with one short label. It reports all nine toolbar buttons on the baseline fixture, plus one bordered badge as an info.
  2. Spec change S3: icon-only links need a name. An icon-only link had no way to carry an accessible name and passed the naming rule silently.
  3. This slice changes web verdicts in two places.
    • An icon-only link on a web canvas now warns in fast mode, because the 24px floor finally knows its 14px width. Detailed mode clears it when nothing sits within its 24px circle.
    • An inspector with three or more text fields now asks for an error variant, as three toggles already did.
  4. A button with any variant except secondary, ghost or destructive counts as primary. That includes a button with no variant at all, because that is what renders filled with the accent color.
  5. Detecting a header row. A first row that holds a select-all checkbox looks the same as a row-select data row. It counts as a header only when its text is styled differently from the next row's (weight, size, color, case or tracking).
  6. Panes are scrolling frames. Two navigation regions that share one pane are one navigation group, so a rail beside a sidebar must each be its own scrolling pane. The docs say so.

Testing

  • New test-desktop-app-rules.ts (fast tier), 140+ checks:
    • Every rule's acceptance, with a twin that must fail.
    • Every rule fires on desktop-app in its category, and none fires on web or mobile.
    • Severities, boundaries (31 vs 32px, three vs four words, 16 to 17 vs 17 to 18, a 1px tolerance), the baseline fixture's toolbar, folding, and form coverage inside and outside tables.
  • New test-desktop-app-rules-detailed.ts (Chrome tier):
    • the circle test on icon-only links
    • rendered header heights and column edges
    • short truncations and a crowded tablist
    • a finding inside a component instance reported on the instance
  • test-desktop-app.ts: rulesOn lists every desktop-app rule.
  • Verification, first round: four checks on the first build.
    • Spec conformance, with about 90 code mutations. Every surviving mutation that mattered now has a test.
    • An adversarial bug hunt. It found six real issues, all fixed:
      • a select-all header read as data
      • size estimates that ignored minimum sizes and stacked captions
      • fluid link widths measured at the glyph
      • unusual button variants not counted
      • text sizes written as strings ignored
      • findings that could not fold
    • A docs audit and a cold read of the new guidelines. Their edits are applied.
  • Verification, second round: a second round checked the fixes.
    • It found that two of them went too far: a headerless row-select table, and a caption nested in a row.
    • It also found that link widths "auto", null and "10px" were no longer measured.
    • Those were fixed, and each fix was proved failing on the earlier commit and passing on the fix. They were not re-checked by a third round.
  • Suites:
    • npm run test:full passes 125/125 on f145107.
    • npm run test:fast passes 85/85 on the final commit 6f16160, which only rewords three comments.

Phase 31 slice C (FR-C1..C10): eight desktop-app-* rule ids for targets, hand-built targets,
icon names, wayfinding, the dense type ladder, row rhythm, truncation and primary count, plus
text-inputs in the form coverage demand. Spec change S2 widens FR-C2 to bordered text buttons.
Select-all headers stay headers, fast estimates honour min sizes and stacked captions, fluid
link widths stay unknown, primaries are what renders filled, the ladder reads string sizes, and
findings fold. Spec change S3: link renders ariaLabel and FR-C3 checks icon-only links.
A first row holding a control is a header only when its text is styled apart from the next row.
The stacked icon-and-caption estimate needs both as in-flow children; auto, null and px link widths
are measured again.
@vicmaster
vicmaster merged commit c9c5b1e into master Nov 13, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-c branch November 13, 2026 20:55
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