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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -941,7 +941,7 @@ Whenever the `coverage` category runs on a **base** canvas, the result also carr
| Param | Type | Description |
|-------|------|-------------|
| `canvasId` | string | Canvas ID to evaluate |
| `mode` | `"fast"` \| `"detailed"` \| `"llm"` | `"fast"` = JSON-tree analysis only (<100ms). `"detailed"` adds Puppeteer-based pixel-level overlap checks, laid out at the canvas's artboard size. `"llm"` runs fast-mode heuristics plus a vision-model critique (provider picked from `FRAMESMITH_LLM_PROVIDER` or whichever of `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` is set — costs one paid API call per invocation). Default `"fast"`. |
| `mode` | `"fast"` \| `"detailed"` \| `"llm"` | `"fast"` = JSON-tree analysis only (<100ms). `"detailed"` adds Puppeteer-based pixel-level overlap checks, laid out at the canvas's artboard size in the design system's own fonts, as `screenshot` and `canvas_stress` render them (a face that cannot load falls back, and the result then carries a `Font warnings` item). `"llm"` runs fast-mode heuristics plus a vision-model critique (provider picked from `FRAMESMITH_LLM_PROVIDER` or whichever of `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` is set — costs one paid API call per invocation). Default `"fast"`. |
| `categories` | string[]? | Subset of `spacing`, `color`, `typography`, `structure`, `consistency`, `cliche`, `coverage`, `usability`. Defaults to all. |
| `genre` | string? | Style that relaxes specific `cliche` gates — `"material"` allows purple and white elevated surfaces; `"data"` (alias `"dashboard"`) allows realistic figures on a screen whose numbers are the user's own data (dashboards, activity, finance, fitness, logistics); `"commerce"` (alias `"checkout"`) allows the money on a transactional screen — cart, checkout, order confirmation, billing history. Defaults to the canvas's stored genre (`canvas_set_genre` stamps it durably, no token churn; `apply_preset` never changes it). Replaces only the genre: a material-preset canvas keeps the material relaxation. Pick by what the screen is *for* (read screens with the user's own figures → `data`; a screen you complete a purchase on → `commerce`; the Material style → `material` (an editor or admin console is type `"desktop-app"`, not a genre); a pricing page is marketing and gets none of them), not what it contains — the result's `genre` field audits the choice. |

Expand Down Expand Up @@ -1080,7 +1080,7 @@ Content stress test — does the design survive real data? Re-renders the canvas
| `empty` | Detected tables lose their data rows (and runs of two or more consecutive `list-row`s are emptied; on a desktop-app canvas also runs of `nav-item`, `tree-row`, `menu-row` or `property-row`, and card grids) |
| `many` | Data rows ×3 (and `list-row` runs ×3; on a desktop-app canvas also runs of `nav-item`, `tree-row`, `menu-row` or `property-row`, and card grids, a grid of three or more same-shaped children). Copies drop `active`, so a tripled list keeps one current row |

Finding kinds: `clip` (content cut off — *info* when a designed `text-overflow: ellipsis` is doing its job, or when it's a primitive's label hitting its designed ellipsis, or a root with an authored `overflow` clipping or scrolling inside itself; the vertical overflow of a sheet or of any frame with `overflow: "auto"` (an app pane) scrolls and is never a clip, while its horizontal overflow still is; *warning* otherwise), `overflow-x` (a node escapes its parent box or the canvas), `layout-shift` (an **untouched** node ballooning — perturbed nodes, their ancestors, and a stretch sibling that merely follows a legitimately growing parent are exempt). Only **new** breakage counts: anything already clipping at baseline is the design's standing state. Tables are found with the same inventory drift and coverage use; component instances are expanded first.
Finding kinds: `clip` (content cut off — *info* when a designed `text-overflow: ellipsis` is doing its job, or when it's a primitive's label hitting its designed ellipsis, or a root with an authored `overflow` clipping or scrolling inside itself; the vertical overflow of a sheet, a `drawer`, or any frame, `popover` or `menu` with `overflow: "auto"` (an app pane, a popover whose body scrolls) scrolls and is never a clip, while its horizontal overflow still is; *warning* otherwise), `overflow-x` (a node escapes its parent box or the canvas), `layout-shift` (an **untouched** node ballooning — perturbed nodes, their ancestors, and a stretch sibling that merely follows a legitimately growing parent are exempt). Only **new** breakage counts: anything already clipping at baseline is the design's standing state. Tables are found with the same inventory drift and coverage use; component instances are expanded first.

| Param | Type | Description |
|-------|------|-------------|
Expand Down
6 changes: 5 additions & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -575,7 +575,11 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [ ] 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
- [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
- [x] 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 and the empty archive, all six CLEAN in fast and detailed mode in both themes with a CLEAN stress run, and the six baseline defects fixed (`test-viewer-rebuild.ts`); detailed evaluate now lays out in the design system's own fonts, and a drawer or a scrolling popover reads as scrolling under stress
- [ ] Follow-up — a misspelt `$token` in a non-colour prop (`gap: "$space-xxs"`, which does not exist) resolves to nothing and evaluate says nothing; the slice I rebuild caught one only through its own resolved-tree check. Warn on any `$ref` the merged tokens do not define
- [ ] Follow-up — `nav-item.count` is not a stress slot, so a sidebar count of "999+" is never exercised; add it (and `tabs.items[].count`) to the big-numbers perturbation

All nine slices are merged and the acceptance re-run passed. The phase is closed.

_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
8 changes: 4 additions & 4 deletions docs/GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ Start an application screen from a desktop-app realisation, not a web page: see

On web and desktop-app canvases every pointer target is measured against WCAG 2.5.8's 24px floor: the four controls (toggle, checkbox, radio, select) and the clickable primitives (`button`, `list-row`, each `tab-bar` tab and the FAB, each `nav-bar` action, and the [desktop-app vocabulary](#desktop-app-vocabulary): `link`, `text-input`, `nav-item`, each tab of a `tabs` node, `tree-row`, `menu-row`), a modal's close button and actions, and a toast's action. Inline text links and `divider`s are not targets. A lone control first grows to its padded row, two levels up, as before, and a control that is the only target directly inside a `property-row`, `nav-item`, `menu-row` or `list-row` (no link, input or button beside it) is measured by that row's box; a disabled target is neither measured nor in anyone's way; nodes inside a component instance are judged as rendered and reported on the instance. What is still below 24px passes only by WCAG's **spacing exception**: a 24px circle centred on it must reach no other target's box and no other undersized target's circle (circles that only touch pass; a target nested inside another is not its neighbour). Spacing needs rendered positions, so:

- **Detailed mode** (`canvas_evaluate({ canvasId, mode: "detailed" })`) runs the circle test and is the authority: a failure is an **error** that names the neighbour it reaches.
- **Detailed mode** (`canvas_evaluate({ canvasId, mode: "detailed" })`) runs the circle test and is the authority: a failure is an **error** that names the neighbour it reaches. It lays the canvas out in the design system's own fonts, as `screenshot` and `canvas_stress` render it, so its boxes are the ones on screen (a face that cannot load falls back, and the result carries a `Font warnings` item).
- **Fast mode** cannot see spacing, so a target below 24px is a **warning** that names the exception and detailed mode. It blocks presenting until you grow the target or a detailed run clears it.

Mobile keeps its own 44px rule (`mobile-touch-target`), which has no spacing exception.
Expand Down Expand Up @@ -152,8 +152,8 @@ Wherever you insert an overlay in the tree, it renders in **one overlay layer**
The six overlays take their colours from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, and their depth from `$elevation.overlay` (a fallback shadow without it); `fill`, `stroke` and `color` override.

- **`tooltip`** `{ text, x, y }` is a short hint, inverted (`$text-primary` fill, `$bg-surface` text, so light on a dark theme), wrapping at 240px. Text only: it never renders children.
- **`popover`** `{ x, y, size?: "xs" | "sm" | "md" | "lg", children }` is a panel 192 / 320 / 480 / 640 wide (320 by default; a numeric `width` wins), vertical with 12px padding by default; `layout`, `gap` and `padding` apply as on a frame. A comment box or a filter form.
- **`menu`** `{ x, y, children }` holds `menu-row`s and `divider`s: 4px padding, at least 192 wide, hugging its rows.
- **`popover`** `{ x, y, size?: "xs" | "sm" | "md" | "lg", children }` is a panel 192 / 320 / 480 / 640 wide (320 by default; a numeric `width` wins), vertical with 12px padding by default; `layout`, `gap` and `padding` apply as on a frame. A comment box or a filter form. Give it a numeric `height` so fast mode can box it, and `overflow: "auto"` so long content scrolls inside it instead of being cut (stress reads it as scrolling, as it does a `drawer`).
- **`menu`** `{ x, y, children }` holds `menu-row`s and `divider`s: 4px padding, at least 192 wide, hugging its rows. With a numeric `height`, add `overflow: "auto"` so long rows scroll inside it.
- **`modal`** `{ title, size?: "sm" | "md" | "lg", actions?: [{ label, variant?, state? }], closeLabel?, children }` is 480 / 640 / 960 wide (640 by default), centred over its own scrim, which always covers the artboard (`x` / `y` place the modal's top-left instead). It is never taller than the artboard less 64px (less the insets on a phone). Its header holds the title and a close button named "Close" (`closeLabel` renames it). The body holds the children (vertical, 12px gap) and scrolls when tall, between the header and the actions. `actions` render right-aligned as 32px buttons; an action with no variant renders `secondary`, and the filled ones (`primary`, `destructive`) render rightmost. For a delete confirmation: `actions: [{ label: "Cancel" }, { label: "Delete", variant: "destructive" }]`.
- **`toast`** `{ text, tone?: "neutral" | "success" | "warning" | "danger", action?: { label, state? } }` sits bottom-centre, 24px above the artboard's bottom edge (`x` / `y` place its top-left instead); it hugs its text up to 480px. The tone colours a leading glyph (`$success`, `$warning`, `$danger`, neutral `$text-secondary`; `iconColor` overrides); the text stays `$text-primary`. `danger` renders `role="alert"`.
- **`drawer`** `{ size?: "sm" | "md", scrim?, children }` is a 320 / 480 panel pinned to the right edge at full height, 16px padding; `scrim: true` dims what is behind it.
Expand Down Expand Up @@ -486,7 +486,7 @@ The happy path of one static frame with ideal data is half a design. Real UX liv

**The evaluator demands them.** The `coverage` category warns — directive-blocking — when a base canvas carries data-bearing content with no designed states: a detected table demands `empty` + `loading`; a form (3+ input controls: toggles, checkboxes, radios, selects and `text-input`s outside tables, on every type, so an inspector of three text fields counts too) demands `error`. (Table detection requires three matching horizontal rows — two stacked rows are a layout, not data — so the rare header-plus-one-row table goes undetected; name the frame `Table` to claim the shape explicitly. A list whose every row leads with an icon, a dot or a small image is navigation and never detects.) Variant canvases and non-data screens are silent. The result's `coverage: { dataBearing, states, missing }` tells you where you stand, and `canvas_list` shows the designed states per screen.

**Then stress it.** `canvas_stress` re-renders the canvas under hostile-but-realistic content — `long-text` (×2.2 + an unbroken German compound), `i18n` (×1.4), `big-numbers` (`9` → `999+`, `$1.5M` → `$1,520,847.33`), `empty`, `many` (rows ×3; tables and runs of `list-row`s on every type, and on a desktop-app canvas also runs of `nav-item`, `tree-row`, `menu-row` or `property-row` and card grids, a grid of three or more same-shaped children; a tripled list keeps one active row) — and reports what broke, by node id: `clip` (info when a designed ellipsis is doing its job, or when it's a primitive's label hitting its designed ellipsis, or a root with an authored `overflow` clipping or scrolling inside itself; the vertical overflow of a sheet or of any frame with `overflow: "auto"` scrolls and is never a clip, while its horizontal overflow still is; warning otherwise), `overflow-x`, `layout-shift` (an untouched node ballooning — perturbed nodes, their ancestors, and a stretch sibling that merely follows a legitimately growing parent, like a full-height sidebar next to a growing table, are all exempt). Only *new* breakage counts. Fix findings with the [width strategies](#width-strategies) above — fluid widths, `minWidth` or `minHeight` floors, wrapping — or give a must-stay-single-line label `textOverflow: "ellipsis"` (the designed-truncation property: the clip downgrades to info because truncating is the design) — and re-run until `CLEAN`. A data screen goes to the user with its states designed and a `CLEAN` stress verdict, the same way it goes with a >95 score. `canvas_evaluate` holds you to it: once stress has recorded a verdict, the evaluate result carries a `stress` field (`{ verdict, warnings, type, current }` — `current` is false after an edit or a type change since the run), and a `FRAGILE` verdict keeps the directive `NOT READY` until a full `CLEAN` run (all five perturbations) replaces it — a subset run can record `FRAGILE` but never clear it. The verdict lives in server memory, so a restart forgets it.
**Then stress it.** `canvas_stress` re-renders the canvas under hostile-but-realistic content — `long-text` (×2.2 + an unbroken German compound), `i18n` (×1.4), `big-numbers` (`9` → `999+`, `$1.5M` → `$1,520,847.33`), `empty`, `many` (rows ×3; tables and runs of `list-row`s on every type, and on a desktop-app canvas also runs of `nav-item`, `tree-row`, `menu-row` or `property-row` and card grids, a grid of three or more same-shaped children; a tripled list keeps one active row) — and reports what broke, by node id: `clip` (info when a designed ellipsis is doing its job, or when it's a primitive's label hitting its designed ellipsis, or a root with an authored `overflow` clipping or scrolling inside itself; the vertical overflow of a sheet, a `drawer`, or any frame, `popover` or `menu` with `overflow: "auto"` scrolls and is never a clip, while its horizontal overflow still is; warning otherwise), `overflow-x`, `layout-shift` (an untouched node ballooning — perturbed nodes, their ancestors, and a stretch sibling that merely follows a legitimately growing parent, like a full-height sidebar next to a growing table, are all exempt). Only *new* breakage counts. Fix findings with the [width strategies](#width-strategies) above — fluid widths, `minWidth` or `minHeight` floors, wrapping — or give a must-stay-single-line label `textOverflow: "ellipsis"` (the designed-truncation property: the clip downgrades to info because truncating is the design) — and re-run until `CLEAN`. A data screen goes to the user with its states designed and a `CLEAN` stress verdict, the same way it goes with a >95 score. `canvas_evaluate` holds you to it: once stress has recorded a verdict, the evaluate result carries a `stress` field (`{ verdict, warnings, type, current }` — `current` is false after an edit or a type change since the run), and a `FRAGILE` verdict keeps the directive `NOT READY` until a full `CLEAN` run (all five perturbations) replaces it — a subset run can record `FRAGILE` but never clear it. The verdict lives in server memory, so a restart forgets it.

## Reviewing the set

Expand Down
Loading
Loading