Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -565,7 +565,7 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100

- [x] Slice A — the type: `desktop-app` with a 1440×900 window profile, a ruleset that switches off the type-scale ratio, the WCAG 2.5.8 spacing exception on the 24px floor (web and desktop-app; mobile keeps its 44px rule) and navigation lists that never read as tables (every type), evaluate and import results an agent can read (repeated findings fold, keeping every fix), type-aware generation with state and control-color tokens, and the baseline canvases committed as fixtures
- [x] Slice B — vocabulary: a 24px `button` with an accessible name, `link`, `text-input`, `nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row` and `divider`, plus identity dots that never count as accents (moved here from slice A: it keys on `nav-item`)
- [ ] Slice C — app rules: every click target measured, hand-built targets named, icon-only actions named, one current item per navigation group, a dense type ladder, row rhythm, honest truncation (a tablist whose every label is truncated included), one primary per region, the declaration matching the window, and form coverage counting text-inputs
- [x] Slice C — app rules: every click target measured, hand-built targets named, icon-only actions named, one current item per navigation group, a dense type ladder, row rhythm, honest truncation (a tablist whose every label is truncated included), one primary per region, the declaration matching the window, and form coverage counting text-inputs
- [ ] Slice D — panes: resolution for any number of types and six desktop-app realisations (workbench, list-detail, editor-inspector, browser, dashboard, settings) under the pattern gate
- [ ] Slice E — overlays: one overlay layer at the root with a fixed ladder, and the `tooltip`, `popover`, `menu`, `modal`, `toast` and `drawer` primitives, with overlay screen states as variants
- [ ] Slice F — overlay rules: one modal, text-only tooltips, no large tables in modals, overlays inside the viewport, and advisories on stacked toasts and error toasts
Expand Down
23 changes: 18 additions & 5 deletions docs/GUIDELINES.md

Large diffs are not rendered by default.

26 changes: 21 additions & 5 deletions docs/specs/PHASE-31-SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,9 @@ One profile ships, keyed by id so a second size is one table row later. Values i

- **Clickable primitive**: `button`, `link`, `text-input`, `nav-item`, each tab of a `tabs` node, `tree-row`, `menu-row`, `list-row`, the four controls, Phase 30's `tab-bar` items and `nav-bar` actions, and the header close button and `actions` of a `modal` and the `action` of a `toast`. A node of any other type is never a target, even with `state` set.
- **Target circle**: WCAG 2.5.8's test. An undersized target (below 24 in either dimension) passes when a 24px-diameter circle centred on its box intersects no other target's box and no other undersized target's circle. Circles that only touch do not intersect. A target nested inside another target (ancestor or descendant) is not its neighbour. Disabled targets are neither measured nor neighbours.
- **Pane**: a frame with `overflow: "auto"`, a `modal`, a `drawer`, or the root.
- **Navigation group**: within one pane, all `nav-item`s at depth 0 together, wherever their section frames sit; one `tabs` node is its own group.
- **Region**: the nearest pane. Primary buttons inside three or more sibling frames with the same shape hash (`shapeHash`, `src/project-evaluate.ts:80`), such as a grid of cards, are not counted toward their region.
- **Pane**: a frame with `overflow: "auto"`, a `modal`, a `drawer`, or the root. A node belongs to its nearest pane. (`modal` and `drawer` join with the overlay primitives in slice E.)
- **Navigation group**: within one pane, all `nav-item`s at depth 0 together, wherever their section frames sit; one `tabs` node is its own group. (As built, slice C F2: depth 0 and 1 together, two active at one depth warn.)
- **Region**: the nearest pane. Primary buttons inside three or more sibling frames with the same shape hash (`shapeHash`, moved to `src/shape-hash.ts` in slice C and read there without node names, F6), such as a grid of cards, are not counted toward their region.
- **Element state**: a primitive's `state` property (FR-G1). **Screen state**: a variant canvas (`canvas_add_variant`).
- **Fast / detailed mode, full tier**: as in Phase 30. Fast mode has no rendered rects; detailed mode adds `computeLayout`.

Expand Down Expand Up @@ -113,8 +113,8 @@ One profile ships, keyed by id so a second size is one table row later. Values i
| **FR-B9** | **`divider`.** `divider` (`orientation: 'horizontal' \| 'vertical'`, `inset?`): a 1px hairline in `$border`; vertical dividers separate panes. Not clickable. | A vertical divider between two panes renders 1px wide and full height. |
| **FR-B10** | **Defaults, reuse, stress, titles.** Every new primitive's colors default through `applyControlDefaults` (`src/variables.ts:112`) in a branch of its own (today it branches on `MOBILE_PRIMITIVES`), so an unthemed canvas never crashes. The structure category's reuse advisory (`evaluate.ts:798`) counts the new primitives as reuse. Stress reaches their text through `PRIMITIVE_TEXT_PROPS` (`src/stress.ts:44`): `link.label`, `nav-item.label`, `tabs.items[].label`, `tree-row.label`, `menu-row.label`, `menu-row.shortcut`, `property-row.label`, `text-input.value`. Their labels truncate to one line with an ellipsis and a `title`, so stress reports designed truncation. `text` nodes gain `title?` (today `title` is documented for `nav-bar` and `list-row` only, `src/types.ts:283`), rendered as the `title` attribute. | Every new primitive renders unthemed in both themes with no console errors; long-text on each yields designed-truncation infos only; a `text` with `title` renders the attribute. |
| **FR-C1** | **Every click target is measured on desktop-app.** Rule `desktop-app-target`: FR-A4's floor, error in detailed mode and warning in fast mode. | The baseline's "← Back", rebuilt as a `link` with no other target inside its circle, passes; packed against a neighbouring `link` it fails in detailed mode. |
| **FR-C2** | **Hand-built click targets are named, not gated.** Rule `desktop-app-handbuilt-target`, info: a frame whose only content is one icon, or one icon plus a label of three words or fewer, below 32px in either dimension, is a possible click target; the finding names `button` (icon-only, `xs` or `sm`) or `link`. It never blocks, mirroring Phase 30 FR-C2. A frame inside a clickable primitive is never hand-built. | The baseline detail fixture reports its hand-built toolbar icons as infos. |
| **FR-C3** | **Icon-only actions have names.** Rule `desktop-app-icon-label`, warning: an icon-only `button` with no `ariaLabel`, or a `collapsed` `nav-item` with a blank `label`. (The `modal` close button carries a default name, FR-E2.) | An icon-only button without `ariaLabel` warns; adding one clears it. |
| **FR-C2** | **Hand-built click targets are named, not gated.** Rule `desktop-app-handbuilt-target`, info: a frame whose only content is one icon, or one icon plus a label of three words or fewer, or (spec change S2) a bordered, padded frame holding one such label alone, below 32px in either dimension, is a possible click target; the finding names `button` (icon-only, `xs` or `sm`) or `link`. It never blocks, mirroring Phase 30 FR-C2. A frame inside a clickable primitive is never hand-built. | The baseline detail fixture reports its hand-built toolbar icons as infos. |
| **FR-C3** | **Icon-only actions have names.** Rule `desktop-app-icon-label`, warning: an icon-only `button` or (spec change S3) `link` with no `ariaLabel`, or a `collapsed` `nav-item` with a blank `label`. (The `modal` close button carries a default name, FR-E2.) | An icon-only button without `ariaLabel` warns; adding one clears it. |
| **FR-C4** | **Wayfinding.** Rule `desktop-app-current`, warning: a navigation group (see Terms) with more than one `active` `nav-item`, or with none; a `tabs` node with no active item or more than one; more than one `active` row in one list or tree. A sidebar split into sections is one group per pane, so one active item in one section passes. Navigation deeper than depth 1 (two levels) is out of reach by construction (`depth: 0 \| 1`); a `tree-row` group used for navigation deeper than 2 is an info. | A sidebar with two active items warns, one with none warns, a sectioned sidebar with one active item passes. |
| **FR-C5** | **A dense type ladder.** Rule `desktop-app-type-ladder`, replacing `type-scale-ratio` on desktop-app. For each adjacent pair of distinct sizes a < b: it passes when a ≤ 16 and b − a ≤ 4; otherwise it passes when 1.1 ≤ b / a ≤ 2.5; otherwise it warns. Pinned typography tokens skip the pair check, as today. Separately: any text below 11 warns; text of five or more words below 12 warns; a node resolving the `body` role below 13 warns. The 2.5 cap is a house value chosen to admit a dense app's 14→32 heading (2.29) while flagging a 13→36 jump (2.77). | 12/13/14 passes; 14→32 passes; 13→36 warns; a 10px label warns. |
| **FR-C6** | **Table rows.** Rule `desktop-app-row-rhythm`, applied to detected tables: a header row whose height differs from the body rows by more than 1px warns (Carbon). Body rows that differ from each other by more than 1px are an info, compared within their class (rows holding two stacked text lines, a title and a subtitle, are compared only with each other), because the ±1px threshold is a proposal no source validated. Detailed mode adds column-edge alignment across rows as an info, for the same reason. Fast mode compares authored heights only. | A table whose header is 40 over 32px rows warns; one 40px body row among 32px rows is an info; one cell 3px off is an info in detailed mode only. |
Expand Down Expand Up @@ -232,6 +232,22 @@ One profile ships, keyed by id so a second size is one table row later. Values i
- Row rhythm and truncation reuse the inventory's table detection; column alignment and the 4-character floor use detailed-mode layout (`computeLayout`, as `mobile-safe-area` does at `:2353`). The tabs clause of FR-C7 reads the layout walker's `truncated` flag per tab label, which needs the tabs' label elements placed (today the walker records only whether any label inside a primitive overflows).
- FR-C10: the `form` entry of `COVERAGE_DEMANDS` (`src/evaluate.ts`) counts `text-input` nodes on top of `inv.counts.controls`; drift's `CONTROL_TYPES` stays as is.

**Slice C — as built (recorded 2026-11-13; read this before slice D).**
- **Spec change S2 (FR-C2, approved by Victor).** The baseline detail fixture holds no `icon` nodes: its toolbar (Mobile, Tablet, Desktop, Compare, Fit, JSON, Comment, Archive, Delete) imported as bordered frames holding one text label each, so FR-C2 as written could not meet its own acceptance. FR-C2 now also matches a frame with a drawn `stroke` (not `none` or `transparent`, width not 0) and padding that holds exactly one label of three words or fewer and nothing else. Fast mode estimates a missing height from the icon or the label's line box (its font size, default 16, times its numeric line-height, default 1.2) plus vertical padding; an icon-only frame's width the same way; a labelled frame's width stays unknown. Detailed mode measures the render. Measured: the detail fixture reports all nine toolbar buttons, plus one bordered "Excellent" badge, an accepted info.
- **F1: FR-C1 is FR-A4's check under a rule id.** On desktop-app every finding of the 24px floor carries `rule: "desktop-app-target"`; web runs the same check without one. The acceptance's packed case needs an undersized link, and a labelled `link` renders at least 24 both ways, so the test packs two icon-only links. The census used to treat an unlabelled link's width as unknown; it now measures its glyphs (14, plus 16 with `external`), on web too, so an icon-only link is measured on every type (`linkGlyphWidth`, `src/primitives.ts`).
- **F2: FR-C4's groups.** A pane is a frame with `overflow: "auto"` or the root (`modal` and `drawer` join in slice E). A navigation group is every `nav-item` in one pane, depth 0 and 1 together: two active items at the same depth warn, so an active parent over its active child passes; "none active" warns only for a group of two or more, so a lone item in another pane (a footer Settings link) is not a group. A tree is the `tree-row`s under one parent. "Used for navigation" in the deep-tree info is read as "marks a current row": a tree with an active row nesting to depth 2 or more is the info; a file tree with no current row is silent.
- **F3: FR-C5's floors** give each text at most one finding, the first that applies (below 11, then `$body` below 13, then prose below 12), as `mobile-type-floor` does. The ladder reads the numeric `fontSize` of every text in the instance-expanded tree; `$body` means the raw `fontSize` is the string `"$body"`.
- **F4: FR-C6's rows.** The rows are the ones `detectTable` counted. The first row is the header when its content is text (icons allowed, at least two texts); it is compared with the most frequent height of the one-line body rows. A row is two-line when a non-horizontal frame in it stacks two or more texts. One info per class per table names the odd rows. Column alignment compares the left edges of cells across the rows with the most common cell count and reports the first column off, one info per table. Detailed mode reads rendered heights for header and body rows alike.
- **F5: FR-C7's short truncation** estimates the visible characters as `floor(chars × clientWidth / scrollWidth) − 1` (the ellipsis takes about one). It covers text nodes and every primitive's labels: the layout walker now records `labels` (`chars`, `scrollWidth`, `clientWidth` per own label) on every tablist and on any primitive with a cut label, a new `LayoutRect` field that `snapshot_layout` documents.
- **F6: FR-C8's primaries.** A `button` with no `variant` renders as primary, so it counts; a disabled one does not. The repeat exemption uses the shape hash without node names (`shapeHash(node, 3, { names: false })`, moved to `src/shape-hash.ts`), because a card grid's copies are usually renamed per item; with names, six distinct pricing cards did not read as a repeat. The modal's primary waits for slice E.
- **F7: FR-C10** counts `text-input`s outside detected tables, as the inventory counts controls.
- **F8: the expanded render.** On desktop-app, detailed mode now renders the instance-expanded tree at depth 25 (as mobile does), so the rects every detailed check reads on a desktop-app canvas, the consistency overlap check included, carry the expanded ids.
- **F9: categories.** `desktop-app-target`, `-handbuilt-target`, `-icon-label`, `-current` and `-truncation` report under usability, `-type-ladder` under typography, `-row-rhythm` under consistency, `-primary-count` under structure; each warning costs 10 in its category, infos nothing.
- FR-C9 had nothing left for this slice: its overlay clause lands with the overlay primitives (slice E).
- **Spec change S3 (FR-C3, approved by Victor after verify round 1).** An icon-only `link` (an `icon`, no `label`) had no way to carry a name and passed FR-C3 silently, while F1 made it a measured target. `link` now renders `ariaLabel` as `aria-label` and `title` (as `button` does, never as text), and `desktop-app-icon-label` warns on an icon-only link without one.
- **Verify round 1 fixes.** (a) F4's header row also admits controls (a select-all checkbox, a toggle, a radio, a select) beside text and icons, so a select-all header keeps the header warnings of FR-C6 and FR-C7. (b) FR-C2's fast estimate honours `minWidth` / `minHeight`, and in a frame that is not horizontal adds an icon stacked over a caption (plus the gap) instead of taking the larger. (c) F1's glyph width applies only when no `width` is authored; a non-numeric width (`fill_container`, a percentage) stays unknown. (d) F6's primary is what renders filled: any `variant` but `secondary`, `ghost` or `destructive` (an unknown one included). (e) F3's ladder reads sizes as rendered (`fontPx`: `"14px"`, a `clamp()`'s minimum). (f) The `desktop-app-icon-label` and no-title truncation suggestions no longer embed the node id, so repeated findings fold. Accepted as specced: icon-only links on web now warn in fast mode (F1's census correction); three `text-input`s in an inspector demand an `error` variant (FR-C10 on every type, like three toggles); two navigation regions sharing one pane are one group (F2; the docs tell agents to give each its own pane); a tree split across wrapper frames is several trees; the deep-tree info fires on a file tree with a current row (info only). The FR-C7 short-tab info is subsumed when every label is cut (the warning fires instead); kept for tablists where only some labels are cut.
- **Verify round 2 fixes** (proved red on e8c5715 and green on the fix; not re-verified by an agent). (a) Fix (a) above read the first data row of a headerless row-select table as a header, so its height and a truncating first cell raised header warnings: a first row holding a control is now a header only when its first text is styled apart from the next row's (`fontWeight`, `fontSize`, `color`, `textTransform` or `letterSpacing`). (b) Fix (b) summed an icon and label nested in a horizontal wrapper, or positioned: the sum now needs both to be in-flow children of the frame itself. (c) Fix (c) left `width: "auto"`, `null`, `""` and px strings unmeasured: those hug the glyphs (or measure the px value); only fluid and token widths stay unknown.

**Slice D: panes (FR-D1 to FR-D3)**
- `src/structures.ts:1834`, `:1863`: N-type listing and resolution; `covers()` for `desktop-app`.
- Six realisations, `data-table-app`, and `test-patterns.ts`'s desktop-app set.
Expand Down
Loading
Loading