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

#### 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`.
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, and `desktop-app-overlay` checks that it names something clickable. Colours come from `$bg-surface`, `$border`, `$text-primary` and `$text-secondary`, depth from `$elevation.overlay`.

| Type | Key props | What it is |
|---|---|---|
Expand All @@ -414,7 +414,7 @@ Six overlays draw screen states: an open menu, a comment popover, a confirm dial
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.
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. On a desktop-app canvas `desktop-app-overlay` warns on a second modal, a tooltip with children, a long table or a sideways scroller inside a modal, an overlay that leaves the viewport, and a popover or menu under the scrim of a modal or a drawer with `scrim: true` (popovers and menus stack below it); a second toast, a danger toast and an anchor that names nothing clickable are infos.

### `find_nodes`

Expand Down Expand Up @@ -926,6 +926,7 @@ Every result also carries a **`surface`** field: `{ type, device, source, rulesO
| `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). 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. |

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
2 changes: 1 addition & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -570,7 +570,7 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [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
- [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
- [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
- [ ] 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
- [ ] 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
Expand Down
11 changes: 9 additions & 2 deletions docs/GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,13 @@ Two terms the rules share. A **pane** is a frame that scrolls on its own (`overf
- **`desktop-app-row-rhythm`** (consistency), on detected tables. A header row (its content is text, plus icons and controls such as a select-all checkbox; a first row holding a control counts only when its text is styled apart from the next row's, since a row-select data row looks the same) more than 1px taller or shorter than the one-line body rows **warns**, as Carbon sets them equal. A body row more than 1px off its siblings is an **info**; rows with a title over a subtitle are compared only with each other. Detailed mode adds a cell whose left edge is more than 1px off its column as an **info**. Fast mode reads authored `height`s only, so rows sized by padding are judged in detailed mode.
- **`desktop-app-truncation`** (usability). A column header text with `textOverflow: "ellipsis"` **warns**: a header is never cut. A hand-built text with an ellipsis and no `title` is an **info**, since the full text must be reachable (primitives add their own `title`). Detailed mode adds: a `tabs` node whose every label is cut **warns** (tabs shrink to fit their tablist, so too many tabs in too little width leaves nothing readable), and an ellipsis that leaves fewer than four visible characters, on a text or a primitive's label, is an **info**.
- **`desktop-app-primary-count`** (structure, info). Two or more primary `button`s in one pane. Any variant but `secondary`, `ghost` or `destructive` renders filled with the accent, so it counts (no variant included); a disabled one doesn't. Primaries inside three or more same-shaped sibling frames (a grid of cards) are each card's own and don't count. A modal is a region of its own: its `actions` with `variant: "primary"` count there with any primary in its body (a `destructive` action is not a primary), never against the page behind it.
- **`desktop-app-overlay`** (usability). Overlays that cannot work as drawn.
- **Warnings**: a second `modal` on one canvas (one dialog at a time; design the other as its own variant); a `tooltip` with children (they never render); inside a modal, a detected table of more than ten body rows (a header row does not count) or a frame with `overflow: "auto"` that renders wider than the modal or scrolls sideways (a dialog is for a short decision, not for browsing data); an overlay whose box leaves the viewport; and each `popover` or `menu` on a canvas that holds a `modal`, or a `drawer` with `scrim: true`, because it renders under the scrim and looks disabled.
- **Infos**: a second `toast`; a `toast` with `tone: "danger"` (a transient toast is easy to miss, so put the error inline or in a banner); an `anchor` that names no node, or a node that is not a clickable primitive or control (a frame cannot be clicked). An overlay with no `anchor` raises nothing. Each finding is its own entry, so a second toast with `tone: "danger"` gets two infos.
- "Inside a modal" means the modal is the node's nearest overlay ancestor: a popover inside a modal is lifted out, so a table in it is the popover's, not the modal's (the popover itself still gets the scrim warning). "Wider than the modal" compares with the modal's outer width.
- The viewport is the root's numeric `width` and `height`, else the window's (1440×900). A modal wider than the viewport less 32px warns in both modes, since the render squeezes it to fit.
- Detailed mode checks every rendered overlay's box. Fast mode has no render, so it boxes only what your numbers decide: a `popover` or `menu` with numeric `x`, `y`, `width` and `height` (its width as the render resolves it: shrunk to the viewport, held by a `minWidth`, a menu never under 192), and a placed `modal` with numeric `x` and `y` at its own width (its height is its content, so only detailed mode judges its bottom edge). A `tooltip` and a `toast` size to their text and a `drawer` is pinned to the right edge, so only detailed mode sees them leave the window.
- A bare px `width` is squeezed to its parent by the render (`max-width: 100%`), so fast mode reads only a `minWidth`, or a `width` with a `maxWidth` that lets it stay wider (px, %, vw, or `"none"`), as wider than a modal.

Start an application screen from a desktop-app realisation, not a web page: see [Starting an application screen](#starting-an-application-screen-desktop-app-realisations).

Expand Down Expand Up @@ -127,11 +134,11 @@ Repeated desktop-app primitives count as component reuse. On an unthemed canvas,

An overlay is a **screen state**: the same screen with a menu open, a comment popover up, a confirm dialog or a toast. Design it as a state variant, not on the base screen: `canvas_add_variant({ canvasId, state: "confirm-delete" })` clones the screen, then insert the overlay into the clone. The recommended state names are `menu-open`, `comment-open`, `confirm-delete` and `toast`. Coverage lists every designed state in `coverage.states` and never demands an overlay state: an overlay is a design choice, not a data obligation.

Wherever you insert an overlay in the tree, it renders in **one overlay layer** after the content: a menu authored inside a sticky toolbar or a scrolling pane is never clipped by the pane and never sits under a sticky or fixed bar. So insert it where it belongs logically (a menu beside the button that opens it) and set `anchor` to that node's id (it is never rendered; the overlay rules of a later release read it). Four things follow:
Wherever you insert an overlay in the tree, it renders in **one overlay layer** after the content: a menu authored inside a sticky toolbar or a scrolling pane is never clipped by the pane and never sits under a sticky or fixed bar. So insert it where it belongs logically (a menu beside the button that opens it) and set `anchor` to that node's id (it is never rendered; `desktop-app-overlay` reads it and flags an anchor that names no node or a node that cannot be clicked). Four things follow:

- **`x` / `y` are root coordinates**: offsets from the root's top-left, not from the parent. To open a menu under a button, read the button's box with `snapshot_layout` and use its `x` and its `y` plus its height, whatever toolbar it sits in. The layer is the artboard box, so a centred modal and a bottom toast sit in the artboard.
- **Overlays nest freely**: an overlay inside another overlay (a tooltip in a modal, a submenu `menu` in a `menu`) is lifted too and stacks by its own kind, so a tooltip shows above a modal and a menu below it.
- **Layers are fixed by kind**, and there is no `zIndex` property: `popover` and `menu` 400, the scrim of a modal or a drawer 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. Everything in the layer sits above all content (`fixed` 10, `sticky` 5, a sheet 30). A menu inside a modal therefore renders under the modal.
- **Layers are fixed by kind**, and there is no `zIndex` property: `popover` and `menu` 400, the scrim of a modal or a drawer 500, `modal` and `drawer` 510, `toast` 600, `tooltip` 800. Everything in the layer sits above all content (`fixed` 10, `sticky` 5, a sheet 30). A menu or popover on a screen with a modal (or a drawer with a scrim) therefore renders under the scrim, and `desktop-app-overlay` warns: put its content in the dialog, or design it open on a variant without one. A variant clones everything on the screen, so a confirm dialog designed from a `menu-open` variant must delete the menu from its clone.
- **`snapshot_layout` lists every overlay as a child of the root**, at root coordinates, and a modal (or a drawer with a scrim) carries `scrim: { x, y, width, height }`. The detailed overlap check never counts an overlay as overlapping its siblings.

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.
Expand Down
Loading
Loading