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
27 changes: 22 additions & 5 deletions README.md

Large diffs are not rendered by default.

6 changes: 4 additions & 2 deletions VISION.md
Original file line number Diff line number Diff line change
Expand Up @@ -555,15 +555,17 @@ 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.

_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)._

### Phase 31 — The desktop-app surface (v2.5)

Run on its own viewer (2026-11-08), framesmith scored every page's usability 100 with zero findings: the viewer has a 17px Back link and 21 click targets that are plain spans, but the web hit-target rule only measures form controls. Meanwhile page rules misfired on the app: the sidebar project list read as a data table, the dense 13/14px type steps failed the scale ratio, and the projects' identity dots counted as competing accents. framesmith judges an application as if it were a marketing page, and has no words for what makes it an application. This phase adds a third type, `desktop-app` (a tool you work in, in a browser or a native window), with the vocabulary, rules, layouts, overlays and element states an app needs. Acceptance is literal: the viewer itself rebuilt as canvases, CLEAN, with every click target a primitive.

- [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
- [ ] 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`)
- [ ] 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, one primary per region, and the declaration matching the window
- [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`)
- [ ] 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
- [ ] 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
Expand Down
30 changes: 24 additions & 6 deletions docs/GUIDELINES.md

Large diffs are not rendered by default.

29 changes: 25 additions & 4 deletions docs/specs/PHASE-31-SPEC.md

Large diffs are not rendered by default.

48 changes: 43 additions & 5 deletions src/desktop-app-rules.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,17 @@

import type { EvaluationIssue } from './evaluate.js';
import type { SceneNode } from './types.js';
import { DESKTOP_APP_PRIMITIVES } from './primitives.js';
import { windowProfile, DEFAULT_WINDOW, WINDOW_PROFILES, type SurfaceDeclaration } from './surfaces.js';

/** `desktop-app-artboard` (base ruleset, every type). Slice A: a desktop-app
* canvas narrower than its window's minimum warns. The clauses about
* desktop-app and overlay primitives on other types land with those
* primitives. */
/** `desktop-app-artboard` (base ruleset, every type). A desktop-app canvas
* narrower than its window's minimum warns (slice A). A canvas that holds a
* desktop-app primitive (nav-item, tabs, tree-row, menu-row, property-row)
* must say it is one (slice B): undeclared warns, an explicit `web` gets an
* info, an explicit `mobile` warns. The overlay clause lands with the
* overlay primitives (slice E). Reads the tree with instances expanded. */
export function checkDesktopArtboard(root: SceneNode, surface: SurfaceDeclaration): EvaluationIssue[] {
if (surface.type !== 'desktop-app') return [];
if (surface.type !== 'desktop-app') return checkAppPrimitivesDeclared(root, surface);
const profile = windowProfile(surface.device ?? DEFAULT_WINDOW) ?? WINDOW_PROFILES[DEFAULT_WINDOW];
const width = typeof root.width === 'number' ? root.width : profile.width;
if (width >= profile.minWidth) return [];
Expand All @@ -24,3 +27,38 @@ export function checkDesktopArtboard(root: SceneNode, surface: SurfaceDeclaratio
suggestion: `Resize it: U("document", { width: ${profile.width}, height: ${profile.height} }) — or canvas_set_type({ type: "mobile" }) / ({ type: "web" }) if it is a phone screen or a narrow web page.`,
}];
}

function firstAppPrimitive(root: SceneNode): SceneNode | undefined {
if (DESKTOP_APP_PRIMITIVES.has(root.type)) return root;
for (const c of root.children ?? []) {
const hit = firstAppPrimitive(c);
if (hit) return hit;
}
return undefined;
}

function checkAppPrimitivesDeclared(root: SceneNode, surface: SurfaceDeclaration): EvaluationIssue[] {
const hit = firstAppPrimitive(root);
if (!hit) return [];
const what = `a ${hit.type}${hit.name ? ` ("${hit.name}")` : ''}`;
const base = { category: 'structure', rule: 'desktop-app-artboard', nodeId: hit.id, nodeName: hit.name } as const;
if (surface.source === 'default') {
return [{
...base, severity: 'warning',
message: `This canvas holds ${what}, a desktop-app primitive, but never declared its type, so it is judged as a web page.`,
suggestion: 'Declare it: canvas_set_type({ type: "desktop-app" }) for an application screen (a tool you work in), or canvas_set_type({ type: "web" }) if it really is a page you read.',
}];
}
if (surface.type === 'mobile') {
return [{
...base, severity: 'warning',
message: `This canvas is declared mobile but holds ${what}, a desktop-app primitive built for pointer input and dense windows.`,
suggestion: 'Use the mobile vocabulary on a phone (list-row, tab-bar, nav-bar, button), or canvas_set_type({ type: "desktop-app" }) if this is an application window.',
}];
}
return [{
...base, severity: 'info',
message: `This canvas is declared web but holds ${what}: an application screen should declare desktop-app so the desktop-app ruleset judges it.`,
suggestion: 'canvas_set_type({ type: "desktop-app" }) if this is a tool you work in.',
}];
}
53 changes: 46 additions & 7 deletions src/evaluate.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import type { Canvas, SceneNode, DesignVariables } from './types.js';
import type { Canvas, SceneNode, DesignVariables, TabItem } from './types.js';
import { resolveVariables } from './variables.js';
import { getCanvasTokens } from './workspaces.js';
import { renderToHtml, resolveInstance } from './renderer.js';
Expand All @@ -9,7 +9,7 @@ import { getIconSvg, parseIconRef } from './icons.js';
import { storedGenre } from './genre.js';
import { relaxedByPreset, relaxedByGenre, canonicalGenre, genreRulesets, activeRulesets, composeRulesets, resolveSurface, deviceProfile, DEVICE_PROFILES, DEFAULT_DEVICE, MOBILE_RULES, type SurfaceType } from './surfaces.js';
import { checkArtboard, checkHandbuiltTargets, checkOneColumn, checkSafeAreaDetailed, checkSafeAreaFast, checkTabBars, checkTypeFloor, paddingSides, type MobileContext } from './mobile-rules.js';
import { CHROME_EDGE, FAB_SIZE, NAV_ACTION, TAPPABLE_PRIMITIVES, buttonBox, effectivePosition, listRowMinHeight, navActions, pinsBottom, tabItemBox, tabItems } from './primitives.js';
import { CHROME_EDGE, FAB_SIZE, NAV_ACTION, TAPPABLE_PRIMITIVES, CLICKABLE_PRIMITIVES, CONTROL_OWNERS, LIST_ROW_HEIGHT, MENU_ROW_HEIGHT, NAV_ITEM_HEIGHT, PROPERTY_ROW_HEIGHT, buttonBox, desktopTargets, effectivePosition, listRowMinHeight, navActions, pinsBottom, tabItemBox, tabItems } from './primitives.js';

// --- Types ---

Expand Down Expand Up @@ -803,10 +803,11 @@ function checkStructure(entries: NodeEntry[], canvas: Canvas): CheckResult {
issues.push(...iconFindings);

// Component reuse. Phase 30 slice D — a repeated primitive (list rows,
// buttons, tab bars) is reuse too: the primitive is the component.
// buttons, tab bars) is reuse too: the primitive is the component. Phase 31
// slice B adds the desktop-app vocabulary.
const primitiveCounts = new Map<string, number>();
for (const e of entries) {
if (e.node.type === 'button' || e.node.type === 'list-row' || e.node.type === 'tab-bar') {
if (REUSE_PRIMITIVES.has(e.node.type)) {
primitiveCounts.set(e.node.type, (primitiveCounts.get(e.node.type) ?? 0) + 1);
}
}
Expand Down Expand Up @@ -834,11 +835,13 @@ function iconSlots(root: SceneNode): Array<{ node: SceneNode; path: string; ref:
(function walk(n: SceneNode) {
if (n.type === 'icon') add(n, 'icon', n.icon, true, true);
else if (n.type === 'button') add(n, 'icon', n.icon, true, false);
// Phase 31 slice B — the desktop-app primitives draw their `icon` too.
else if (n.type === 'link' || n.type === 'nav-item' || n.type === 'tree-row' || n.type === 'menu-row' || n.type === 'text-input') add(n, 'icon', n.icon, true, false);
else if (n.type === 'list-row' || n.type === 'nav-bar') {
add(n, 'leading.icon', n.leading?.icon, false, false);
if (n.type === 'nav-bar' && Array.isArray(n.trailing)) n.trailing.slice(0, 2).forEach((a, i) => add(n, `trailing[${i}].icon`, a?.icon, false, false));
} else if (n.type === 'tab-bar') {
(Array.isArray(n.items) ? n.items : []).forEach((it, i) => add(n, `items[${i}].icon`, it?.icon, false, true));
(Array.isArray(n.items) ? n.items as Array<TabItem | null> : []).forEach((it, i) => add(n, `items[${i}].icon`, it?.icon, false, true));
if (n.variant === 'fab') add(n, 'fab.icon', n.fab?.icon, false, false);
}
n.children?.forEach(walk);
Expand All @@ -848,7 +851,11 @@ function iconSlots(root: SceneNode): Array<{ node: SceneNode; path: string; ref:

/** Phase 30 slice D — the mobile primitives' copy and enum props: words and
* variant names, never style values, so the token census skips them. */
const PRIMITIVE_COPY_PROPS = new Set(['title', 'subtitle', 'label', 'time', 'variant', 'size', 'detent', 'appearance', 'iconPosition']);
const PRIMITIVE_COPY_PROPS = new Set([
'title', 'subtitle', 'label', 'time', 'variant', 'size', 'detent', 'appearance', 'iconPosition',
// Phase 31 slice B — the desktop-app primitives' copy and enums.
'placeholder', 'value', 'shortcut', 'error', 'ariaLabel', 'count', 'orientation',
]);

/** Spellings worth trying for an icon name that didn't resolve: Material
* Symbols names multi-word icons with `_` (chevron_right), Lucide with `-`
Expand Down Expand Up @@ -1798,6 +1805,9 @@ function tellAccentConsistency(ctx: ClicheCtx): EvaluationIssue[] {
n.type === 'ellipse' || n.type === 'rectangle' || !!n.icon ||
(typeof n.width === 'number' && n.width < 600);

// Phase 31 FR-A6 — a nav-item's `dotColor` is an identity dot (a project,
// a label), never an accent: it is deliberately not one of the props read
// below. The same value used as a fill or colour elsewhere still counts.
for (const { node } of ctx.entries) {
if (node.id === rootId) continue; // page background isn't an accent
const raw = ctx.rawById.get(node.id);
Expand Down Expand Up @@ -1897,6 +1907,8 @@ function generateSummary(overall: number, categories: CategoryScore[], issues: E
// tree so padding/dimensions are numbers.

const CONTROL_TYPES = new Set(['toggle', 'checkbox', 'radio', 'select']);
/** Primitives whose repetition counts as component reuse (structure advisory). */
const REUSE_PRIMITIVES = new Set(['button', 'list-row', 'tab-bar', 'link', 'text-input', 'nav-item', 'tabs', 'tree-row', 'menu-row', 'property-row']);
/** Renderer defaults (controlSize + select's padding-derived height). */
const CONTROL_DEFAULT_SIZE: Record<string, { w: number; h: number }> = {
toggle: { w: 44, h: 24 },
Expand Down Expand Up @@ -2006,13 +2018,31 @@ export function pointerTargets(entries: NodeEntry[], rootWidth: number): Pointer
for (const ch of n.children ?? []) c += countControls(ch);
return c;
};
const countTargets = (n: SceneNode): number => {
let c = CONTROL_TYPES.has(n.type) || CLICKABLE_PRIMITIVES.has(n.type) ? 1 : 0;
for (const ch of n.children ?? []) c += countTargets(ch);
return c;
};
const targets: PointerTarget[] = [];
for (const { node } of entries) {
const disabled = node.disabled === true;
if (CONTROL_TYPES.has(node.type)) {
const def = CONTROL_DEFAULT_SIZE[node.type];
let w = typeof node.width === 'number' ? node.width : def.w;
let h = typeof node.height === 'number' ? node.height : def.h;
// Phase 31 FR-A4 — a control that is the only target directly inside a
// row primitive (property-row, nav-item, menu-row, list-row) owns that
// row's box: the row is the target. Its height is the row's; its width
// the row's when known, else the row spans its container. A link,
// text-input or button beside it shares the row; the row itself never
// counts (a nav-item is clickable, but it is the owner, not a sibling).
const owner = parentOf.get(node.id) ?? null;
const siblingsAndSelf = owner ? (owner.children ?? []).reduce((c, ch) => c + countTargets(ch), 0) : 0;
if (owner && CONTROL_OWNERS.has(owner.type) && siblingsAndSelf === 1 && Math.min(w, h) < 24) {
const rowH = Math.max(typeof owner.height === 'number' ? owner.height : 0, OWNER_HEIGHT[owner.type] ?? 0);
w = typeof owner.width === 'number' ? owner.width : Infinity;
h = Math.max(h, rowH);
}
let cur = parentOf.get(node.id) ?? null;
for (let hop = 0; hop < 2 && cur && Math.min(w, h) < 24; hop++) {
if (countControls(cur) === 1) {
Expand All @@ -2027,11 +2057,20 @@ export function pointerTargets(entries: NodeEntry[], rootWidth: number): Pointer
for (const t of primitiveTargets(node, parentOf, rootWidth)) {
targets.push({ node, what: t.what, w: t.w ?? Infinity, h: t.h, disabled });
}
} else if (CLICKABLE_PRIMITIVES.has(node.type)) {
// Phase 31 slice B — the desktop-app vocabulary, each by its own box
// (a tabs node has one target per item, sharing the node's id).
for (const t of desktopTargets(node)) {
targets.push({ node, what: t.what, w: t.w ?? Infinity, h: t.h, disabled: t.disabled });
}
}
}
return targets;
}

/** The heights the row primitives that own a sole control render at. */
const OWNER_HEIGHT: Record<string, number> = { 'property-row': PROPERTY_ROW_HEIGHT, 'nav-item': NAV_ITEM_HEIGHT, 'menu-row': MENU_ROW_HEIGHT, 'list-row': LIST_ROW_HEIGHT };

/** The live targets still below 24px after the padded-row step — the ones
* the circle test must place; [] means no detailed render is needed. */
export function undersizedTargets(targets: PointerTarget[]): PointerTarget[] {
Expand Down Expand Up @@ -2528,7 +2567,7 @@ export async function evaluateCanvas(
if (activeCategories.includes('structure')) {
results.set('structure', withRuleIssues(checkStructure(rawEntries, canvas), [
...(ruleOn.has('mobile-artboard') ? reportOnInstances(checkArtboard(mobile, declared), owners) : []),
...(ruleOn.has('desktop-app-artboard') ? checkDesktopArtboard(resolvedRoot, declared) : []),
...(ruleOn.has('desktop-app-artboard') ? reportOnInstances(checkDesktopArtboard(mobileRoot, declared), owners) : []),
]));
}
if (activeCategories.includes('consistency')) {
Expand Down
Loading
Loading