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
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -397,7 +397,7 @@ Application screens (`type: "desktop-app"`) are built from eight primitives on t

`fill`, `stroke`, `color`, `iconColor` and `secondaryColor` override the token defaults (`tabs.fill` is the contained variant's active background). A canvas that holds a `nav-item`, `tabs`, `tree-row`, `menu-row` or `property-row` must declare its type (`desktop-app-artboard`).

**Element states.** `state: "hover" | "focus" | "pressed" | "disabled"` on a `button`, `link`, `text-input`, `nav-item`, `tree-row`, `menu-row`, `list-row` or control (`toggle`, `checkbox`, `radio`, `select`; on the item for `tabs`, `tab-bar`, `nav-bar` actions, `modal` actions and a `toast` action) draws that state from the design system's state tokens: hover, focus and pressed layer the label colour over the fill, or over what is behind a target with no fill (8 / 10 / 10%), focus adds a 2px `$focus-ring` at a 2px gap (inside the box for a tab and a tab-bar item), and disabled renders in `$text-primary` at `disabledContent` 38% (a drawn fill or border at `disabledContainer` 12%) when the `state` tokens set either disabled opacity (a lone one takes the other's Material value), else at 0.5 in the target's own colours. An authored `opacity` wins. It is for a states sheet or a screenshot; the evaluator never needs a state drawn. `state: "disabled"` counts as disabled wherever `disabled: true` does: it leaves the tab order, the 24px census and the primary count (the phone's 44px census still measures a disabled target). Other node types ignore it.
**Element states.** `state: "hover" | "focus" | "pressed" | "disabled"` on a `button`, `link`, `text-input`, `nav-item`, `tree-row`, `menu-row`, `list-row` or control (`toggle`, `checkbox`, `radio`, `select`; on the item for `tabs`, `tab-bar`, `nav-bar` actions, `modal` actions and a `toast` action) draws that state from the design system's state tokens: hover, focus and pressed layer the label colour over the fill, or over what is behind a target with no fill (8 / 10 / 10%), focus adds a 2px `$focus-ring` at a 2px gap (inside the box for a tab and a tab-bar item), and disabled renders in `$text-primary` at `disabledContent` 38% (a drawn fill or border at `disabledContainer` 12%) when the `state` tokens set either disabled opacity (a lone one takes the other's Material value), else at 0.5 in the target's own colours. An authored `opacity` wins. It is for a states sheet or a screenshot; the evaluator never needs a state drawn: on a desktop-app canvas four rules compute each target's focus ring, active indicator, disabled look and boundary from the scene (`desktop-app-focus-visible`, `desktop-app-state-contrast`, `desktop-app-disabled`, `desktop-app-boundary`, in the rules table below). `state: "disabled"` counts as disabled wherever `disabled: true` does: it leaves the tab order, the 24px census and the primary count (the phone's 44px census still measures a disabled target). Other node types ignore it.

#### Overlays

Expand Down Expand Up @@ -929,6 +929,10 @@ Every result also carries a **`surface`** field: `{ type, device, source, rulesO
| `desktop-app-truncation` | usability | warning / info | Desktop-app only: a truncating column header warns; a hand-built ellipsis with no `title` is an info. Detailed mode: a `tabs` node whose every label is cut warns, and an ellipsis leaving fewer than four characters is an info. |
| `desktop-app-primary-count` | structure | info | Desktop-app only: two or more primary `button`s in one pane (any variant but `secondary`, `ghost` or `destructive` renders filled, so it counts; no variant included). A modal's `actions` with `variant: "primary"` count in the modal's pane. Primaries inside three or more same-shaped sibling frames, such as a card grid, don't count. |
| `desktop-app-overlay` | usability | warning / info | Desktop-app only: warns on a second `modal`; a `tooltip` with children; inside a modal, a table of more than ten body rows or a frame with `overflow: "auto"` that renders wider than the modal or scrolls sideways; an overlay that leaves the viewport (the root's size, else the window's; a modal wider than the viewport less 32px in both modes, in fast mode a popover or menu with numeric `x`/`y`/`width`/`height` and a placed modal's sides, in detailed mode every rendered overlay); a `popover` or `menu` on a canvas with a modal or a scrimmed drawer, which renders under the scrim. Infos: a second `toast`, a `danger` toast, an `anchor` naming no node or nothing clickable. |
| `desktop-app-focus-visible` | color | error / info | Desktop-app only, in each theme: a focus ring (`$focus-ring`, else `$accent`) below 3:1 against the pixels it covers unfocused (the backdrop behind the target; a tab's own fill for its inset ring). One error per ring and backdrop, with `nodeIds` and `count`; a target whose backdrop or ring cannot be read is listed in one info. Disabled targets are skipped. |
| `desktop-app-state-contrast` | color | warning | Desktop-app only, in each theme: an active `nav-item`'s bar or an active line tab's underline below 3:1 against its active fill, at rest or in hover. |
| `desktop-app-boundary` | color | warning | Desktop-app only, in each theme: a `text-input` border, an unchecked `checkbox` or `radio` outline, or an unchecked `toggle` track below 3:1 against what is behind it. A border that draws nothing (`transparent`, an unresolved token) counts as invisible; a field whose own fill clears 3:1 passes. `$border-strong` clears it on `bg-primary` and `bg-surface`. |
| `desktop-app-disabled` | color | info | Desktop-app only, when the `state` tokens set the disabled opacities: targets whose disabled content would draw within 1.1:1 of their enabled content. On every type, text inside a disabled clickable primitive is exempt from the text-contrast error. |

Repeated findings fold in this result: three or more warnings or infos with the same severity, category, rule (or tell) and theme come back as one entry when they also share their message — on its shape for members that carry a fix (each fix op holds its node's specifics), word for word apart from quoted node text for members without one. The entry keeps the first one's message and adds `nodeIds` (distinct), `count` and, when they had fixes, `fixes: [{ nodeId, op }]`. Errors never fold, and `canvas_autofix` works from the unfolded list.

Expand All @@ -946,7 +950,7 @@ Whenever the `coverage` category runs on a **base** canvas, the result also carr
| Category | Weight | Checks |
|----------|--------|--------|
| `spacing` | 20 | Off-scale padding/gap values (`gap: 0`, a flush stack, is never flagged), plus spacing variety measured against the canvas's **declared** scale (`set_variables`/`generate_scale` spacing tokens) — only values *not* on that scale count toward sprawl, so a design built entirely from its own multi-step scale (framesmith's generated scale ships nine: `space-3xs`…`space-3xl`) isn't penalized for using it. No declared scale falls back to the old total-unique-values count, with a suggestion to declare one |
| `color` | 25 | WCAG AA contrast ratios for text against nearest background — checked in BOTH themes when a `dark` token layer exists (dark-run issues carry `theme: "dark"`, score takes the worse theme, and dark failures point at the dark layer instead of carrying a literal fix). WCAG-passing pairs that are perceptually weak by **APCA** get an info advisory (Lc vs ~75 body / ~60 large) — APCA is a candidate method, not a standard; it never blocks |
| `color` | 25 | WCAG AA contrast ratios for text against nearest background — checked in BOTH themes when a `dark` token layer exists (dark-run issues carry `theme: "dark"`, score takes the worse theme, and dark failures point at the dark layer instead of carrying a literal fix). WCAG-passing pairs that are perceptually weak by **APCA** get an info advisory (Lc vs ~75 body / ~60 large) — APCA is a candidate method, not a standard; it never blocks. On a desktop-app canvas it also carries the four element-state rules (`desktop-app-focus-visible`, `desktop-app-state-contrast`, `desktop-app-boundary`, `desktop-app-disabled`; see the rules table above), each judged in both themes. Text inside a disabled clickable primitive is exempt, on every type |
| `typography` | 20 | Type-scale ratios (1.1–2.0; adjacent sizes both declared as typography tokens are pinned and skip the check), font-family count, weight variation — plus score-neutral craft advisories: measure (prose past ~75 characters per line; warning past 90), tracking (display text ≥28px without negative letter-spacing, autofixable), and tabular numerals (numeric table columns without `tabularNums`, autofixable) On a mobile canvas `mobile-type-floor` adds −10 per warning. |
| `structure` | 15 | Tree depth, naming coverage, design-token usage %, component reuse, unknown icon names (an icon node, or a mobile primitive's icon prop — `button.icon`, `leading.icon`, nav-bar `trailing[].icon`, `tab-bar` `items[].icon` (required) and `fab.icon` — that resolves in neither set renders an empty slot: a directive-blocking warning, −10 structure score each; autofixable for icon nodes and `button.icon` when one spelling resolves) `mobile-artboard` adds −10 per warning, on every type. |
| `consistency` | 20 | Frames missing `layout`, sibling overlap (detailed mode; positioned siblings that content scrolls under — absolute, sticky, pinned chrome, a sheet, a bar pinned to the bottom — are exempt, while a bar pinned to the top still counts) — plus score-neutral advisories: **token detachment** (a literal `fill`/`stroke`/`color`/`cornerRadius` that exactly equals a token's value flags with a mechanical `$ref` autofix; ambiguous matches list candidates and never guess) and **ad-hoc motion** (3+ distinct duration/easing combos with no motion tokens declared) |
Expand Down
3 changes: 2 additions & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -573,7 +573,8 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [x] Slice F — overlay rules: one modal, text-only tooltips, no large tables in modals, overlays inside the viewport, nothing under a scrim, and advisories on stacked toasts, error toasts and dangling anchors
- [x] Slice G — element states: hover, focus, pressed and disabled as a primitive property (and on the items of tabs, tab-bar, nav-bar, modal and toast), drawn from state tokens; focus is a 2px ring at a 2px gap, disabled renders in the on-surface colour, and `state: "disabled"` counts as disabled in the 24px census and the primary count
- [ ] Follow-up — a disabled control inside a component instance renders undimmed, because instances render after variable resolution (`resolveInstance`); resolve instance subtrees too, so `disabled` and `state` dim inside components as they do outside
- [ ] Slice H — state checks: focus rings, active indicators, disabled renders and control boundaries checked analytically on every interactive primitive, without being drawn
- [x] Slice H — state checks: focus rings, active indicators, disabled renders and control boundaries checked analytically on every interactive primitive, without being drawn, in each theme; text inside a disabled target is exempt from text contrast on every type
- [ ] Follow-up — `select` is not in the boundary check, though its `$border` is its only boundary too; and `tree-row` and the contained `tabs` draw no indicator mark when active (a tint and a heavier weight only), so the active-indicator check has nothing to measure on them
- [ ] Slice I — the acceptance re-run: the viewer's gallery, detail with inspector and archive rebuilt as canvases, with the comment popover and delete-confirm states

_Full spec-driven breakdown in [`docs/specs/PHASE-31-SPEC.md`](docs/specs/PHASE-31-SPEC.md). Deliberately out of scope: porting the viewer's code, anchored overlay rendering, keyboard behaviour, narrow-window collapse, the command palette and bulk-selection variants, importer work, and desktop-app rules on web._
Expand Down
Loading
Loading