ui-design-workbench-cli 0.5.0__py3-none-any.whl

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/platform-profiles.json

@@ -0,0 +1,84 @@
+{
+  "version": 2,
+  "profiles": {
+    "material3": {
+      "family": "android",
+      "label": "Android · Material 3",
+      "standardRefPrefixes": ["material3.", "project."],
+      "minimumTarget": {"width": 48, "height": 48},
+      "requiredInteractionStates": ["default", "pressed", "focused", "disabled"],
+      "requirements": ["system-back", "edge-to-edge-insets", "dynamic-color-aware", "scalable-type"]
+    },
+    "apple-hig": {
+      "family": "ios",
+      "label": "iOS · Apple HIG",
+      "standardRefPrefixes": ["apple.", "project."],
+      "minimumTarget": {"width": 44, "height": 44},
+      "requiredInteractionStates": ["default", "highlighted", "focused", "disabled"],
+      "requirements": ["safe-area-insets", "dynamic-type", "system-back", "reduced-motion"]
+    },
+    "web-platform": {
+      "family": "web",
+      "label": "Web · semantic HTML, WCAG 2.2 AA, APG",
+      "standardRefPrefixes": ["html.", "aria.", "project."],
+      "minimumTarget": {"width": 24, "height": 24},
+      "recommendedTouchTarget": {"width": 44, "height": 44},
+      "requiredInteractionStates": ["default", "hover", "focus-visible", "active", "disabled"],
+      "requirements": ["keyboard-complete", "focus-visible", "semantic-landmarks", "reflow-320-css-px"]
+    },
+    "windows-fluent": {
+      "family": "windows",
+      "label": "Windows · Fluent, WinUI and Windows accessibility",
+      "standardRefPrefixes": ["windows.", "winui.", "project."],
+      "minimumTarget": {"width": 40, "height": 40},
+      "requiredInteractionStates": ["default", "pointer-over", "pressed", "focused", "disabled"],
+      "requirements": ["keyboard-complete", "visible-focus", "narrator-uia", "text-scaling", "high-contrast", "resizable-window", "multi-input"],
+      "referenceUrls": [
+        "https://learn.microsoft.com/windows/apps/design/",
+        "https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting",
+        "https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions",
+        "https://learn.microsoft.com/windows/apps/design/accessibility/"
+      ]
+    },
+    "macos-hig": {
+      "family": "macos",
+      "label": "macOS · Apple HIG",
+      "standardRefPrefixes": ["macos.", "apple.", "project."],
+      "minimumTarget": {"width": 28, "height": 28},
+      "documentedMinimumTarget": {"width": 20, "height": 20},
+      "requiredInteractionStates": ["default", "pressed", "focused", "disabled", "inactive-window"],
+      "requirements": ["menu-bar-commands", "keyboard-shortcuts", "full-keyboard-access", "voiceover", "resizable-window", "active-inactive-window", "reduced-motion", "increase-contrast"],
+      "referenceUrls": [
+        "https://developer.apple.com/design/human-interface-guidelines/designing-for-macos/",
+        "https://developer.apple.com/design/human-interface-guidelines/accessibility",
+        "https://developer.apple.com/design/human-interface-guidelines/focus-and-selection/"
+      ]
+    },
+    "flutter-adaptive": {
+      "family": "flutter",
+      "label": "Flutter · Material, Cupertino and adaptive layout",
+      "standardRefPrefixes": ["flutter.", "material3.", "cupertino.", "project."],
+      "minimumTarget": {"width": 48, "height": 48},
+      "requiredInteractionStates": ["default", "hovered", "focused", "pressed", "disabled"],
+      "requirements": ["adaptive-layout", "platform-semantics", "scalable-text", "safe-area-insets", "keyboard-complete", "reduced-motion"],
+      "referenceUrls": [
+        "https://docs.flutter.dev/ui/adaptive-responsive",
+        "https://docs.flutter.dev/ui/accessibility-and-internationalization/accessibility"
+      ]
+    }
+  },
+  "frameworkAdapters": {
+    "android-compose": {"families": ["android"], "profiles": ["material3"]},
+    "android-views": {"families": ["android"], "profiles": ["material3"]},
+    "swiftui": {"families": ["ios"], "profiles": ["apple-hig"]},
+    "uikit": {"families": ["ios"], "profiles": ["apple-hig"]},
+    "web": {"families": ["web"], "profiles": ["web-platform"]},
+    "react-web": {"families": ["web"], "profiles": ["web-platform"]},
+    "windows-winui": {"families": ["windows"], "profiles": ["windows-fluent"]},
+    "windows-wpf": {"families": ["windows"], "profiles": ["windows-fluent"]},
+    "windows-xaml": {"families": ["windows"], "profiles": ["windows-fluent"]},
+    "swiftui-macos": {"families": ["macos"], "profiles": ["macos-hig"]},
+    "appkit": {"families": ["macos"], "profiles": ["macos-hig"]},
+    "flutter": {"families": ["flutter"], "profiles": ["flutter-adaptive"]}
+  }
+}

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/platform-standards.md

@@ -0,0 +1,131 @@
+# Platform standards profile
+
+Last verified: 2026-08-27. Use official sources when a decision depends on newer OS behavior, an experimental component, or a library version. Never upgrade project dependencies merely because newer guidance exists.
+
+The executable profile catalog is [platform-profiles.json](platform-profiles.json). Keep profile IDs, standard-reference prefixes, target sizes, and framework adapters there; prose in this file explains judgment and never overrides a stricter machine gate. Validate every final IR with `scripts/validate_platform_profiles.py` or the combined coverage gate described in [quality-automation.md](quality-automation.md).
+
+## Selection order
+
+1. Explicit product requirements and user-approved brand constraints.
+2. The repository's installed UI framework, design system, tokens, and established interaction patterns.
+3. The target platform's official components and navigation conventions.
+4. Accessibility and adaptive-layout requirements.
+5. A custom solution only when the previous layers cannot satisfy the task; record a `design.decisions` entry explaining why.
+
+Reconstruction preserves current behavior and reports standards gaps instead of silently redesigning. Generation and redesign use the platform baseline unless the existing project system intentionally overrides it.
+
+## Android mobile and tablet
+
+Default profile ID: `material3`.
+
+- For new Android UI, default to Material 3 components and theming. In Compose, derive color, typography, and shape from `MaterialTheme`; in Views, stay with the project's installed Material Components stack rather than introducing Compose without permission.
+- Prefer the installed stable APIs. Use Material 3 Expressive or experimental APIs only when already enabled or explicitly approved.
+- Map top-level and hierarchical navigation to Material/Android patterns already used by the project. Do not import iOS tab, sheet, or toolbar behavior merely for visual novelty.
+- Use adaptive layouts based on window size, not a hard-coded phone model. Consider navigation bar/rail and list-detail/supporting-pane patterns where the information architecture warrants them.
+- Interactive touch targets should be at least 48×48 dp, even if the visible icon is smaller.
+- Support font scaling, screen readers, keyboard, mouse, stylus, RTL, dark theme, system insets, loading/error/empty states, and back behavior.
+
+Official sources:
+
+- [Material Design 3 in Compose](https://developer.android.com/develop/ui/compose/designsystems/material3)
+- [Adaptive Android guidance](https://developer.android.com/develop/adaptive-apps/guides/adaptive-dos-and-donts)
+- [Android accessibility and 48 dp targets](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
+
+## iOS
+
+Default profile ID: `apple-hig`.
+
+- Prefer native SwiftUI/UIKit controls, navigation, sheets, alerts, menus, pickers, toolbars, tab bars, system typography, semantic colors, materials, and standard gestures.
+- A tab bar navigates between top-level areas; actions belong in a toolbar or content. Preserve navigation state within tabs.
+- Respect safe areas, system margins, Dynamic Type, localization expansion, RTL, orientation, and input methods beyond touch.
+- Use a 44×44 pt default control target for iOS. Do not shrink it merely to make a dense layout fit.
+- Do not simulate Material ripples, FABs, Android back behavior, or Android component geometry unless the product explicitly chooses a cross-platform custom system.
+- Use current system materials, including newer visual treatments, only when the deployment target and existing implementation support them. Do not draw a speculative imitation in HTML.
+
+Official sources:
+
+- [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines)
+- [Apple layout and safe-area guidance](https://developer.apple.com/design/human-interface-guidelines/layout)
+- [Apple accessibility guidance and control sizes](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+- [Apple tab bar guidance](https://developer.apple.com/design/human-interface-guidelines/tab-bars)
+- [Apple toolbar guidance](https://developer.apple.com/design/human-interface-guidelines/toolbars)
+
+## macOS
+
+Default profile ID: `macos-hig`.
+
+- Prefer native SwiftUI/AppKit windows, split views, sidebars, inspectors, tables, toolbars, menus, sheets, popovers, search fields, system typography, semantic colors, and standard command placement.
+- Treat the menu bar and keyboard shortcuts as first-class command surfaces. Important commands remain discoverable in menus even when a toolbar or contextual shortcut also exposes them.
+- Support resizable, movable, minimizable, full-screen, multiwindow, active, and inactive window states where the product architecture permits them. Do not freeze a desktop workflow into a phone-sized fixed canvas.
+- Design for precise pointer input, keyboard-only workflows, Full Keyboard Access, VoiceOver, drag and drop, contextual menus, and focus rings. Hover may supplement meaning but cannot be the only way to expose a required action.
+- Use 28×28 pt as the default control target for generated and redesigned macOS UI. The documented 20×20 pt minimum requires a recorded exception, adequate spacing, low error consequence, and verification with the actual control/input context.
+- Preserve platform conventions for destructive commands, default/cancel actions, document state, app/window lifecycle, and active/inactive emphasis. Do not copy iOS tab bars, oversized touch geometry, or mobile-only sheets into a desktop Mac workflow without an explicit reason.
+- Respect Reduce Motion, Increase Contrast, Differentiate Without Color, text enlargement, localization expansion, RTL where applicable, and multiple display scales.
+
+Official sources:
+
+- [Designing for macOS](https://developer.apple.com/design/human-interface-guidelines/designing-for-macos/)
+- [Apple accessibility guidance and macOS control sizes](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+- [Apple focus and selection guidance](https://developer.apple.com/design/human-interface-guidelines/focus-and-selection/)
+- [Apple menu guidance](https://developer.apple.com/design/human-interface-guidelines/menus)
+- [Apple toolbar guidance](https://developer.apple.com/design/human-interface-guidelines/toolbars)
+
+## Web
+
+Default profile ID: `web-platform`.
+
+- Start with semantic HTML and native elements. Use ARIA only when native semantics cannot express the required widget.
+- Target WCAG 2.2 AA unless the repository or user requires a stronger level. Preserve visible focus, logical tab order, keyboard operation, names/roles/values, contrast, zoom/reflow, error identification, and reduced motion.
+- Custom widgets follow the corresponding WAI-ARIA Authoring Practices pattern, including its keyboard model and focus management. APG is informative guidance, while WCAG and ARIA are normative standards.
+- Pointer targets must meet WCAG 2.2 AA target sizing or a documented exception. The baseline audit uses 24×24 CSS px; prefer larger targets for primary touch interfaces when product density permits.
+- Use responsive content-driven breakpoints and appropriate maximum content widths. Do not imitate an Android or iOS screen when the target is a desktop web application.
+- Preserve browser expectations for links, forms, history, selection, copy/paste, autofill, and keyboard shortcuts.
+
+Official sources:
+
+- [WCAG 2.2 Recommendation](https://www.w3.org/TR/WCAG22/)
+- [WCAG 2.2 target-size guidance](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html)
+- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
+- [APG keyboard-interface guidance](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/)
+
+## Windows
+
+Default profile ID: `windows-fluent`.
+
+- Prefer the UI stack already installed by the repository: normally WinUI 3 with Windows App SDK for a new native app, or the existing WPF/Win32 stack for an established product. Do not migrate frameworks merely to satisfy the profile.
+- Use Fluent/Windows control and navigation conventions, system typography, theme resources, standard title-bar/window behavior, dialogs, teaching tips, command bars, menus, and NavigationView patterns when they match the task.
+- Support mouse, touch, pen, keyboard, gamepad/remote where relevant, Narrator, UI Automation, access keys, keyboard accelerators, visible focus, high contrast, text scaling, display scaling, and reduced motion.
+- Use 40×40 effective pixels as the default touch target for generated and redesigned interactive elements. Pointer-dense UI may use a smaller visible control only when the hit target, spacing, frequency, and error consequence remain safe and the exception is recorded.
+- Treat window resizing, snap layouts, multiple displays, DPI changes, compact/expanded layouts, activation/deactivation, and title-bar insets as normal states. Recompute custom title-bar interactive regions after size, scale, or presenter changes.
+- Keep command placement and shortcuts consistent with Windows expectations. Do not import macOS traffic-light controls, iOS navigation stacks, or Android FAB/ripple behavior without an intentional cross-platform-system decision.
+- Prefer standard WinUI text and controls so Windows text-size and accessibility settings work without custom reimplementation. Validate wrapping, clipping, contrast, and geometry at supported display and text scales.
+
+Official sources:
+
+- [Windows app design guidance](https://learn.microsoft.com/windows/apps/design/)
+- [Windows touch target guidance](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
+- [Windows keyboard interactions](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
+- [Windows focus navigation](https://learn.microsoft.com/windows/apps/develop/input/focus-navigation)
+- [Windows accessibility guidance](https://learn.microsoft.com/windows/apps/design/accessibility/)
+- [Windows text scaling](https://learn.microsoft.com/windows/apps/develop/input/text-scaling)
+- [Windows title bar guidance](https://learn.microsoft.com/windows/apps/develop/title-bar)
+
+## Flutter
+
+Default profile ID: `flutter-adaptive`.
+
+- Preserve the project's existing Material, Cupertino, or custom widget system; do not replace it merely to make the HTML projection easier.
+- Resolve adaptive behavior, safe areas, scalable text, localization, platform semantics, keyboard/focus behavior, and responsive breakpoints explicitly.
+- Treat custom painters, runtime layout delegates, platform channels, and builder output without deterministic fixtures as unsupported evidence gaps.
+- The HTML output is a structural projection. Native Flutter golden/device evidence is required before calling it visually verified.
+
+## IR evidence
+
+For generated or redesigned interactive nodes, use:
+
+- `standardRef`: one reference such as `material3.Button`, `apple.Button`, `macos.Toolbar`, `windows.NavigationView`, `flutter.Text`, `html.button`, or `aria.dialog`;
+- `standardRefs`: per-platform references for shared nodes;
+- `decisionId`: an ID from `design.decisions` when a custom component is necessary;
+- `semantics.role`, `semantics.label`, and `semantics.targetSize`.
+
+Project-system references use `project.ComponentName` and require a valid project standard profile. A custom decision is not permission to ignore accessibility or expected platform behavior.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/platforms.md

@@ -0,0 +1,40 @@
+# Platform discovery rules
+
+Read only the section matching platforms reported by `scan_ui.py`.
+
+## Web and React
+
+Prioritize route declarations, page/layout files, exported PascalCase components, JSX/TSX, CSS modules, global styles, theme providers, design-token JSON, and public assets. Preserve imported project components instead of flattening them into generic HTML controls. Extract visible strings, prop defaults, variants, and navigation calls.
+
+## Android Compose
+
+Prioritize `@Composable` functions, `NavHost`/`composable` routes, `MaterialTheme`, `Modifier` chains, preview fixtures, `Row`, `Column`, `Box`, lazy containers, text, images, icons, and project design-system components. Read `res/values`, vector drawables, fonts, and raster resources. Treat custom `Canvas`, subcomposition, and runtime measurement as unsupported until mapped.
+
+## Android Views
+
+Prioritize `res/layout`, navigation XML, styles/themes, drawables, Activities, Fragments, adapters, and view binding. Translate XML constraints into IR layout relationships; do not render Android widgets with browser defaults. Record custom Views as project-specific components.
+
+## SwiftUI and UIKit
+
+For SwiftUI, prioritize types conforming to `View`, `body`, stacks, grids, modifiers, `NavigationStack`, `NavigationLink`, previews, assets, and environment-driven themes. For UIKit, prioritize Storyboard/XIB, view controllers, Auto Layout constraints, appearance configuration, and asset catalogs. Mark custom drawing and implicit system metrics approximate unless a renderer mapping exists.
+
+## macOS SwiftUI and AppKit
+
+Detect macOS targets from `Package.swift` platform declarations, Xcode target metadata, `import AppKit`, `#if os(macOS)`, `NSApplication`, `NSWindow`, `NSViewController`, `WindowGroup`, `Settings`, `Commands`, and `MenuBarExtra`. For SwiftUI, prioritize scenes, windows, commands, split views, tables, toolbars, inspectors, focus, and environment-driven active/inactive states. For AppKit, prioritize NSWindow/NSWindowController, NSViewController, NSToolbar, NSMenu, NSSplitView, NSTableView, Auto Layout, bindings, and asset catalogs. Do not classify a macOS Storyboard/XIB as UIKit or reuse iOS navigation assumptions.
+
+## Windows
+
+Detect WinUI 3 and Windows App SDK through `.csproj`, `Microsoft.WindowsAppSDK`, `Microsoft.UI.Xaml`, `AppWindow`, XAML pages/windows, NavigationView, CommandBar, and resource dictionaries. Detect WPF through `UseWPF`, `System.Windows`, Window/Page/UserControl XAML, routed commands, styles, templates, and VisualStateManager. Read theme dictionaries, control templates, title-bar integration, window-size handlers, keyboard accelerators/access keys, UI Automation properties, high-contrast resources, and scale-aware assets. Keep WinUI, WPF, Win32, and hybrid web content distinct; do not translate XAML controls as browser-default HTML.
+
+## Flutter
+
+Prioritize `Widget` subclasses, `build`, `MaterialApp`/`CupertinoApp`, `ThemeData`, `Navigator`/`GoRouter`, rows, columns, stacks, flex, lists, assets, and `pubspec.yaml`. Use explicit fixture values for builders. Mark custom painters and runtime layout delegates unsupported until mapped.
+
+## Shared rules
+
+- Search navigation and theme definitions before individual leaf components.
+- Reuse literal strings and local assets; do not invent product copy.
+- Trace design-system wrappers to their defaults before choosing a renderer variant.
+- Keep alternate themes and responsive variants as explicit preview states.
+- For desktop targets, inventory window sizes, activation, menus, commands, keyboard shortcuts, pointer/keyboard focus, and multiwindow behavior as first-class states.
+- If a platform uses generated code, prefer authored source and configuration over generated output.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/quality-automation.md

@@ -0,0 +1,77 @@
+# Quality automation
+
+Use these deterministic gates for every final reconstruction, generation, redesign, or expert-review bundle. They inspect IR and standalone HTML only; they never run the target application. Ordinary `workbench` and `check` runs use **projection** mode: they verify evidence transfer and workbench behavior without judging the product UI. UI/UX heuristics run only in **review** mode after an explicit review request.
+
+## 1. Platform profile
+
+`references/platform-profiles.json` is the machine-readable source for profile IDs, standard-reference prefixes, minimum targets, required interaction states, and framework adapters. The validation matrix covers Android, iOS, macOS, Windows, Flutter, and Web.
+
+```powershell
+python <skill-dir>/scripts/validate_platform_profiles.py <review-dir>/ui-ir.json --output <review-dir>/platform-profile-report.json --strict
+```
+
+Fix a blocked report in IR. A `project` profile is valid only with a non-empty reason and project evidence.
+
+## 2. Coverage gate
+
+Run after the final IR update and before delivery:
+
+```powershell
+python <skill-dir>/scripts/coverage_report.py <review-dir>/ui-ir.json --mode projection --output <review-dir>/ui-coverage.json --markdown <review-dir>/ui-coverage.md --strict
+```
+
+Projection mode gates screen-tree uniqueness, discovered screens/routes/navigation, component mappings, appearance, profiles, and source/evidence transfer. It never gates target size, contrast, spacing, accessibility, or other UI-quality heuristics. Use `--mode review` only after an explicit review request; for generated/redesigned review artifacts it additionally gates semantics, standards, target size, contrast, and required state coverage. Do not average away a failed category; every active gate must pass or remain an explicit delivery blocker.
+
+## 3. Interaction scenario plan
+
+Generate the review plan from declared actions and states:
+
+```powershell
+python <skill-dir>/scripts/generate_interaction_matrix.py <review-dir>/ui-ir.json --output <review-dir>/ui-interaction-matrix.json
+```
+
+The plan covers single, repeated, reverse, chained, and boundary actions plus workbench zoom, menu, and panel continuity. `--max-pairs` bounds cross-control combinations without dropping individual control checks. Use `--merge-output <new-ir.json>` only when the plan should travel inside `review.scenarioPlan`; never overwrite the input IR. Generated scenarios are a plan, not proof of execution. Record actual results separately in `review.audit.interactionChecks`.
+
+## 4. Reproducible snapshots
+
+Capture both pixels and DOM geometry at the approved viewport:
+
+```powershell
+node <skill-dir>/scripts/smoke_preview.js <review-dir>/ui-preview.html --mode projection --output <review-dir>/ui-diagnostics.json --screenshot <review-dir>/candidate.png --geometry-output <review-dir>/candidate-geometry.json --capture-view overview --capture-screen home --capture-left-panel open --capture-right-panel open --capture-inspector-tab review --viewport-width 1440 --viewport-height 960
+```
+
+Use `--capture-review-section summary|problems|changes` to capture each review workspace deterministically. A production reviewer workbench needs at least Summary at primary and compact widths plus Problems and Changes after representative decisions or imports.
+
+Repeat for every primary and compact viewport. The `--capture-*` options restore a canonical view, screen, panel, and inspector state after smoke interactions, so regression screenshots do not accidentally capture the test residue. At widths up to 980 px, an explicitly open right panel closes the left panel to preserve the production mutual-exclusion invariant. Compare a candidate only with a deliberately approved baseline captured at the same viewport and state:
+
+The smoke workflow must also validate the portable agent handoff without launching an agent: an absolute artifact path, provider-neutral prompt/job, immutable-baseline/source guards, selected finding IDs for proposal jobs, and visible copy/refresh recovery controls. For `--agent codex`, additionally validate the optional `codex://new` URL. No adapter may require a bridge server, localhost port, or background process.
+
+```powershell
+python <skill-dir>/scripts/visual_regression.py --baseline <baseline.png> --candidate <candidate.png> --baseline-geometry <baseline-geometry.json> --candidate-geometry <candidate-geometry.json> --output <visual-regression.json> --diff-image <visual-diff.png> --strict
+```
+
+Pixel thresholds tolerate small antialiasing differences; geometry defaults to a one-CSS-pixel tolerance for the generated workbench shell and reconstruction mapping. Never treat source-authored spacing, wrapping, contrast, target size, or accessibility as a product problem in projection mode. Never replace an approved baseline automatically. A product finding may be created only during an explicit review.
+
+Pixel comparison uses Pillow (`PIL`). If the default Python runtime lacks it, use the bundled workspace Python runtime that provides Pillow; do not silently skip the regression gate.
+
+The workbench review shell has four committed golden states (Summary at wide and compact widths, Problems, and Changes). Verify them after changing the renderer, review navigation, or panel CSS:
+
+```powershell
+python <skill-dir>/scripts/verify_workbench_goldens.py
+```
+
+Use `--approve` only after visually inspecting every new PNG. This is an explicit maintainer action; normal verification never replaces a baseline.
+
+## Delivery gate
+
+A production review bundle contains:
+
+- `ui-ir.json` and `ui-preview.html`;
+- `platform-profile-report.json`;
+- `ui-coverage.json` and optional Markdown summary;
+- `ui-interaction-matrix.json` for stateful work;
+- `ui-diagnostics.json` for primary and compact profiles;
+- candidate screenshots and geometry snapshots;
+- `visual-regression.json` plus a diff image when pixels changed.
+
+Report each non-pass result. A successful script invocation is not equivalent to a passing report.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/review-workflow.md

@@ -0,0 +1,135 @@
+# Component registry and review workflow
+
+Use this reference when a task includes project-component reuse, Before/After comparison, comments, or staged design approval.
+
+## Component catalog
+
+`scan_ui.py` emits conservative `componentCatalog.components` candidates. The inventory is not a usable design system until each relevant entry has been inspected recursively.
+
+For every project component used by a screen:
+
+1. Inspect its implementation, default parameters, variants, states, reached tokens, assets, semantics, and platform dependency.
+2. Update the catalog entry with `inspection: mapped`, its actual `variants`, `states`, and `tokenRefs`, plus a renderer mapping such as `{"nodeType":"button","confidence":"high"}`.
+3. Set the corresponding node's `componentRef` to the catalog entry ID.
+4. Use `inspection: excluded` only with a non-empty `reason`, for example a preview-only wrapper or a component unrelated to rendered UI.
+5. Mark `componentCatalog.status: ready` only when every component used in the review scope is mapped or reasonedly excluded.
+
+When `componentCatalog.enforce` is true, the renderer blocks an uninspected catalog or project component use without a mapped `componentRef`. New project components require a design decision explaining why existing catalog entries are insufficient.
+
+## Review versions
+
+Base `nodes` are the immutable `Before` snapshot. Store proposals as sparse overrides rather than overwriting base nodes:
+
+```json
+{
+  "review": {
+    "sessionId": "checkout-review-2026-08-24",
+    "revision": "checkout-review-v1",
+    "baselineVersion": "baseline",
+    "activeVersion": "proposal-1",
+    "versionDecision": "pending",
+    "versions": [
+      {
+        "id": "baseline",
+        "label": "Before",
+        "kind": "baseline",
+        "status": "approved",
+        "nodeOverrides": {}
+      },
+      {
+        "id": "proposal-1",
+        "label": "After · clearer checkout action",
+        "kind": "proposal",
+        "parent": "baseline",
+        "status": "proposal",
+        "summary": "Clarifies the primary action without changing checkout behavior.",
+        "findingIds": ["finding-checkout-action-priority"],
+        "decisionIds": ["decision-checkout-action"],
+        "nodeOverrides": {
+          "checkout-action": {
+            "text": "Review order",
+            "style": {"background": "$colors.primary"}
+          }
+        }
+      }
+    ],
+    "annotations": []
+  }
+}
+```
+
+Version inheritance follows `parent`; later overrides merge node fields and merge `layout` and `style`. Keep IDs stable across iterations. Create a new proposal version for a materially different alternative instead of mutating an already reviewed version.
+
+Set `review.revision` to a stable human-readable revision for the review bundle. The renderer combines it with a target-content hash that covers screens, nodes, themes, versions, and audit data but excludes the renderer/workbench schema. Store the workbench and diagnostics-engine versions separately. Re-rendering or upgrading the HTML shell preserves review runs, selections, decisions, annotations, and view context when target content is unchanged. It preserves runtime diagnostics only when their engine version matches; otherwise it removes technical findings and requires a fresh run without discarding human review state. A legacy snapshot from the same `review.revision` lineage is migrated automatically once and stamped with the separate target revision. When target content really changes, do not silently replay stale references: keep the old snapshot intact until the reviewer migrates compatible state or discards it. Never migrate runtime findings across target revisions; recompute them.
+
+The HTML workbench provides split and overlay comparisons, highlights overridden nodes, and stores local review state in browser storage. Its canvas-first shell uses a narrow navigation rail, searchable screen tree, one compact document bar with the active ordinary-view version, a floating view palette with one pointer escape action, zoom-only bottom-right controls, and a contextual right panel. Properties and Comments activate their matching canvas modes from the rail, while Problems visibility is controlled inside the Problems panel rather than duplicated in the bottom palette. Compare is a dedicated view with explicit left/right version selectors. Side panels are independently collapsible and resizable on wide screens and mutually exclusive overlays at compact widths. `Approve version` means design approval only; it never authorizes source changes. Read [workbench-ui.md](workbench-ui.md) for the complete shell contract.
+
+Workbench menus are transient, mutually exclusive surfaces: opening one closes the previous menu, and selecting an action, clicking outside, pressing `Escape`, or changing view closes the open menu. In `All screens`, zoom applies to one shared overview canvas; it must not change the per-screen preview scale, grid geometry, or relative card positions.
+
+## Diagnostics Runner
+
+Every review preview exposes a local Diagnostics Runner in the right panel. Configure it through `review.diagnostics`, run it after the final render, and export its report with the review state. For every fixed `{width,height}` profile, the renderer loads an isolated same-document sandbox at that real CSS viewport size; do not emulate a narrow profile by merely recording a label. The runner changes workbench states only temporarily and restores the starting screen, view, version, zoom, comparison mode, selected node, active highlight, scroll positions, and node states when it finishes.
+
+The primary `Review` entry point is one button, `Запустить ревью`. It runs the configured scenarios across every assembled screen and fixed profile, replaces the previous runtime-generated set with evidence-backed cards for the current non-pass results, removes cards whose checks now pass, focuses that generated set in the findings list, and leaves the technical report under the collapsed `Диагностика` section. A repeated run reuses deterministic diagnostic finding IDs instead of duplicating cards. The launcher must show scope, running state, final issue count, and a clear rerun label.
+
+The Review panel uses three isolated workspaces: `Проверка`, `Проблемы`, and `Исправление`. Проверка reports exact screen/profile/check/state coverage and named run history. Проблемы groups automated failures by causal scenario and screen, keeps systemic findings ahead of instances, and supports source/screen/severity filtering plus bulk decisions. Исправление shows one concise current-state summary, result import, version comparison, design approval, and the source-planning boundary; it must not repeat another step diagram. A single sticky primary action advances to the next valid stage.
+
+Never claim `all states` from screen count alone. Enumerate every declared `node.states` variant for each included screen and deterministic viewport profile, execute it, and report tested versus expected combinations. Keep unavailable loading/error/offline/localization/RTL or assistive-technology conditions as explicit gaps. `Current screen` scope may reduce runtime; `All screens` remains the default final-review scope.
+
+After a completed local run, enable `Подготовить AI-ревью`. The generated HTML embeds its absolute review-directory path and creates a portable prompt/job for any filesystem-capable agent. A user still reviews and sends the prompt. With the optional `--agent codex` renderer adapter, the same job can also be prepared through the official `codex://new?prompt=...&path=...` deep link. Keep `ui-expert-review-request.json` as a portable fallback containing the complete IR, screen IDs, active version, runtime report, existing findings and decisions.
+
+The workbench accepts either a complete returned UI IR or `ui-design-workbench-expert-review-result` with `requestRevision`, `project`, `summary`, `findings`, `versions`, and `resolvedFindingIds`. Continue accepting the legacy `ui-code-preview-expert-review-result` so existing review jobs remain importable. Reject an explicit mismatched request revision or project. Merge nodes, stable finding IDs, and sparse proposal versions without replacing baseline nodes; register new versions in Changes, make the latest imported proposal the active ordinary-view version and the default right side of Compare, record an import-history entry, and open Changes. Import never authorizes source edits.
+
+For an explicit review headless/local pass, open the generated file with `?diagnostics=run&diagnostic-mode=review`; the runner starts automatically and exposes the same report in the diagnostics panel. This remains an offline HTML check and does not execute the application. Ordinary reconstruction uses `diagnostic-mode=projection` and never creates review findings.
+
+The dependency-free Node helper performs that pass and writes a reusable report:
+
+```powershell
+node <skill-dir>/scripts/smoke_preview.js <review-dir>/ui-preview.html --mode review --output <review-dir>/ui-diagnostics.json
+```
+
+Add `--screenshot <review-dir>/workbench.png --geometry-output <review-dir>/workbench-geometry.json --viewport-width 1440 --viewport-height 960` for reproducible pixel and DOM-geometry QA. Repeat at a compact width before delivery. Compare approved and candidate snapshots with `scripts/visual_regression.py` as described in [quality-automation.md](quality-automation.md).
+
+Set `CHROME_PATH` when Chrome, Edge, or Chromium is outside the common Windows, macOS, or Linux locations. Add `--fail-on-findings` for CI gating; without it, detected UI problems are reported but do not make the helper itself fail.
+
+Projection scenarios check screen/node IR-to-DOM transfer, source-evidenced variant rendering, navigation-target references, zoom-label/reset synchronization, stable overview-card geometry and scroll bounds, menu exclusivity, and the workbench's theme/state controls. They do not inspect product contrast, keyboard access, target size, typography quality, spacing, overlap, overflow, or user-flow reachability and cannot create findings. Review mode adds those UI/UX checks. Navigation reachability is assessed only when the IR declares an entry screen through `scenario.entryScreenIds` or `screen.navigationEntry`; otherwise review diagnostics validate target references without inventing a start node. Group repeated review non-pass checks by scenario and screen into one systemic runtime finding with measured instances. Exported review findings merge into `review.audit.findings`, so they remain actionable in the next revision.
+
+## Expert audit findings
+
+When `review.audit` exists, its findings appear above user annotations. Every failed `interactionCheck` or `layoutCheck`, and every `uxAssessment` with `status: finding`, links to one or more concrete cards through `findingIds`. Audit rows show the linked count and provide `Показать проблемы` plus `Все в исправление`; they are evidence summaries, not separate invisible work items.
+
+Each finding has one stable review number used in both the Problems list and its canvas marker. A reliably mapped screen/node receives a numbered circle; clicking it opens one anchored description card and the top-right collapse action restores the circle. Current finding filters and the Problems visibility toggle update list and canvas together. Each finding can focus its affected screen/node and, when linked to `proposalVersionId`, open the dedicated Compare view. A proposal declares visually addressed corrections in `resolvedFindingIds`; this is proposal coverage, not proof that project files changed. Baseline markers render only on the immutable reviewed version and on the original side of Compare. The reviewer chooses `Выбрать для применения`, `Не исправлять`, or `Позже`. The correction queue reports how many selected findings already have a proposal, how many need a new one, and how many were applied and verified. `Создать вариант макета` prepares an agent task scoped to the review directory. The task includes selected finding IDs, active and baseline versions, annotations, review scope, and `sourceChangeAllowed: false`; it may create up to two alternatives only when a real UX tradeoff exists. `Скопировать задание` and `ui-fix-request.json` remain portable fallbacks.
+
+The queue communicates six concrete outcomes: `Найдено → Выбрано → Учтено в новом макете → Подтверждено → Применено → Проверено`. The safe path previews corrections first and exposes `Применить исправления` only on step 3, after every selected preview-solvable finding is addressed in the active proposal and the user approves it. Approval still leaves the persistent status `в проект не применён`. A separate advanced source action is the explicit fast-path authorization: it prepares one implementation job for every current finding and bypasses proposal approval. Implementation jobs set `sourceChangeAllowed: true`, include `projectRoot`, stable finding IDs, annotations, and source targets, and must change real project files rather than merely rebuilding the proposal.
+
+After implementation, run incremental `uidw sync` and only targeted checks for affected screens, finding IDs, and project modules. Record a finding-level `verification` only for passing targeted checks; legacy `status: resolved`, a prepared handoff, proposal coverage, or proposal approval is not completion. Do not automatically repeat the full AI review; that is an explicit user action. The agent's final chat response must be a plain numbered list of every selected finding with screen, problem, implemented fix, changed files, verification result, and any remaining blocker. Keep this textual report in chat, not as a duplicate HTML block.
+
+Use [ui-reviewer.md](ui-reviewer.md) for evidence, severity, coverage, and proposal rules. Keep expert findings separate from user annotations: findings are the AI reviewer's reasoned analysis, while annotations are reviewer feedback on the current or proposed design.
+
+## Annotation lifecycle
+
+Annotations use statuses `new`, `in-progress`, `proposed`, `accepted`, `rejected`, or `resolved` and stay anchored to `screenId`, `nodeId`, and `versionId`. Preserve the source snapshot included by the workbench.
+
+Process comments incrementally:
+
+1. Explicitly save or copy `ui-review-state.json` from the preview. The File menu also restores this file directly; saving is never automatic.
+2. Merge it into a new IR file. The merge preserves the exported runtime report as `review.diagnosticsReport`, appends validated `runtimeFindings` to `review.audit.findings`, and records the feedback revision, so an agent can reconcile failed checks with findings and proposals:
+
+```powershell
+python <skill-dir>/scripts/merge_review_state.py <review-dir>/ui-ir.json <review-dir>/ui-review-state.json --output <review-dir>/ui-ir-reviewed.json
+```
+
+3. Select one coherent group of `new` comments. Mark them `in-progress` before proposing changes.
+4. Add a child proposal version containing only the required node overrides and link its decisions to the relevant annotations with `proposalVersionId` and a short response.
+5. Render again. The reviewer accepts or rejects each annotation and the version separately.
+6. Mark an annotation `resolved` only after its proposal is accepted. Rejected proposals remain in history and are never silently replaced.
+
+Do not edit application source during review or proposal generation. After the user explicitly chooses `Применить в проекте` or `Исправить всё в проекте`, implement only the authorized findings and list their affected source mappings and verification results in chat.
+
+## Offline boundary
+
+The preview remains a standalone local HTML file and makes no network requests. It can copy or download a portable task and may optionally navigate to a provider's official local deep link. This requires no bridge server, localhost port, CLI process, or background service. Preparing or navigating is not submission: the workbench must ask the user to send the prompt and never claim that AI review or remediation started.
+
+The agent task is restricted to the generated review directory. It may update `ui-ir.json`, regenerate `ui-preview.html`, and write validation artifacts, but it must not modify the source project or immutable baseline. When complete, the user returns to the preview and chooses `Обновить макет`. Export/copy of `ui-agent-job.json`, `ui-fix-request.json`, and `ui-expert-review-request.json` remains the recovery path when a native adapter is unavailable.
+
+`merge_review_state.py` accepts `ui-review-state.json`, the legacy `ui-review-feedback.json`, or the wrapped `ui-fix-request.json`. For a fix request it also preserves the selected IDs and requested action as `review.correctionRequest` before a new proposal is authored.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/ui-guidance-mode.md

@@ -0,0 +1,22 @@
+# Optional UI guidance mode
+
+Use this lightweight path only when `ui-context.json` reports `uiMode.enabled: true` and the user requests an ordinary UI-related source change. It prevents platform-inappropriate improvisation without turning every UI task into a design audit.
+
+## Task contract
+
+1. Keep the user's requested behavior and scope authoritative. Do not add a redesign, new dependency, mockup, review bundle, or unrelated cleanup.
+2. Resolve the target platform and existing UI stack from cached context and the directly affected source. Read only that platform section of [platform-standards.md](platform-standards.md) and any discovered project UI policy.
+3. Prefer existing project components, tokens, assets, typography, spacing, navigation, and state patterns. Platform guidance fills gaps; it does not erase an intentional project design system.
+4. Check the affected control or screen for relevant states, adaptive behavior, input method, focus/semantics, accessibility, localization pressure, and platform navigation/action placement. Ignore categories the change cannot affect.
+5. Implement in the real source only when the user's request authorizes implementation. Run the smallest relevant repository validation and report any deliberate standards exception or unresolved evidence.
+
+## Platform routing
+
+- Android: existing Compose/Views stack, Material guidance compatible with that stack, system back/navigation, touch targets, state and accessibility semantics.
+- iOS: existing SwiftUI/UIKit stack, Apple navigation and presentation patterns, Dynamic Type, safe areas, and semantic controls.
+- macOS: existing SwiftUI/AppKit stack, window/menu/toolbar conventions, keyboard commands, compact pointer geometry, and active/inactive state.
+- Windows: existing WinUI/WPF/other installed stack, Fluent-compatible command placement, keyboard/focus/high-contrast behavior, resizable-window layout, and pointer/touch differences.
+- Flutter: existing Material/Cupertino/adaptive stack, platform-aware navigation and semantics, scalable text, safe areas, and responsive layout.
+- Web: existing framework and design system, semantic HTML, WCAG 2.2 AA, keyboard/focus behavior, responsive layout, and established component primitives.
+
+The mode is advisory and scoped. It does not claim that the whole product was reviewed or made compliant.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/references/ui-policy-schema.md

@@ -0,0 +1,83 @@
+# Project UI policy
+
+An optional `.codex/ui-policy.json` makes design choices repeatable across tasks. Do not create or change it inside a repository without explicit approval. `ui-policy.json` at the repository root is also recognized.
+
+```json
+{
+  "version": 1,
+  "platforms": {
+    "android": {
+      "standardProfile": "material3",
+      "implementation": "compose",
+      "allowExperimental": false,
+      "minimumTarget": 48,
+      "adaptive": true
+    },
+    "ios": {
+      "standardProfile": "apple-hig",
+      "implementation": "swiftui",
+      "minimumTarget": 44,
+      "preferSystemComponents": true
+    },
+    "macos": {
+      "standardProfile": "macos-hig",
+      "implementation": "swiftui",
+      "minimumTarget": 28,
+      "documentedMinimumTarget": 20,
+      "preferSystemComponents": true,
+      "requireMenuCommands": true,
+      "resizableWindows": true
+    },
+    "windows": {
+      "standardProfile": "windows-fluent",
+      "implementation": "winui3",
+      "minimumTarget": 40,
+      "inputs": ["mouse", "keyboard", "touch", "pen"],
+      "requireVisibleFocus": true,
+      "requireHighContrast": true,
+      "resizableWindows": true
+    },
+    "flutter": {
+      "standardProfile": "flutter-adaptive",
+      "implementation": "flutter",
+      "minimumTarget": 48,
+      "adaptive": true,
+      "preferPlatformSemantics": true
+    },
+    "web": {
+      "standardProfile": "web-platform",
+      "wcagTarget": "2.2 AA",
+      "minimumTarget": 24,
+      "preferNativeHtml": true
+    }
+  },
+  "brand": {
+    "tokenSources": ["design/tokens.json"],
+    "componentRoots": ["ui/components"],
+    "assetRoots": ["assets"],
+    "allowInventedCopy": false
+  },
+  "rules": {
+    "preferProjectComponents": true,
+    "allowNewDependencies": false,
+    "allowCrossPlatformVisualParity": false,
+    "requireStateMatrix": true,
+    "forbiddenPatterns": [
+      "unapproved gradients",
+      "decorative glass effects",
+      "icon-only destructive actions",
+      "navigation controls used as actions"
+    ]
+  }
+}
+```
+
+## Resolution
+
+- Explicit user instructions override the policy for the current task; record the override.
+- Repository instructions and installed framework constraints remain authoritative for implementation.
+- Missing policy values fall back to [platform-standards.md](platform-standards.md), not to model preference.
+- Numeric minimums may be stricter than platform defaults but must not be weaker than required accessibility baselines without a documented standards exception.
+- Paths are repository-relative. The policy identifies authoritative sources; it does not duplicate token or component contents.
+
+Copy the resolved policy into `design.policySnapshot` in review IR. Include `policyFile` so annotations and later tasks can trace the decision source. Never silently mutate the policy during preview iteration.