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
18 changes: 10 additions & 8 deletions README.md

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -566,7 +566,8 @@ Run on its own viewer (2026-11-08), framesmith scored every page's usability 100
- [x] Slice A — the type: `desktop-app` with a 1440×900 window profile, a ruleset that switches off the type-scale ratio, the WCAG 2.5.8 spacing exception on the 24px floor (web and desktop-app; mobile keeps its 44px rule) and navigation lists that never read as tables (every type), evaluate and import results an agent can read (repeated findings fold, keeping every fix), type-aware generation with state and control-color tokens, and the baseline canvases committed as fixtures
- [x] Slice B — vocabulary: a 24px `button` with an accessible name, `link`, `text-input`, `nav-item`, `tabs`, `tree-row`, `menu-row`, `property-row` and `divider`, plus identity dots that never count as accents (moved here from slice A: it keys on `nav-item`)
- [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
- [ ] Slice D — panes: resolution for any number of types and six desktop-app realisations (workbench, list-detail, editor-inspector, browser, dashboard, settings) under the pattern gate
- [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
- [ ] 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
Expand Down
35 changes: 28 additions & 7 deletions docs/GUIDELINES.md

Large diffs are not rendered by default.

29 changes: 28 additions & 1 deletion docs/specs/PHASE-31-SPEC.md

Large diffs are not rendered by default.

15 changes: 14 additions & 1 deletion src/evaluate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2233,6 +2233,13 @@ function checkUsability(entries: NodeEntry[], rootWidth: number, touch?: { floor
if (node.type !== 'select') {
let scope = parentOf.get(node.id) ?? null;
let labeled = false;
// Phase 31 slice D — a property-row's label names its value. With a
// blank label only text inside the row itself can, never a sibling
// row's text one hop up.
if (scope?.type === 'property-row') {
labeled = (typeof scope.label === 'string' && scope.label.trim().length > 0) || hasText(scope);
scope = null;
}
for (let hop = 0; hop < 2 && scope && !labeled; hop++) {
labeled = hasText(scope);
scope = parentOf.get(scope.id) ?? null;
Expand Down Expand Up @@ -2367,6 +2374,12 @@ const COVERAGE_HINTS: Record<string, string> = {
loading: 'canvas_add_variant with state "loading", replace the data rows with the skeleton-table (or skeleton-card) scaffold.',
error: 'canvas_add_variant with state "error", show the form\'s validation-failure treatment (field messages + summary).',
};
/** Phase 31 slice D — on a desktop-app canvas the loading hint names the
* desktop-app skeleton (the web skeleton-table is refused there). */
const COVERAGE_HINTS_APP: Record<string, string> = {
...COVERAGE_HINTS,
loading: 'canvas_add_variant with state "loading", replace the data rows with the skeleton-table-app scaffold (data-table-app\'s loading state), or skeleton-card for cards.',
};

function checkCoverage(canvas: Canvas, designedStates: string[]): { result: CheckResult; report?: EvaluationResult['coverage'] } {
// A variant IS a designed state — demanding states of it would recurse.
Expand Down Expand Up @@ -2436,7 +2449,7 @@ function checkCoverage(canvas: Canvas, designedStates: string[]): { result: Chec
severity: 'warning',
nodeId: canvas.root.id,
message: `This screen has ${demanded.get(state)} but no "${state}" state variant is designed — the shipped UI will improvise it.`,
suggestion: COVERAGE_HINTS[state],
suggestion: (resolveSurface(canvas).type === 'desktop-app' ? COVERAGE_HINTS_APP : COVERAGE_HINTS)[state],
}));
return {
result: { score: Math.max(0, 100 - missing.length * 35), issues },
Expand Down
21 changes: 11 additions & 10 deletions src/index.ts

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion src/renderer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -602,7 +602,9 @@ function renderNode(node: SceneNode, rc: RenderCtx): string {

const styles = buildStyles(node, rc);
const styleAttr = styles ? ` style="${escapeStyleValue(styles)}"` : '';
const dataAttr = ` data-node-id="${node.id}"`;
// Phase 31 slice D (spec change S4) — a scrolling frame is marked like a
// sheet panel, so stress reads its vertical overflow as scrolling.
const dataAttr = ` data-node-id="${node.id}"${node.overflow === 'auto' ? ' data-fs-scroll' : ''}`;

if (node.type === 'text') {
const title = typeof node.title === 'string' && node.title.trim() ? ` title="${escapeAttr(node.title.trim())}"` : '';
Expand Down
50 changes: 38 additions & 12 deletions src/stress.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import type { SceneNode } from './types.js';
import type { LayoutRect } from './screenshot.js';
import type { SurfaceType } from './surfaces.js';
import { extractInventory, isDataLike } from './drift.js';
import { shapeHash } from './shape-hash.js';

export type PerturbationName = 'long-text' | 'i18n' | 'big-numbers' | 'empty' | 'many';
export const PERTURBATION_NAMES: PerturbationName[] = ['long-text', 'i18n', 'big-numbers', 'empty', 'many'];
Expand Down Expand Up @@ -98,18 +99,32 @@ function walkTexts(root: SceneNode, visit: (slot: TextSlot) => void): void {
root.children?.forEach((c) => walkTexts(c, visit));
}

/** Runs of two or more consecutive sibling `list-row`s — a list, for the
* empty and many perturbations. Lives here, not in the drift inventory, which
* coverage, typography and drift share and which must not change. */
function listRuns(root: SceneNode): Array<{ container: SceneNode; start: number; length: number }> {
/** Phase 31 slice D (spec change S5) — the desktop-app rows `many` and
* `empty` also act on. */
const DESKTOP_ROW_TYPES = new Set(['nav-item', 'tree-row', 'menu-row', 'property-row']);
const CARD_GRID_MIN = 3;

/** Runs of two or more sibling rows of one type, for the empty and many
* perturbations: `list-row` on every type, plus the desktop-app rows on a
* desktop-app canvas, where the children of a grid holding three or more
* same-shaped children (a card grid) are a run too. Lives here, not in the
* drift inventory, which coverage, typography and drift share and which must
* not change. */
function listRuns(root: SceneNode, desktop = false): Array<{ container: SceneNode; start: number; length: number }> {
const runs: Array<{ container: SceneNode; start: number; length: number }> = [];
const isRow = (n: SceneNode): boolean => n.type === 'list-row' || (desktop && DESKTOP_ROW_TYPES.has(n.type));
(function walk(n: SceneNode) {
const kids = n.children ?? [];
for (let i = 0; i < kids.length;) {
let j = i;
while (j < kids.length && kids[j].type === 'list-row') j++;
if (j - i >= 2) runs.push({ container: n, start: i, length: j - i });
i = j > i ? j : i + 1;
const cardGrid = desktop && n.layout === 'grid' && kids.length >= CARD_GRID_MIN
&& kids.every((k) => shapeHash(k, 3, { names: false }) === shapeHash(kids[0], 3, { names: false }));
if (cardGrid) runs.push({ container: n, start: 0, length: kids.length });
else {
for (let i = 0; i < kids.length;) {
let j = i;
while (j < kids.length && isRow(kids[j]) && kids[j].type === kids[i].type) j++;
if (j - i >= 2) runs.push({ container: n, start: i, length: j - i });
i = j > i ? j : i + 1;
}
}
kids.forEach(walk);
})(root);
Expand Down Expand Up @@ -139,6 +154,14 @@ function tableRows(container: SceneNode): SceneNode[] {
return (container.children ?? []).filter((c) => c.type === 'frame' && (c.children?.length ?? 0) >= 2);
}

/** A copy that is not the current row (Phase 31 slice D: `many` on a run of
* nav-items must not add a second active one). */
function withoutActive(node: SceneNode): SceneNode {
if (node.active === undefined) return node;
const { active: _active, ...rest } = node;
return rest;
}

function cloneWithSuffix(node: SceneNode, suffix: string): SceneNode {
const clone: SceneNode = { ...node, id: `${node.id}${suffix}` };
if (node.children) clone.children = node.children.map((c) => cloneWithSuffix(c, suffix));
Expand Down Expand Up @@ -199,12 +222,15 @@ export function applyPerturbation(name: PerturbationName, root: SceneNode, opts:
}
touched.push(container.id);
}
// Runs of list-rows, last run first so earlier indices stay valid.
for (const run of listRuns(clone).reverse()) {
// Runs of rows (list-rows; desktop-app rows and card grids on desktop-app),
// last run first so earlier indices stay valid. Nested runs are fine: a
// container's own indices only move when its own run is edited.
for (const run of listRuns(clone, opts.type === 'desktop-app').reverse()) {
const kids = run.container.children!;
const rows = kids.slice(run.start, run.start + run.length);
if (name === 'empty') kids.splice(run.start, run.length);
else kids.splice(run.start + run.length, 0, ...[1, 2].flatMap((i) => rows.map((r) => cloneWithSuffix(r, `-x${i}`))));
// A tripled list still has one current place: copies drop `active`.
else kids.splice(run.start + run.length, 0, ...[1, 2].flatMap((i) => rows.map((r) => withoutActive(cloneWithSuffix(r, `-x${i}`)))));
touch(run.container.id);
}
return { root: clone, touched };
Expand Down
57 changes: 57 additions & 0 deletions src/structure-tokens.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
// Phase 31 slice D — the token vocabulary every scaffold references, shared by
// the web/mobile scaffolds (structures.ts) and the desktop-app realisations
// (structures-desktop.ts).

/** Standard color tokens these scaffolds reference (the preset vocabulary). */
export const COLOR = {
bgPrimary: '$bg-primary',
bgSurface: '$bg-surface',
bgElevated: '$bg-elevated',
textPrimary: '$text-primary',
textSecondary: '$text-secondary',
accent: '$accent',
border: '$border',
} as const;

/** Phase 27 slice B — density comes from tokens, not literals. Scaffolds
* reference the space/radius/elevation vocabulary generate_design_system
* writes; applyStructure seeds neutral defaults (the pre-27 literal values)
* for anything not already resolvable, so unthemed canvases render exactly
* as before and a personality re-densifies every stamp. */
export const SPACE = {
xxs: '$space-3xs', // 2
xs2: '$space-2xs', // 4
xs: '$space-xs', // 8
sm: '$space-sm', // 12
md: '$space-md', // 16
lg: '$space-lg', // 24
xl: '$space-xl', // 32
xl2: '$space-2xl', // 48
} as const;
export const RADIUS = {
sm: '$radius-sm', // 8
md: '$radius-md', // 12
lg: '$radius-lg', // 16
} as const;
export const ELEV = {
flat: '$elevation.flat',
raised: '$elevation.raised',
} as const;
export const TYPE = {
display: '$display', // hero headlines — the display face at full size
title: '$title', // page/screen titles, one step below display
heading: '$heading', // section heads
textLg: '$text-lg', // card titles, subheads — the step above body
textSm: '$text-sm', // small body text — untracked (nav items, prose, meta)
body: '$body', // prose and item text
label: '$label', // control, CTA, breadcrumb and table-header text
caption: '$caption', // metadata, timestamps, eyebrows
} as const;
/** Phase 28 — the tint pair: tint as the FILL, base color as the INK. */
export const TINT = {
accent: { bg: '$accent-tint', ink: COLOR.accent },
success: { bg: '$success-tint', ink: '$success' },
warning: { bg: '$warning-tint', ink: '$warning' },
danger: { bg: '$danger-tint', ink: '$danger' },
neutral: { bg: '$neutral-tint', ink: COLOR.textSecondary },
} as const;
Loading
Loading