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
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -508,7 +508,7 @@ Get computed bounding boxes via browser rendering.
| `nodeId` | string? | Root node to start from |
| `maxDepth` | number? | Max depth (default 10) |

Returns `{ nodeId, x, y, width, height, children? }` per node — plus, on any node whose content exceeds its box, overflow data (`scrollWidth`/`clientWidth`/`scrollHeight`/`clientHeight` and an `ellipsis` flag for designed truncation): the same capture `canvas_stress` uses to detect clipping. On a primitive, `truncated: true` when one of its own labels is cut by its ellipsis, and `labels` (`[{ chars, scrollWidth, clientWidth }]`, one per own label, in order) on every `tabs` node and on any primitive with a cut label. Overlays (`tooltip`, `popover`, `menu`, `modal`, `toast`, `drawer`) render in a layer after the root: from the root they are listed as its last children wherever they sit in the tree, at root coordinates, and a modal (or a drawer with `scrim: true`) carries `scrim: { x, y, width, height }`, the rect its scrim covers.
Returns `{ nodeId, x, y, width, height, children? }` per node (a node inside a component instance appears under its expanded id, `"<instanceId>/<childId>"`, so two instances never share an id; `batch_design` cannot address it, so edit the component or override the child on the instance) — plus, on any node whose content exceeds its box, overflow data (`scrollWidth`/`clientWidth`/`scrollHeight`/`clientHeight` and an `ellipsis` flag for designed truncation): the same capture `canvas_stress` uses to detect clipping. On a primitive, `truncated: true` when one of its own labels is cut by its ellipsis, and `labels` (`[{ chars, scrollWidth, clientWidth }]`, one per own label, in order) on every `tabs` node and on any primitive with a cut label. Overlays (`tooltip`, `popover`, `menu`, `modal`, `toast`, `drawer`) render in a layer after the root: from the root they are listed as its last children wherever they sit in the tree, at root coordinates, and a modal (or a drawer with `scrim: true`) carries `scrim: { x, y, width, height }`, the rect its scrim covers.

### `generate_scale`

Expand Down Expand Up @@ -859,7 +859,7 @@ Compare two canvases visually. Returns a diff image with changed regions highlig

### `get_feedback` / `resolve_feedback`

Point-and-tell feedback: comments anchored to a specific node (or to the canvas as a whole), stored on the canvas at `metadata.feedback` — plain JSON that travels with the canvas and is git-diffable in bound repos. `get_feedback` returns open entries, each with the comment, the anchor `nodeId`, and a **node snapshot** (`{ type, name, text }`) captured at comment time, so the agent can act without extra lookups; `orphaned: true` marks a comment whose node no longer exists (it stays open — the concern usually applies to the node's replacement). Omit `canvasId` to sweep every canvas in the current context. `resolve_feedback` closes entries with an optional one-line note saying what changed. **Open feedback blocks presenting**, same as open inspector comments — `canvas_list` rows and `canvas_evaluate` results surface an `openFeedback` count (and `init` reports the workspace total) so waiting comments are visible at every checkpoint.
Point-and-tell feedback: comments anchored to a specific node (or to the canvas as a whole), stored on the canvas at `metadata.feedback` — plain JSON that travels with the canvas and is git-diffable in bound repos. `get_feedback` returns open entries, each with the comment, the anchor `nodeId`, and a **node snapshot** (`{ type, name, text }`) captured at comment time, so the agent can act without extra lookups (a comment on a node inside a component instance anchors on the instance, so `nodeId` is always an id `batch_design` can address); `orphaned: true` marks a comment whose node no longer exists (it stays open — the concern usually applies to the node's replacement). Omit `canvasId` to sweep every canvas in the current context. `resolve_feedback` closes entries with an optional one-line note saying what changed. **Open feedback blocks presenting**, same as open inspector comments — `canvas_list` rows and `canvas_evaluate` results surface an `openFeedback` count (and `init` reports the workspace total) so waiting comments are visible at every checkpoint.

Comments are authored in the viewer: toggle **Comment** in the detail-page toolbar, click any element in the preview (a breadcrumb lets you re-scope from the exact element to its card, section, or the whole page), and type the note. The **Feedback** inspector tab lists open and resolved comments with click-to-highlight, and shows the agent's resolution note as a reply. Entries added any other way (hand-edited JSON, a teammate's `git pull`) reach the running server just the same.

Expand Down Expand Up @@ -936,6 +936,8 @@ Every result also carries a **`surface`** field: `{ type, device, source, rulesO

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.

Every check reads the canvas as it renders: each component instance is expanded into its component, with the instance's props and overrides applied, and the design system is resolved inside it. A finding on a node inside an instance reports the instance in `nodeId` (the stored node, fixed in the component or with an override). It reports the inner node in `innerNodeId`, as `"<instanceId>/<childId>"`, the id `snapshot_layout` and `canvas_stress` give it. Its message names the component, and it carries no `fix`, since `batch_design` cannot address an expanded id.

Whenever the `coverage` category runs on a **base** canvas, the result also carries a **`coverage`** field: `{ dataBearing, states, missing }` — whether the screen carries data-bearing content, which state variants (`canvas_add_variant`) already exist, and which demanded states are missing. It's absent on variant canvases (a variant *is* a designed state, so it doesn't demand states of itself).

| Param | Type | Description |
Expand Down Expand Up @@ -985,7 +987,7 @@ The weights are relative, not points out of 100. Each category scores 0–100, a
}
```

An issue produced by a ruleset rule also carries `rule` (its id, e.g. `"mobile-touch-target"`).
An issue produced by a ruleset rule also carries `rule` (its id, e.g. `"mobile-touch-target"`). An issue on a node inside a component instance has `nodeId` set to the instance and also carries `innerNodeId` (the expanded id, `"<instanceId>/<childId>"`) and no `fix`; its message names the component.

**With `mode: "llm"`**, the vision model scores a **fixed rubric** — five axes, each 1–5 with a rationale — instead of one opaque number. The verdict is stamped on the canvas (`metadata.critique`) and the per-project build log so quality is auditable over time. Add `floor` (1–5, default 3, or `FRAMESMITH_CRITIQUE_FLOOR`) to set the per-axis threshold that trips `needsRevision`. **Without an `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`, the call doesn't fail** — the full heuristic result still returns with an `llmNote` explaining the critique was skipped, and the heuristic directive alone decides whether the design is ready.

Expand Down Expand Up @@ -1080,7 +1082,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, 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.
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, and a finding on a node inside one names it by its expanded id, `"<instanceId>/<childId>"` (the id `snapshot_layout` uses; edit the component or override the child on the instance).

| Param | Type | Description |
|-------|------|-------------|
Expand Down
4 changes: 2 additions & 2 deletions VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -572,7 +572,7 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [x] 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
- [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
- [x] 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 (done in Phase 32 slice B)
- [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
- [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/e2e/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
Expand All @@ -588,7 +588,7 @@ _Full spec-driven breakdown in [`docs/specs/PHASE-31-SPEC.md`](docs/specs/PHASE-
Phases 30 and 31 closed with seven follow-ups open, and five of them are quiet false passes: evaluate says READY on a disabled button that renders undimmed inside a component, on a misspelt `$token` the renderer drops, on a `select` border at 1.46:1, and on a phone screen whose links, text inputs and dialogs are never measured. Reproducing them found more: contrast and spacing never look inside a component instance at all, and seeded dark tints and `danger` survive a light preset. This phase clears every follow-up, and first moves the 140 root-level tests into folders that set their tier, so the fixes land in the new layout.

- [x] Slice A — tests in folders: `test/unit`, `test/browser`, `test/e2e` and `test/manual` set the tier, a Chrome guard on `test/unit` proves it at run time, tests are type-checked under `strict`, and files are named by subject, not phase or issue
- [ ] Slice B — one tree: instances expanded and resolved once, so the renderer and every rule (contrast, spacing and cliché included) see the same thing inside a component, and findings there name the instance
- [x] Slice B — one tree: instances expanded and resolved once, so the renderer and every rule (contrast, spacing and cliché included) see the same thing inside a component, and findings there name the instance
- [ ] Slice C — tokens: an `unknown-token` warning for any `$ref` the merged tokens do not define or that is the wrong kind, with a rename autofix when only one name is close; copy props never resolve; tints and `danger` derive from the applied palette, on new stamps and on canvases holding the old seeds
- [ ] Slice D — desktop-app checks: `select` gets a `$border-strong` boundary and joins the boundary check, an active `tree-row` draws a bar the indicator check measures, and stress widens `nav-item` and `tabs` counts
- [ ] Slice E — phone targets: `link` and `text-input` (with a new 44px `size: "lg"`) join the 44px census, and `modal` and `toast` take a `controlSize` the census measures
Expand Down
Loading
Loading