Skip to content

Phase 31 slice B: the desktop-app vocabulary - #246

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

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

Conversation

@vicmaster

@vicmaster vicmaster commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Slice B of Phase 31 (docs/specs/PHASE-31-SPEC.md, FR-B1 to FR-B10). It also ships three items slice A deferred to this slice: identity dots (FR-A6), the new primitives in the 24px target census, and the declaration clauses of the desktop-app-artboard rule. The spec's "Slice B — as built" block records each decision the spec left open. There is no spec change.

What changes

  • Eight desktop-app primitives on the 24, 32 and 40 pixel steps of the density ladder:

    • link: a standalone text action, at least 24 tall.
    • text-input: a field. Its border is its only boundary; an error draws an icon and the message below the field.
    • nav-item: a sidebar row. The active one shows a tint, a 2px bar and a heavier label. It also has a collapsed 32×32 rail form and an identity dot.
    • tabs: one tablist with a line or contained variant. Each tab is its own target.
    • tree-row: a row that indents 16px per level and shows a disclosure chevron.
    • menu-row: a menu item with a right-aligned shortcut, a destructive form, a checked state and a submenu chevron.
    • property-row: an inspector row with a label column and one value.
    • divider: a 1px hairline.

    Labels truncate to one line with an ellipsis and keep their full text as a title. Colors come from the design system's tokens, with neutral fallbacks when a canvas has none.

  • button gains size: "xs" (24px) and ariaLabel, the accessible name of an icon-only button. The name is never drawn.

  • A text node gains inline links (links: [{ start, end }] character ranges, drawn underlined) and a title tooltip.

  • The new primitives join the 24px floor on web and desktop-app canvases:

    • Not targets: property-row and divider. Inline links are exempt, as WCAG exempts them.
    • Row ownership: a control that is the only target directly inside a property-row, nav-item, menu-row or list-row is measured by the row's box.
    • Measured as rendered: the census uses each primitive's rendered height, so an explicit height can't produce a false pass or a false warning.
    • Not phone targets: the new primitives don't join the mobile 44px rule.
  • Identity dots are not accents. A nav-item's dotColor never counts as a competing accent color. The same color used anywhere else still counts.

  • A canvas holding a desktop-app primitive must declare its type. This applies to nav-item, tabs, tree-row, menu-row and property-row. Undeclared warns, declared mobile warns, and declared web gets an info.

  • Control borders. Checkbox, radio, toggle and text-input boundaries use $border-strong when the design system has that token. Canvases without it render exactly as before.

  • Wiring: the new primitives are covered everywhere the phone primitives already were:

    • stress tests reach their text
    • repeated ones count as component reuse
    • unknown icon names on them are flagged
    • unthemed stamps seed the $accent-tint and $border-strong tokens
    • the breadcrumb component now uses a link for its parent

Decisions worth a look

  1. Only property-row renders children. The other seven primitives draw their own anatomy and drop any children, and the docs say so.
  2. The layout walker now steps through a primitive's child slot. A property-row's value had no node id, so detailed mode could never place it. That made every small target on such a canvas a blocking warning. The value slot is marked, and the walker steps through only marked slots, so no other layout changes.
  3. Tabs shrink in a narrow tablist so their labels truncate. The cost: a crowded tablist can hide every label without a finding, because nothing yet checks tab width. That belongs to the app rules in slice C and is recorded as open.
  4. Two open items are recorded for later slices:
  • A link or text-input on a phone has no 44px check, since adding one would change the mobile ruleset.
  • Form coverage does not count text-inputs toward "three input controls need an error state".

Testing

  • New test-desktop-primitives.ts (fast tier) covers:

    • the markup and defaults of every primitive
    • the 24px census and the row-ownership rule, including siblings, nesting and owners that are themselves clickable
    • identity dots and the declaration clauses
    • stress copy, reuse and seeding
    • inline-link edge cases: overlaps, out-of-range offsets, emoji, null offsets
    • unknown icons, disabled focus, and the dark-palette fallback tint
  • New test-desktop-primitives-render.ts (Chrome tier) covers:

    • rendered sizes in three themes
    • the indents and the aligned shortcut and value columns
    • a full-height pane divider
    • disabled tabs leaving the tab order
    • long text and i18n producing designed truncation only
  • test-pointer-targets.ts gains link, property-row and tabs cases in detailed mode.

  • Verification: four verifiers checked the first build: spec conformance, mutation testing, a bug review and a docs audit. The confirmed findings are fixed:

    • narrow tabs overflowing
    • the unplaced property-row value
    • unknown icons and new text fields mistaken for un-tokenized values
    • census heights that disagreed with the render
    • an ownership rule that ignored sibling targets
    • an unthemed error color
    • a light active tint on dark palettes
    • links splitting emoji
    • disabled rows staying focusable

    Each mutation that mattered now has a test that kills it. A second-round verifier passed every fix, failing on the old code and passing on the new. Its one remaining finding was fixed after that round and proved the same way.

  • Suites: npm run test:fast passes, and npm run test:full passes 123/123.

Added after verification

  • The fallback tint mixes any parseable accent. Without an accent-tint token, the active fill is the accent mixed 12% into the surface. That mix used to need #RRGGBB, so an rgb() or hsl() accent on a dark palette got the light #EFF4FF. It now reads #RGB, #RRGGBB(AA), rgb() and hsl(). A named color still gets the light fallback. New checks in test-desktop-primitives.ts fail on the old code.
  • The spec's open items have a home. A tablist whose every label is truncated becomes a clause of slice C's truncation rule (FR-C7). Counting text-input toward form coverage becomes FR-C10, also in slice C. The missing 44px check for link and text-input on phones is a Phase 30 follow-up in VISION.md.
  • npm run test:full passes 123/123 on 6d97d11.

Phase 31 slice B. Eight primitives on the 24/32/40 ladder (link, text-input,
nav-item, tabs, tree-row, menu-row, property-row, divider), a 24px button with
an accessible name, inline text links and text titles. The new targets join
the 24px census, identity dots never count as accents, and a canvas holding
a desktop-app primitive must declare its type.
Verify round 1 on slice B. The census now uses each primitive's rendered
height, a control owns its row only when it is the row's only target, and
the layout walker steps through the property-row value slot. Tabs truncate
in a narrow tablist, unknown icons and copy props are checked like the
phone primitives, and disabled rows leave the tab order. Docs follow.
The 12% tint mix needed #RRGGBB, so an rgb() or hsl() accent on a dark palette got the light
fallback. Slice B's open items move into the spec: the tablist and text-input coverage gaps
become FR-C7's tabs clause and FR-C10, and the mobile 44px gap goes to the VISION backlog.
@vicmaster
vicmaster merged commit efe9ebe into master Nov 13, 2026
3 checks passed
@vicmaster
vicmaster deleted the phase-31-slice-b branch November 13, 2026 19:20
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