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/ui-reviewer.md

@@ -0,0 +1,175 @@
+# Evidence-based UI/UX reviewer
+
+Use this workflow when the user asks to review, audit, critique, simplify, or improve an existing interface and expects corrected visual proposals.
+
+## Review contract
+
+The reviewer must produce three connected artifacts:
+
+1. an accurate, source-linked `Before` reconstruction;
+2. a prioritized audit whose findings are anchored to screens and nodes;
+3. one or more restrained correction versions that can be opened directly in `Before / After`.
+
+Do not edit application source during the review. Do not redesign untouched regions, invent product requirements, or turn personal taste into a defect. A missing runtime fact remains a validation gap rather than a confident finding.
+
+## Evidence order
+
+Use the strongest applicable evidence in this order:
+
+1. explicit product requirements, user feedback, research, analytics, or support evidence supplied in scope;
+2. repository behavior, task flow, content, design tokens, components, platform versions, and intentional project conventions;
+3. official target-platform guidance from [platform-standards.md](platform-standards.md), including accessibility requirements;
+4. established usability heuristics for visibility, match to user language, control and recovery, consistency, error prevention, recognition, efficiency, minimalism, error recovery, and help;
+5. a clearly labelled inference with `confidence: low` when stronger evidence is unavailable.
+
+Never fabricate research, analytics, user intent, legal requirements, or runtime accessibility results. Heuristics can identify risk, not prove that users fail.
+
+Use stable heuristic references when needed: `heuristic.visibility`, `heuristic.real-world-language`, `heuristic.user-control`, `heuristic.consistency`, `heuristic.error-prevention`, `heuristic.recognition`, `heuristic.efficiency`, `heuristic.minimalism`, `heuristic.error-recovery`, and `heuristic.help`. Pair a heuristic with source evidence and a platform/accessibility reference whenever the finding depends on a concrete control or behavior.
+
+## Scope before scoring
+
+Record:
+
+- audited platforms and installed UI frameworks;
+- primary and secondary user tasks;
+- included screens, logical views, routes, and relevant states;
+- excluded areas with reasons;
+- available evidence and validation gaps;
+- viewport classes, input methods, themes, localization/RTL, and accessibility conditions in scope.
+
+Review the complete requested flow, not only a visually representative screen. Check default, loading, empty, error, offline, permission, disabled, success, destructive confirmation, long content, text scaling, and adaptive layouts where applicable.
+
+## Review lenses
+
+Evaluate only lenses relevant to the product and platform:
+
+- task flow and information architecture;
+- navigation, orientation, back/cancel, and context preservation;
+- visual hierarchy, density, grouping, alignment, spacing, and typography;
+- action priority, affordance, labels, discoverability, and icon comprehension;
+- forms, validation, error prevention, retained input, and recovery;
+- feedback, progress, system status, empty/loading/error/success states;
+- platform component and interaction conformity;
+- accessibility semantics, focus, keyboard, target size, contrast, scaling, motion, and assistive technology structure;
+- responsive/adaptive behavior, safe areas, localization expansion, RTL, and long content;
+- transient surfaces and interaction sequences: menus, popovers, drawers, dialogs, tooltips, selection changes, repeated actions, and dismissal behavior;
+- consistency with the project's mapped component system;
+- content clarity, terminology, destructive wording, and unnecessary cognitive load;
+- privacy, trust, irreversible actions, and exposure of sensitive information when visible in the UI.
+
+Do not reward decoration. Simpler means fewer decisions, clearer grouping, safer defaults, less repetition, or a shorter task path—not merely fewer visible elements.
+
+## Mandatory interactive behavior pass
+
+A visual snapshot is insufficient when the deliverable contains working controls. Exercise the generated HTML preview before completing the review, without running the real application:
+
+1. Run every workbench view at least once: `All screens`, `Prototype`, `Single screen`, and the dedicated `Compare` view when retained versions are available. Switch the active ordinary-view version independently.
+2. In `All screens`, test Fit plus manual zoom at 20%, 100%, and 200%. Screen geometry and relative positions must remain stable: zoom scales one shared canvas, its scrollable bounds grow or shrink with that canvas, and cards must not reflow into or overlap one another.
+3. Open each application-menu item in sequence. At most one menu or popover may remain open. Verify dismissal by selecting an item, clicking outside, pressing `Escape`, changing view, and reopening the same trigger.
+4. Exercise navigation, back/forward, panel show/hide, panel resizing, interaction-mode changes, repeated clicks, and the relevant product menus, drawers, dialogs, tabs, and state actions. Check both the end state and intermediate/transient states.
+5. Repeat the interaction pass at the primary review viewport and one narrower adaptive viewport, using pointer and keyboard paths where the control supports both.
+
+Record an observed failure as a finding with the exact action sequence, start state, resulting state, affected screen or workbench region, and user impact. If browser interaction is unavailable, list these scenarios as validation gaps and do not claim the interactive review is complete.
+
+### State-transition and cross-control matrix
+
+Inventory every stateful control and every visible value derived from it. For each transition, verify the complete contract rather than checking only whether the main content changed:
+
+- trigger state, action, expected next state, and a repeated/reverse action;
+- visual selection/pressed/open/disabled state;
+- text, number, badge, tooltip, status, and accessible-name synchronization;
+- focus destination, keyboard path, dismissal, and history behavior;
+- effects on dependent controls, panels, menus, selection, scroll position, and persisted state;
+- geometry at the new state: clipping, overlap, reflow, occlusion, reachable scroll bounds, and stable anchors.
+
+Include paired and chained actions that can expose stale or conflicting state, for example: zoom → reset → zoom, Fit → resize panel → Fit, open menu A → open menu B → outside click, select node → zoom → hide panel → restore panel, and switch view → browser Back/Forward. Test boundary values and at least one intermediate value, not only defaults.
+
+The audit records these checks under `review.audit.interactionChecks`. Each entry states `id`, `startState`, `actions`, `expected`, `observed`, `result`, `viewports`, and `inputMethods`. A `complete` audit cannot contain an untested (`not-run`) interaction check.
+
+After the reasoned audit and proposal render, run the HTML Diagnostics Runner. Use its measured report to catch state synchronization, shared-canvas drift/overlap, menu conflicts, text containment, padding/height variance, small targets, and missing accessible names across every rendered screen. Reconcile every failure with the expert findings or a documented false-positive/validation gap. Automated geometry and DOM checks never replace the separate UX assessment: they cannot decide whether information architecture, icon meaning, action priority, cognitive load, or platform idiom is appropriate.
+
+### Mandatory typography and geometry pass
+
+Treat text and spacing as measurable layout, not as subjective polish. For every toolbar, menu, form row, repeated card, and button group at the reviewed viewport/zoom combinations:
+
+- define the intended typography roles and verify a coherent hierarchy of family, size, weight, line height, color, and emphasis;
+- compare sibling label baselines and the top, center, and bottom edges of their control boxes; investigate visible deviation greater than 1 CSS px after normalizing page transforms;
+- measure effective top/right/bottom/left padding, icon-label gap, target box, and spacing between adjacent controls; equal variants must use equal geometry unless the difference is intentional and recorded;
+- count rendered text lines and compare `scrollWidth/clientWidth` and `scrollHeight/clientHeight`; flag unintended wrapping, clipping, ellipsis, overflow, or text leaving its container;
+- verify active, inactive, hover, focus, disabled, loading, and selected variants do not change label position or control dimensions unexpectedly;
+- repeat with long localized labels, text scaling, narrow width, Fit, 100%, and the supported zoom boundaries; distinguish deliberate wrapping from accidental wrapping;
+- visually check optical alignment of icons and text after numeric measurements, because equal boxes do not guarantee equal perceived alignment.
+
+Store results under `review.audit.layoutChecks`. Each entry includes `id`, `scope`, `viewports`, `zoomLevels`, `metrics`, `expected`, `observed`, `result`, and linked `findingIds` when it fails. A completed audit requires checks for typographic hierarchy, sibling alignment/baseline, control padding, text containment, and icon-label optical alignment. If geometry cannot be measured, mark the audit partial and record the validation gap.
+
+## Separate UX assessment
+
+Run a dedicated UX assessment after correctness and interaction testing. Do not collapse UX into a list of rendering bugs. Evaluate:
+
+- whether the primary task, current mode, current screen, navigation availability, and next likely action are evident without trial clicks;
+- whether information architecture and grouping match the user's mental model and keep related controls together;
+- whether actions are placed where users expect them, ordered by frequency and consequence, and separated when accidental activation is costly;
+- whether labels, icons, and tooltips make the outcome predictable before activation;
+- whether icon metaphors are conventional for the target platform, visually consistent in family, stroke/fill, optical size, alignment, and emphasis, and distinguishable from adjacent icons;
+- whether icon-only controls have accessible names and whether unfamiliar or ambiguous icons retain a visible label or concise tooltip;
+- whether button size, target area, spacing, hierarchy, disabled/pressed/loading feedback, and destructive styling fit the platform and input method;
+- whether density, repeated controls, competing emphasis, long panels, and simultaneous tool groups overload the interface or hide the primary workflow;
+- whether progressive disclosure removes complexity without hiding essential state or navigation;
+- whether the interface remains coherent at supported widths, zoom levels, text scaling, localization expansion, themes, and input methods.
+- whether typography roles create an intentional hierarchy and repeated controls share stable baselines, padding, label position, and optical alignment.
+
+Treat visual beauty as coherence, balance, craft, and fit with the project/platform—not as personal taste. Record assessments under `review.audit.uxAssessment`, with one entry per relevant lens containing `lens`, `status`, `observation`, and linked `findingIds` or a validation gap. A deep review must explicitly cover information architecture, discoverability, action placement, iconography, typographic hierarchy, spacing/alignment, control ergonomics, density/cognitive load, feedback/state visibility, and adaptive behavior.
+
+## Finding quality gate
+
+Every finding under `review.audit.findings` contains:
+
+- stable `id` and concise `title`;
+- `category` and `severity`;
+- `confidence`: `high`, `medium`, or `low`;
+- `screenId` and, when possible, `nodeId` plus source mapping;
+- `observation`: what is verifiably present;
+- `impact`: the user or business consequence;
+- `recommendation`: a concrete correction that preserves stated constraints;
+- non-empty `evidence`, each with `type`, `ref`, and a short `note`;
+- `effort`: `small`, `medium`, or `large`;
+- `proposalVersionId` and optional `decisionId`, or `noProposalReason`.
+
+Valid evidence types are `requirement`, `user-feedback`, `research`, `analytics`, `source`, `project-pattern`, `platform-standard`, `accessibility-standard`, and `heuristic`. A URL or standard identifier must be specific enough to verify; `best practice` is not evidence.
+
+Use one finding for one causal problem. When a design-system defect repeats, create one `systemic: true` finding with `instances` rather than flooding the audit with duplicates.
+
+## Severity and prioritization
+
+- `blocker`: prevents the primary task, causes data loss/security/safety risk, or excludes a required user group with no viable workaround.
+- `high`: creates likely errors, severe disorientation, inaccessible core interaction, or substantial abandonment risk.
+- `medium`: adds recurring friction, ambiguity, unnecessary effort, or inconsistent platform behavior without blocking completion.
+- `low`: localized clarity, consistency, or polish issue with limited task impact.
+
+Do not infer severity from visual ugliness. Consider task criticality, reach/frequency, reversibility, evidence confidence, and implementation effort. Keep the scorecard traceable to findings; never invent an overall numeric score from intuition.
+
+## Correction proposals
+
+1. Preserve the baseline nodes and routes.
+2. Create a primary proposal that fixes the highest-value coherent group with the fewest unrelated changes.
+3. Link the version's `findingIds` and `decisionIds` to the audit.
+4. Use project components first, then the platform baseline. Record deviations.
+5. Preserve business rules, data availability, analytics hooks, accessibility labels, and accepted content unless the finding explicitly addresses them.
+6. Add another variant only when it demonstrates a meaningful tradeoff such as density versus guidance or persistent versus progressive disclosure.
+7. Keep unresolved runtime questions in `review.audit.validationGaps`; do not fake them in HTML.
+
+Each blocker/high finding must either open a corrected comparison or explain why a responsible visual proposal cannot be made without more evidence.
+
+## Presentation order
+
+Present:
+
+1. a concise audit summary and coverage statement;
+2. blocker/high findings first, then medium/low;
+3. systemic findings before repeated instances;
+4. direct navigation to the affected screen/node;
+5. `Before / After` for each linked proposal;
+6. tradeoffs and validation gaps;
+7. explicit design approval controls, separate from source-edit approval.
+
+The HTML workbench lets the user filter findings, focus the affected element, compare its proposed correction, and accept/reject the finding. Export those decisions with annotations for the next iteration.

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

@@ -0,0 +1,34 @@
+# Delivery validation
+
+Run this checklist for every final bundle. The detailed commands and report formats live in [quality-automation.md](quality-automation.md).
+
+## Coverage and fidelity
+
+- Inventory includes platforms, all screens/logical views/routes/navigation targets, source-evidenced surfaces, components, tokens, assets, and explicit exclusions. `screenTree` contains every screen exactly once and preserves every discovered `groupPath`/`parentFragment`; a flat list is not complete hierarchy coverage.
+- Coverage is 100% for declared screens, routes, and visible navigation. Component mappings and source/design evidence pass the mode-specific thresholds.
+- The viewport content box matches the target size. Reconstruction reports `exact`, `high`, `approximate`, or `unsupported`; never claim pixel parity without runtime comparison.
+- Platform profile, semantics, target size, states, contrast, accessibility, installed-framework constraints, and input methods are explicit and pass strict validation or remain named blockers.
+
+## Workbench behavior
+
+- All screens uses a single scalable canvas at Fit, 20%, 100%, and 200% without changing card dimensions, reflow, overlap, or incorrect scroll bounds. Zoom reset updates both geometry and displayed value.
+- Prototype navigation, browser history, Single-screen freezing, active/hover-target tree colors, menu mutual exclusion/dismissal, panel collapse/resize persistence, compact overlay behavior, and selection/scroll persistence all work.
+- Properties, Review, and Comments are isolated contextual panels. Icons use one coherent SVG family, icon-only actions have names/tooltips, and top chrome remains compact and unambiguous.
+- The Problems toggle, active-version selector, Compare view, left/right version selectors, and split/overlay choices expose accurate states without duplicating commands or changing unrelated toolbar geometry.
+- Finding markers use the same stable numbers as the Problems list, remain anchored after zoom/scroll/resize, open only one inline description at a time, collapse back to a circle, follow all finding filters, and never edit source. Findings declared in a proposal's `resolvedFindingIds` are hidden only on that version and stay visible on the baseline side of Compare.
+
+## Deep review
+
+- Exercise default, loading, empty, error, offline, permission, disabled, success, destructive, focus, active/inactive, long-label/localization, text-scale, theme, narrow, and platform-specific states where applicable.
+- Build interaction and cross-control scenarios for single, repeated, reverse, chained, boundary, and intermediate actions. Verify visual state, displayed values, focus, history, persistence, dependencies, scroll, and geometry after every transition.
+- Measure typography hierarchy, baselines, four-side padding, icon-label gaps, box edges/heights, line counts, clipping, containment, overflow, and optical alignment at primary/compact viewports and zoom boundaries.
+- Run a separate UX assessment of information architecture, discoverability, action priority/location, icon meaning/style, ergonomics, density/cognitive load, feedback/state visibility, progressive disclosure, adaptive behavior, platform fit, and visual coherence.
+- Every non-pass check links to stable findings. Each finding has evidence, observation, impact, recommendation, severity, confidence, source target, standard/project basis, and proposal or `noProposalReason`. Consolidate repeated causal defects as systemic findings.
+
+## Automation and approval
+
+- Run strict platform validation, strict coverage, interaction-matrix generation for stateful UI, primary/compact diagnostics, screenshot plus geometry capture, and visual regression only against an explicitly approved matching baseline.
+- The Review entry point checks the declared scope, records exact coverage/history, groups systemic failures, and exposes Problems and Changes with task-language decisions.
+- Agent jobs include stable selection/scope/revision data, immutable-baseline rules, allowed writes, and `sourceChangeAllowed: false`. Preparing a proposal or review never claims execution started.
+- A proposal requires explicit design acceptance. A separate source plan still requires approval of intended application files and diff.
+- The preview performs no network requests. Report unsupported constructs, skipped tests, validation gaps, and residual risk.

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

@@ -0,0 +1,108 @@
+# Production workbench UI
+
+Use this reference when generating the review workbench shell itself. It governs the editor chrome around reconstructed screens; it must never leak into the product UI being reviewed.
+
+## Canvas-first information architecture
+
+Give each persistent region one job:
+
+- a narrow left rail starts with the conventional File/menu trigger, then switches Screens, Properties, Review, and Comments, exposes the language icon menu, controls right-panel visibility, and remains available when panels collapse;
+- the left panel contains project/screen navigation, hierarchy, search, and low-priority coverage metadata;
+- one compact document bar contains product identity, current screen path, and the single active version used by ordinary views; document actions and locale selection stay in the rail instead of consuming canvas width;
+- the canvas owns screen previews and comparisons;
+- a floating canvas palette switches view and interaction tools and independently toggles `Problems`;
+- Compare is a dedicated view: its compact contextual bar selects the left and right versions and then the split/overlay layout. Do not mix version selection with view selection through a `Before / Compare / After` visibility group;
+- a small bottom-right cluster owns zoom only;
+- the right panel is contextual and shows only `Properties`, `Review`, or `Comments`. Every area is directly reachable from the rail, while Inspect and Comment canvas tools also open their matching area; do not add a duplicate tab row inside the panel.
+
+Do not duplicate the same primary control in several persistent regions. Menu commands may repeat toolbar actions only as a conventional keyboard/menu fallback. Keep document actions, canvas tools, object properties, review decisions, and navigation visually distinct.
+
+This structure follows stable patterns documented in Figma, Sketch, and Penpot: navigation/layers on the left, a dominant scrollable canvas, contextual properties on the right, dedicated prototype/comment modes, and collapsible UI for more canvas space.
+
+Official pattern references:
+
+- Figma navigation and panels: https://help.figma.com/hc/en-us/articles/360039831974-Explore-the-navigation-bar-and-left-sidebar
+- Figma properties and prototype modes: https://help.figma.com/hc/en-us/articles/360039832014-Design-Prototype-and-view-Code-in-the-Properties-Panel
+- Figma comments: https://help.figma.com/hc/en-us/articles/360039825314
+- Sketch toolbar: https://www.sketch.com/docs/interface-and-settings/the-mac-app-interface/the-toolbar/
+- Sketch layer list: https://www.sketch.com/docs/interface-and-settings/the-mac-app-interface/the-layer-list/
+- Sketch canvas: https://www.sketch.com/docs/interface-and-settings/the-mac-app-interface/the-canvas/
+- Penpot interface: https://help.penpot.app/user-guide/first-steps/the-interface/
+
+## Progressive disclosure
+
+- Show the screen tree by default on wide windows.
+- Show only the active right-panel tab. Selecting an inspection or comment tool opens its matching tab.
+- Keep diagnostics collapsed until requested or until a run has non-pass results.
+- Present Review as three explicit user steps: `Проверка`, `Проблемы`, and `Исправление`. Each step must show its completion state and a short plain-language outcome.
+- Keep exactly one visually primary contextual action in the sticky footer. It advances the workflow: check the interface, inspect issues, prepare a fix, compare it, approve it, and apply it.
+- Selection is a separate transition: after choosing findings, step 2 says exactly how many are selected and offers `Перейти к исправлению · N`. It must not start proposal generation or show an apply-to-project action.
+- Show `Применить исправления · N` only while step 3 is active, only after the selected proposal has been compared and approved. Steps 1 and 2 must never expose source-application wording.
+- Count expert and runtime findings together in the human-facing result. Never report “no issues” while unresolved expert findings exist.
+- Keep coverage, history, raw diagnostics, AI handoff, JSON import/export, and direct source changes inside collapsed `Дополнительно` or caution regions. They are escape hatches for advanced users, not parallel primary workflows.
+- Keep finding observation and actions visible; place impact, recommendation, and evidence in an expandable detail region.
+- Use the same stable number for each finding in the Problems list and on the canvas. Canvas markers remain circles until clicked, open one compact anchored card at a time, and expose an unambiguous top-right collapse control that restores the circle.
+- Render unresolved user comments on the canvas as numbered markers from a distinct, non-severity color family. They open and collapse like findings but remain a separate semantic layer and list.
+- Use short empty states that name the next direct action. Do not add tutorial paragraphs to compensate for ambiguous controls.
+- Do not vertically stack the three steps or expose multiple competing “start/fix/export” buttons. Secondary actions may remain available inside expandable details but must not compete visually with the contextual primary action.
+- Name versions by user meaning: `Исходный макет` and `Новый макет`, optionally followed by a concise proposal name. Do not expose unexplained `Before`/`After` labels. Fresh redesign previews open the newest proposal by default and clearly identify it as the new mockup; this does not imply that source files were changed.
+- Keep the finding lifecycle explicit: `Найдена → Выбрана → Учтена в новом макете → Макет подтверждён → Применена → Проверена`. `resolvedFindingIds` stops at “Учтена в новом макете”; it must never make a card, step, or version look applied or verified. Only a targeted passing `verification` record may produce `Применено и проверено`.
+- Show the proposal status persistently beside the version selector. Until source implementation and targeted verification are recorded, use `Ещё не применён к проекту` (or `Задание на применение подготовлено` after handoff), even after the proposal is approved.
+
+## Controls and visual system
+
+- Use one coherent inline SVG icon family with equal view boxes, stroke behavior, optical size, and alignment. Do not use mixed Unicode glyphs as workbench icons.
+- Keep icon-only controls for conventional actions such as panel collapse, zoom, and export. Give every icon-only control an accessible name and concise tooltip.
+- Retain visible labels for modes whose meaning is not safely conveyed by an icon alone. Labels may collapse at narrow widths.
+- Use restrained neutral surfaces, one primary accent, semantic success/warning/error colors, subtle borders, and elevation only for floating or transient surfaces.
+- Base dense desktop controls on a 28–32 px visual box while preserving at least a 24×24 CSS px WCAG target and larger targets where space permits.
+- Use stable typography roles: 13 px panel/page title, 10–11 px primary control/body text, 8–9 px metadata. Never shrink essential task text merely to fit a panel.
+- Equivalent segmented controls must share height, padding, baseline, icon box, and selected-state geometry.
+- Localize every built-in workbench label, accessible name, tooltip, empty state, and toast at runtime with native-language choices (`Русский`, `English`) and persist the locale in local storage plus `?lang=`. Stable internal values may remain English. Never translate the reconstructed product, screen names, version names, findings, comments, or evidence.
+
+## Adaptive behavior
+
+- Wide layout: left navigation and contextual right panel may coexist.
+- Compact desktop/tablet layout: panels become overlays. Opening one closes the other so the canvas retains a useful working width.
+- Narrow layout: rail remains; panel labels and nonessential document-bar items collapse before controls disappear.
+- Panel width, active tab, selected node, review filter, scroll, and collapse state persist by review revision.
+- Persist review results independently from the generated shell version. Rebuilding `ui-preview.html` with unchanged target screens/nodes/versions must restore diagnostics, run history, selections, decisions, annotations, and view context automatically. Never let unload or incidental UI interaction overwrite a quarantined stale snapshot before the reviewer chooses migrate or discard.
+- Version runtime diagnostics independently. An engine upgrade or a new run removes obsolete runtime findings but preserves expert findings, decisions, annotations, run history, and view context.
+- Put `Сохранить ревью` and `Восстановить ревью` in File. Both are explicit actions; opening or checking a preview must never download a file.
+- A panel opened from a finding, comment, inspection tool, diagnostic, or application menu must select the relevant tab automatically.
+
+## Interaction contract
+
+- `All screens`, `Prototype`, `Single screen`, optional `Variants`, and `Compare` are view modes and stay in one group. `Variants` is disabled when the current screen has neither extra scenarios nor extra source-evidenced themes; do not create filler states or themes merely to enable it. No other persistent control may also enter Compare.
+- The bottom canvas palette keeps view modes plus only the pointer/Interact escape action. `Properties` and `Comments` in the rail activate Inspect and Comment respectively; the Problems visibility toggle lives inside the Problems panel, so these commands are not duplicated in the persistent bottom palette.
+- Prototype is the only mode in which declared navigation changes screens. Entering it activates Interact, and selecting a screen in the tree preserves Prototype instead of silently falling back to Single screen.
+- Single screen and Prototype show one stable compact control bar only when alternatives exist. Use fixed-width native selectors for Theme and State rather than one button per value; changing long labels must not resize the bar, move the canvas, or lose keyboard focus. One grid action opens `Variants`, which provides `By theme`, `By state`, and, only when both dimensions vary, `Matrix`. The matrix is split into visually separate theme sections; it must not flatten every combination into one unlabelled grid. Every device retains its theme, scenario patch, stable geometry, and label.
+- Selecting a node synchronizes canvas highlight, layer/screen context, and the Properties or Comments panel without losing canvas scroll.
+- Menus and popovers are mutually exclusive and close on action, outside click, `Escape`, or view change.
+- Diagnostics must be observational: menu, keyboard, and interaction checks may use inert diagnostic controls but must never activate export, source-change, clipboard, navigation, or other consequential user commands. `ui-review-state.json` is downloaded only after an explicit user click on `Сохранить ревью`.
+- The current screen and hovered navigation destination use distinct colors.
+- Design approval and source implementation are separate phases with separate actions. The primary safe flow is preview → approve → `Apply to project`; the Problems workspace also exposes one unmistakable `Fix everything in project` fast path. Never label a generated After mockup as a completed project fix.
+- Ordinary views render exactly one version chosen in the document bar. Version selection never changes the view mode.
+- Compare mode allows any two retained review versions, not only baseline versus latest, while preserving the immutable baseline. Its left/right selectors and Split/Overlay controls appear only inside the dedicated Compare context and never duplicate the main view switcher.
+- `Problems` is a visibility layer, not a separate review mode. Its marker set follows the current severity/source/screen/focused-block filters and never invents an anchor for a finding whose screen cannot be located.
+- Clicking a finding marker opens its description on the canvas without navigating away. Opening a second marker closes the first; hiding Problems, changing screen/version, or collapsing the card leaves list state and numbering synchronized.
+- Place markers beside the device they annotate, not in one global right-hand stack. In Compare, markers for the left version use the outer left edge and markers for the right version use the outer right edge; in ordinary views choose the nearest device edge to the anchor. User-comment markers follow the same placement rule in their own color.
+- Bind each review to an immutable `reviewVersionId`, defaulting to the baseline. Version selectors change only what is displayed; they never retarget or rerun the review. Baseline finding markers appear only on that reviewed version, never on proposal versions, and only on the original side of Compare. A correction version lists the baseline findings it addresses in `resolvedFindingIds`; this means “shown as corrected in this proposal”, not source implementation or verification. Merely linking a finding with `findingIds`, setting legacy `status: resolved`, approving the proposal, or preparing an agent handoff is also insufficient.
+- Finding and comment markers use the scrollable canvas as their containing block, resolve collisions independently for each rendered device and side, and are remeasured after zoom, canvas/device scroll, resize, version change, and panel layout change. They must remain beside the owning device; leader lines preserve the exact node relationship when collision avoidance changes the vertical slot.
+- Holding the middle mouse button and dragging pans the entire canvas in both axes where overflow exists. Prevent browser autoscroll, show a grabbing cursor while active, and release capture on pointer up/cancel without activating product controls.
+- Large reviews default to all screens but may be scoped to the current screen. The scope and exact counts must travel in diagnostics and AI handoff payloads.
+
+## Production acceptance gate
+
+Before delivery:
+
+1. Render screenshots at a primary viewport and one compact viewport.
+2. Inspect visual hierarchy, canvas area, panel competition, icon consistency, label baselines, spacing, clipping, selected states, empty states, and floating-control occlusion.
+3. Run the Diagnostics Runner and the review workflow smoke test.
+4. Click the one-button review launcher and confirm that it covers every screen/profile, converts every non-pass result into a focused finding set without duplicates, and enables a self-contained expert-review export only after completion.
+5. Verify the agent handoff uses an absolute review-directory path, prepares only a prompt/job, clearly asks the user to send it, requires no server or open port, and leaves source modification blocked. Verify `Скопировать запрос`, `Обновить макет`, and the JSON fallback independently; test native adapters separately.
+6. Verify Summary/Problems/Changes isolation, contextual primary-action progression, source/screen filters, bulk selection, named run history, expert-result import, revision/project rejection, and active proposal comparison.
+7. Verify compact-width panel mutual exclusion, every right-panel tab, every view/tool combination, panel resizing/collapse, menu dismissal, zoom, tree search, and version approval.
+8. Verify Problems state, active-version selection, dedicated Compare version pairing/layout, direct-link state normalization, marker/list number parity, per-version resolution, per-device-side placement, distinct user-comment markers, collision-free layout and anchoring after zoom/scroll/resize, single-popover behavior, and collapse back to a marker.
+9. Verify the restored rail commands, File and language icon menus, mutually exclusive menu dismissal, middle-button canvas pan, pointer release/cancel, marker click isolation, RU/EN switching, locale persistence, and that product/user content remains untranslated.
+10. Reject the shell if understanding the primary controls depends on permanent help copy.

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/schemas/native-render-state.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Elgreed/ui-design-workbench/schemas/native-render-state.schema.json",
+  "title": "UI Design Workbench native render state",
+  "type": "object",
+  "required": ["schemaVersion", "type", "repository", "status", "currentFidelityTier", "nativeExecutionStarted", "platforms", "providers", "captures"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "type": { "const": "ui-design-workbench-native-render-state" },
+    "repository": {
+      "type": "object",
+      "required": ["root"],
+      "properties": { "root": { "type": "string" } },
+      "additionalProperties": true
+    },
+    "status": { "enum": ["pass", "not-applicable"] },
+    "currentFidelityTier": { "enum": ["structural", "native-preview", "device-verified"] },
+    "nativeExecutionStarted": { "type": "boolean" },
+    "platforms": { "type": "array", "items": { "type": "object" } },
+    "providers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "platform", "status", "availableFidelityTier", "execution"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "platform": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["configured", "available", "not-configured", "host-required", "not-applicable"] },
+          "availableFidelityTier": { "enum": ["native-preview", "device-verified"] },
+          "execution": { "const": "explicit-only" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "captures": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "providerId", "platform", "screenId", "sourceFingerprint", "status", "fidelityTier"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "providerId": { "type": "string", "minLength": 1 },
+          "platform": { "type": "string", "minLength": 1 },
+          "screenId": { "type": "string", "minLength": 1 },
+          "stateId": { "type": "string" },
+          "sourceFingerprint": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["ready", "blocked", "failed", "stale"] },
+          "fidelityTier": { "enum": ["native-preview", "device-verified"] },
+          "artifacts": {
+            "type": "object",
+            "properties": {
+              "image": { "$ref": "#/$defs/relativePath" },
+              "semantics": { "$ref": "#/$defs/relativePath" },
+              "geometry": { "$ref": "#/$defs/relativePath" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "$defs": {
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?![A-Za-z]:[/\\\\])(?!.*(?:^|/)\\.\\.(?:/|$)).+$"
+    }
+  },
+  "additionalProperties": true
+}

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/schemas/ui-agent-job.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Elgreed/ui-design-workbench/schemas/ui-agent-job.schema.json",
+  "title": "UI Design Workbench portable agent job",
+  "type": "object",
+  "required": ["type", "version", "provider", "kind", "artifactDir", "allowedWrites", "sourceChangeAllowed"],
+  "properties": {
+    "type": { "const": "ui-design-workbench-agent-job" },
+    "version": { "enum": [1, 2, 3] },
+    "provider": { "type": "string" },
+    "kind": { "enum": ["expert", "proposal", "source-plan", "implementation"] },
+    "artifactDir": { "type": "string" },
+    "uiIrFile": { "type": "string" },
+    "contextFile": { "type": "string" },
+    "patchFile": { "type": "string" },
+    "contextBudget": { "type": "object" },
+    "scope": { "enum": ["all", "current"] },
+    "screenIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "acceptedFindingIds": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "allowedWrites": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "projectRoot": { "type": "string" },
+    "sourceTargets": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "sourceChangeAllowed": { "type": "boolean" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "implementation" } }, "required": ["kind"] },
+      "then": {
+        "properties": { "sourceChangeAllowed": { "const": true }, "sourceTargets": { "minItems": 1 } },
+        "required": ["projectRoot", "sourceTargets"]
+      },
+      "else": { "properties": { "sourceChangeAllowed": { "const": false } } }
+    }
+  ],
+  "additionalProperties": true
+}

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/schemas/ui-graph.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Elgreed/ui-design-workbench/schemas/ui-graph.schema.json",
+  "title": "UI Design Workbench source graph",
+  "type": "object",
+  "required": ["version", "graphType", "repoRoot", "summary", "screenTree", "nodes", "edges"],
+  "properties": {
+    "version": { "const": 1 },
+    "graphType": { "const": "ui-source-map" },
+    "repoRoot": { "type": "string" },
+    "project": { "type": "object" },
+    "detectedPlatforms": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "summary": {
+      "type": "object",
+      "required": ["nodes", "edges", "screens", "routes"],
+      "additionalProperties": { "type": "integer", "minimum": 0 }
+    },
+    "screenTree": { "type": "array" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "kind"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "enum": ["source", "screen", "route", "component", "token-file", "navigation-target"] }
+        },
+        "additionalProperties": true
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source", "target", "kind"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" },
+          "kind": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/schemas/ui-ir.patch.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Elgreed/ui-design-workbench/schemas/ui-ir.patch.schema.json",
+  "title": "UI Design Workbench sparse IR patch",
+  "type": "object",
+  "required": ["type", "version", "target", "operations"],
+  "properties": {
+    "type": { "const": "ui-design-workbench-ir-patch" },
+    "version": { "const": 1 },
+    "target": {
+      "type": "object",
+      "required": ["uiIrFile"],
+      "properties": {
+        "uiIrFile": { "type": "string", "minLength": 1 },
+        "project": { "type": ["string", "null"] },
+        "baselineHash": { "type": ["string", "null"] },
+        "reviewRevision": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "contextFile": { "type": ["string", "null"] },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["op", "value"],
+        "properties": {
+          "op": { "enum": ["upsert-findings", "upsert-versions", "merge-annotations", "record-verifications"] },
+          "value": { "type": "array" }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}