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
31 changes: 25 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,7 +208,7 @@ Clone a screen into a linked **state variant** — the empty / loading / error v
| Param | Type | Description |
|-------|------|-------------|
| `canvasId` | string | The base canvas (a variant id also works — it resolves to the root base; variants never nest) |
| `state` | string | The state this variant designs — `empty` / `loading` / `error` recommended; free string accepted |
| `state` | string | The state this variant designs — `empty` / `loading` / `error` for data states, `menu-open` / `comment-open` / `confirm-delete` / `toast` for overlay states; free string accepted |

Returns `{ canvasId, name, state, of, idMap }` — `idMap` maps every base node id to its clone, so follow-up edits target the right nodes immediately. One canvas per state per base (a duplicate state errors). The viewer shows a screen and its variants as one card with state chips; `canvas_list` rolls designed states onto the base row.

Expand Down Expand Up @@ -310,7 +310,7 @@ R("nodeId", { type: "text", content: "Replaced" })

**Returns** `{ ok, nodeIds, results }`. `nodeIds` maps each bound variable to the node ID it created — e.g. `{ "header": "n_a1b2" }` — so you can target those nodes in later calls (bindings only live within a single call). `results` lists each op's outcome in order; an op that succeeded but will not fully take effect carries a `warning` (a `shadow` beside an active `shadows`, a chart `highlight` entry outside the series data). If the call wrote a `fontFamily` nothing can serve yet (not cached, registered, or system/generic), a `Font warnings` content item names it — a cache-only check with no network call, so it's a heads-up, not exhaustive.

**Node types:** `frame`, `text`, `rectangle`, `ellipse`, `image`, `icon`, `path`, `component`, `instance`, `toggle`, `checkbox`, `radio`, `select`, `chart`, `skeleton` (loading-placeholder block — token-derived neutral fill; pulses subtly in the live viewer, always static in screenshots/exports so diffs stay deterministic; `pulse: false` opts a block out), the mobile primitives `status-bar`, `home-indicator`, `nav-bar`, `tab-bar`, `button`, `list-row`, `sheet` (see [Mobile primitives](#mobile-primitives)), and the desktop-app primitives `link`, `text-input`, `nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row`, `divider` (see [Desktop-app primitives](#desktop-app-primitives))
**Node types:** `frame`, `text`, `rectangle`, `ellipse`, `image`, `icon`, `path`, `component`, `instance`, `toggle`, `checkbox`, `radio`, `select`, `chart`, `skeleton` (loading-placeholder block — token-derived neutral fill; pulses subtly in the live viewer, always static in screenshots/exports so diffs stay deterministic; `pulse: false` opts a block out), the mobile primitives `status-bar`, `home-indicator`, `nav-bar`, `tab-bar`, `button`, `list-row`, `sheet` (see [Mobile primitives](#mobile-primitives)), and the desktop-app primitives `link`, `text-input`, `nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row`, `divider` (see [Desktop-app primitives](#desktop-app-primitives)), and the overlays `tooltip`, `popover`, `menu`, `modal`, `toast`, `drawer` (see [Overlays](#overlays))

**Properties:** `fill`, `gradient`, `stroke`, `strokeWidth`, `strokeStyle`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `cornerRadius`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `layout` (`"horizontal"` | `"vertical"` | `"grid"`), `gap`, `rowGap`, `gridColumns`, `gridColumn`, `gridRow`, `padding`, `alignItems`, `justifyContent`, `fontSize`, `fontFamily`, `fontWeight`, `color`, `content`, `textAlign`, `lineHeight`, `letterSpacing` (px), `textDecoration`, `textTransform`, `textOverflow` (`"ellipsis"` — designed single-line truncation; `canvas_stress` reports clips behind it as info), `tabularNums`, `fontVariationSettings`, `src`, `objectFit`, `opacity`, `shadow` (CSS string, or `"$elevation.<name>"` referencing an elevation token), `shadows`, `blur`, `backdropBlur`, `backdropFilter`, `overflow`, `wrap`, `position` (`"absolute"` | `"relative"` | `"fixed"` | `"sticky"`), `x`, `y`, `bottom`, `right`, `icon`, `iconSize`, `iconColor`, `iconStyle`, `checked`, `disabled`, `value`, `d`, `viewBox`, `strokeLinecap`, `strokeLinejoin`, `strokeDasharray`, `animation`, `transition` (object, or `"$motion.<name>"` referencing a motion token), `kind`, `series`, `segments`, `innerRatio`, `centerValue`, `centerLabel`, `sparkKind`, `xDomain`, `yDomain`, `curve`, `gridlines`, `xLabels`, `yLabels`, `componentId`, `overrides`, `safeArea` (`{ top, bottom }`, document root only — insets the renderer adds to the root's top and bottom padding; `canvas_create` with `type: "mobile"` writes the device's), `name` (a readable label — `find_nodes` and component overrides match on it), `pulse` (skeleton only), `responsive` (`"stack"` | `"wrap"`)

Expand Down Expand Up @@ -397,6 +397,25 @@ 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`).

#### Overlays

Six overlays draw screen states: an open menu, a comment popover, a confirm dialog, a toast. Put each in a state variant (`canvas_add_variant` with `menu-open`, `comment-open`, `confirm-delete` or `toast`); coverage lists those states and never demands them. Wherever an overlay sits in the tree, it renders in one layer after the content, so a pane never clips it and a sticky bar never covers it. `x` / `y` are offsets from the root's top-left, not from the parent. Layers are fixed by kind, with no z-index property: `popover` and `menu` 400, the modal's scrim 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. `anchor` names the node that opens an overlay; it is never rendered (the overlay rules of a later release read it). Colours come from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, depth from `$elevation.overlay`.

| Type | Key props | What it is |
|---|---|---|
| `tooltip` | `text`, `x`, `y` | A short hint, inverted, wrapping at 240px; never renders children |
| `popover` | `x`, `y`, `size` (`xs` 192 / `sm` 320 / `md` 480 / `lg` 640), children | A panel (vertical, 12px padding by default) for a comment box or a filter form |
| `menu` | `x`, `y`, children (`menu-row`s, `divider`s) | A menu at least 192 wide, hugging its rows |
| `modal` | `title`, `size` (`sm` 480 / `md` 640 / `lg` 960), `actions: [{ label, variant? }]`, `closeLabel`, children | Centred over its own full scrim, with a close button named "Close"; actions right-aligned, the filled one (`primary` or `destructive`) rightmost, an action with no variant `secondary` |
| `toast` | `text`, `tone` (`neutral` / `success` / `warning` / `danger`), `action: { label }` | Bottom-centre, 24px above the artboard's edge; the tone colours a leading glyph |
| `drawer` | `size` (`sm` 320 / `md` 480), `scrim`, children | A panel pinned to the right edge at full height |

```
I("document", { type: "modal", title: "Delete \"Checkout\"?", actions: [{ label: "Cancel" }, { label: "Delete", variant: "destructive" }] })
```

A modal and a drawer are panes of their own for `desktop-app-current` and `desktop-app-primary-count`; a modal's close button and actions and a toast's action are pointer targets. An undeclared canvas holding an overlay warns until it declares a type (`desktop-app-artboard`); web and mobile canvases may hold overlays freely.

### `find_nodes`

Find nodes by what they are — property values, text content, or name — instead of hand-tracking ids. Read-only; the query twin of `replace_matching_properties`.
Expand Down Expand Up @@ -487,7 +506,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.
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.

### `generate_scale`

Expand Down Expand Up @@ -897,16 +916,16 @@ Every result also carries a **`surface`** field: `{ type, device, source, rulesO
| `mobile-type-floor` | typography | warning | Text below 11px, `$body` below 16px, or prose of five or more words below 13px (copy of twelve or more words at 13–15px is an info). |
| `mobile-one-column` | usability | info | Prose set side by side in a horizontal or grid frame: two or more children each holding eight or more words. |
| `mobile-artboard` | structure | warning / info | Runs on every type. A mobile canvas 500px or wider warns, and any other size than the device's is an info. An undeclared canvas narrower than 500px warns until `canvas_set_type` declares it; one declared `web` gets an info. |
| `desktop-app-artboard` | structure | warning / info | Runs on every type. Warns on a desktop-app canvas narrower than 1024px, the narrowest window the desktop-app layouts are built for. Also warns on a canvas that holds a desktop-app primitive (`nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row`) and was never declared, or is declared `mobile`; one declared `web` gets an info. Primitives inside an instance count. |
| `desktop-app-artboard` | structure | warning / info | Runs on every type. Warns on a desktop-app canvas narrower than 1024px, the narrowest window the desktop-app layouts are built for. Also warns on a canvas that holds a desktop-app primitive (`nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row`) and was never declared, or is declared `mobile`; one declared `web` gets an info. An undeclared canvas holding an overlay (`tooltip`, `popover`, `menu`, `modal`, `toast`, `drawer`) warns too; declared web or mobile, overlays alone raise nothing. Primitives inside an instance count. |
| `type-scale-ratio` | typography | warning | On by default: adjacent font sizes stepping by a ratio below 1.1 or above 2.0 (pinned typography tokens skip it). The desktop-app ruleset turns it off, since dense apps step 12 / 13 / 14 on purpose; it then appears in `rulesOff`, and `desktop-app-type-ladder` judges the sizes instead. |
| `desktop-app-target` | usability | warning / error | Desktop-app only: the 24px floor (the `usability` row under Categories below), under its rule id. Fast mode warns on a target under 24px in either dimension; detailed mode errors when its 24px circle reaches a neighbour. An unlabelled `link` with no width (or `"auto"`) is measured at its glyphs (14px wide, 30 with `external`), on web too. |
| `desktop-app-handbuilt-target` | usability | info | Desktop-app only: a frame below 32px holding one icon, an icon plus a label of up to three words, or (bordered and padded) one such label alone, the shape an imported text button takes. Frames inside a clickable primitive or a `property-row` are never counted. Rebuild it as a `button` or `link` if it is clickable. |
| `desktop-app-icon-label` | usability | warning | Desktop-app only: an icon-only `button` or `link` with no `ariaLabel`, or a `collapsed` `nav-item` with a blank `label`. |
| `desktop-app-current` | usability | warning / info | Desktop-app only: in one pane (a frame with `overflow: "auto"`, or the root; each node belongs to its nearest), two active `nav-item`s at one depth, or two or more with none active (give each navigation region its own scrolling pane); a `tabs` node with no active tab or more than one; two active `tree-row`s under one parent. A tree with a current row that nests past two levels is an info. |
| `desktop-app-current` | usability | warning / info | Desktop-app only: in one pane (a frame with `overflow: "auto"`, a `modal`, a `drawer`, or the root; each node belongs to its nearest), two active `nav-item`s at one depth, or two or more with none active (give each navigation region its own scrolling pane); a `tabs` node with no active tab or more than one; two active `tree-row`s under one parent. A tree with a current row that nests past two levels is an info. |
| `desktop-app-type-ladder` | typography | warning | Desktop-app only, replacing `type-scale-ratio`: adjacent sizes a < b step by at most 4px while a ≤ 16, else by a ratio of 1.1 to 2.5 (pinned token pairs skip). Also text below 11px, prose of five or more words below 12px, and a `$body` text below 13px. |
| `desktop-app-row-rhythm` | consistency | warning / info | Desktop-app only, on detected tables: a header row more than 1px off the one-line body rows warns; a body row off its siblings is an info (title-over-subtitle rows compared only with each other); detailed mode adds a cell off its column's left edge as an info. Fast mode reads authored heights only. |
| `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). Primaries inside three or more same-shaped sibling frames, such as a card grid, don't count. |
| `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. |

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 Down
3 changes: 2 additions & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -556,6 +556,7 @@ The mobile attempt (2026-09-07) built one iOS screen end to end on v2.2.0 and go
All seven slices are merged and the acceptance re-run passed. The phase is closed.

- [ ] Follow-up — `link` and `text-input` join the mobile 44px touch census. Phase 31 slice B added both primitives for app screens; on a phone canvas they are not measured today, so a 32px text-input passes silently.
- [ ] Follow-up — overlay controls on a phone. Phase 31 slice E's `modal` close button and actions (32px) and `toast` action (24px) are drawn at fixed pointer sizes and are not in the mobile 44px touch census, so a modal on a phone canvas passes silently; meeting 44px needs a size option on the overlay (render never depends on type), and the census then measures it. Until then the docs send phone dialogs to `sheet`.

_Full spec-driven breakdown in [`docs/specs/PHASE-30-SPEC.md`](docs/specs/PHASE-30-SPEC.md). Deliberately out of scope: an Android profile, tablet and other types, a tappable flag on frames, a thumb-reach rule, interaction and flows, mobile import, and mobile commerce archetypes (those come next, on the anatomy/realisation split this phase creates)._

Expand All @@ -568,7 +569,7 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [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
- [x] Slice D — panes: resolution for any number of types, six desktop-app realisations (workbench, list-detail, editor-inspector, browser, dashboard, settings) and the `data-table-app` / `skeleton-table-app` components under the pattern gate, scrolling panes that stress reads as scrolling, and stress runs that triple app rows and card grids
- [ ] Follow-up — the web scaffolds' tint tokens (`success-tint` and the rest) are seeded dark and survive a later light `apply_preset`, as `accent-tint` did before Phase 31 slice D stopped seeding it; derive them from the applied palette instead
- [ ] 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 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
- [ ] Slice G — element states: hover, focus, pressed and disabled as a primitive property, drawn from state tokens
- [ ] Slice H — state checks: focus rings, active indicators, disabled renders and control boundaries checked analytically on every interactive primitive, without being drawn
Expand Down
Loading
Loading