ui-design-workbench-cli 0.5.0__tar.gz

ui_design_workbench_cli-0.5.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: ui-design-workbench-cli
+Version: 0.5.0
+Summary: Repository UI indexing, graph, preview, and deterministic review CLI
+Author: Elgreed
+Project-URL: Homepage, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Repository, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Changelog, https://github.com/Elgreed/ui-design-workbench/blob/main/CHANGELOG.md
+Keywords: agent-skills,ui,ux,design-review,code-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+
+# UI Design Workbench
+
+[Русская версия](README.ru.md) · [Changelog](CHANGELOG.md) · [Release guide](RELEASING.md)
+
+Turn repository UI source into an offline interactive HTML workbench—without building or running the application.
+
+```text
+UI source → cached UI map → strict UI IR → interactive HTML
+```
+
+Use it to understand unfamiliar UI, inspect screens and navigation, verify a reconstruction, or run an explicit UI/UX review.
+
+## Install
+
+Requires Python 3.10+ and [`pipx`](https://pipx.pypa.io/).
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+`install-skill` also supports `claude`, `cursor`, `gemini`, `copilot`, `opencode`, `agents`, and `all`.
+
+Optional local MCP support:
+
+```sh
+pipx inject ui-design-workbench-cli "mcp>=2,<3"
+```
+
+Verify the installation:
+
+```sh
+uidw --version
+uidw doctor
+```
+
+## Quick start
+
+Choose preview detail once:
+
+```sh
+uidw --repo <repo> config setup
+```
+
+Build and open the source-derived workbench:
+
+```sh
+uidw --repo <repo> workbench --output-dir <artifacts> --level full --open
+```
+
+Run a UI/UX audit only when product critique is wanted:
+
+```sh
+uidw --repo <repo> review --output-dir <review-dir> --level full
+```
+
+`workbench` and `check` validate the projection. Only `review` creates UI/UX findings.
+
+## What it provides
+
+- Screen, route, component, token, theme, and state inventory.
+- Standalone HTML with source links and reconstructed navigation.
+- Incremental scans that reprocess only changed UI files.
+- Property-level evidence and explicit unsupported gaps instead of guessed UI.
+- Sparse review patches and a separate, authorized source-apply step.
+- Structural Android and Apple resource projection, plus discovery of available native capture paths.
+
+Supported source families include Web, React, Vue, Svelte, Jetpack Compose, Android Views XML, SwiftUI, Storyboard/XIB, WinUI/WPF, and Flutter.
+
+## Main commands
+
+| Command | Purpose |
+| --- | --- |
+| `uidw doctor` | Check installation and optional dependencies |
+| `uidw --repo <repo> context --json` | Read compact cached project context |
+| `uidw --repo <repo> scope ...` | Prepare bounded context for a screen or finding |
+| `uidw --repo <repo> patch ...` | Validate or apply sparse review-artifact changes |
+| `uidw --repo <repo> workbench ...` | Build and validate the HTML projection |
+| `uidw --repo <repo> native status` | Discover native Android/Apple render providers without running them |
+| `uidw --repo <repo> check ...` | Repeat projection checks without a UI/UX audit |
+| `uidw --repo <repo> review ...` | Start an explicit UI/UX review |
+| `uidw --repo <repo> fidelity ...` | Inspect source evidence and adapter limits |
+| `uidw --repo <repo> mcp` | Start the optional local stdio MCP server |
+
+Run `uidw help overview`, `uidw help advanced`, or `uidw <command> --help` for details.
+
+## Accuracy and safety
+
+- HTML is a static source projection, not proof of runtime or pixel parity.
+- Android and Apple translation remains structural until a source-matched native capture exists.
+- Unsupported bindings, custom drawing, runtime data, and platform behavior remain explicit gaps.
+- Preview and review keep application source read-only; applying a proposal is a separate step.
+- Derived cache and review state live outside the target repository by default.
+
+## Upgrade
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw install-skill codex
+```
+
+A Windows `.exe` is not published yet. PyPI + `pipx` is the primary cross-platform installation path.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Release and distribution guide](RELEASING.md)
+- [Agent integrations](references/agent-integrations.md)
+- [Fidelity contract](references/fidelity.md)
+- [Native rendering](references/native-rendering.md)
+- [IR schema](references/ir-schema.md)
+- [Review workflow](references/review-workflow.md)
+
+Current CLI version: `0.5.0`.

ui_design_workbench_cli-0.5.0/README.md

@@ -0,0 +1,114 @@
+# UI Design Workbench
+
+[Русская версия](README.ru.md) · [Changelog](CHANGELOG.md) · [Release guide](RELEASING.md)
+
+Turn repository UI source into an offline interactive HTML workbench—without building or running the application.
+
+```text
+UI source → cached UI map → strict UI IR → interactive HTML
+```
+
+Use it to understand unfamiliar UI, inspect screens and navigation, verify a reconstruction, or run an explicit UI/UX review.
+
+## Install
+
+Requires Python 3.10+ and [`pipx`](https://pipx.pypa.io/).
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+`install-skill` also supports `claude`, `cursor`, `gemini`, `copilot`, `opencode`, `agents`, and `all`.
+
+Optional local MCP support:
+
+```sh
+pipx inject ui-design-workbench-cli "mcp>=2,<3"
+```
+
+Verify the installation:
+
+```sh
+uidw --version
+uidw doctor
+```
+
+## Quick start
+
+Choose preview detail once:
+
+```sh
+uidw --repo <repo> config setup
+```
+
+Build and open the source-derived workbench:
+
+```sh
+uidw --repo <repo> workbench --output-dir <artifacts> --level full --open
+```
+
+Run a UI/UX audit only when product critique is wanted:
+
+```sh
+uidw --repo <repo> review --output-dir <review-dir> --level full
+```
+
+`workbench` and `check` validate the projection. Only `review` creates UI/UX findings.
+
+## What it provides
+
+- Screen, route, component, token, theme, and state inventory.
+- Standalone HTML with source links and reconstructed navigation.
+- Incremental scans that reprocess only changed UI files.
+- Property-level evidence and explicit unsupported gaps instead of guessed UI.
+- Sparse review patches and a separate, authorized source-apply step.
+- Structural Android and Apple resource projection, plus discovery of available native capture paths.
+
+Supported source families include Web, React, Vue, Svelte, Jetpack Compose, Android Views XML, SwiftUI, Storyboard/XIB, WinUI/WPF, and Flutter.
+
+## Main commands
+
+| Command | Purpose |
+| --- | --- |
+| `uidw doctor` | Check installation and optional dependencies |
+| `uidw --repo <repo> context --json` | Read compact cached project context |
+| `uidw --repo <repo> scope ...` | Prepare bounded context for a screen or finding |
+| `uidw --repo <repo> patch ...` | Validate or apply sparse review-artifact changes |
+| `uidw --repo <repo> workbench ...` | Build and validate the HTML projection |
+| `uidw --repo <repo> native status` | Discover native Android/Apple render providers without running them |
+| `uidw --repo <repo> check ...` | Repeat projection checks without a UI/UX audit |
+| `uidw --repo <repo> review ...` | Start an explicit UI/UX review |
+| `uidw --repo <repo> fidelity ...` | Inspect source evidence and adapter limits |
+| `uidw --repo <repo> mcp` | Start the optional local stdio MCP server |
+
+Run `uidw help overview`, `uidw help advanced`, or `uidw <command> --help` for details.
+
+## Accuracy and safety
+
+- HTML is a static source projection, not proof of runtime or pixel parity.
+- Android and Apple translation remains structural until a source-matched native capture exists.
+- Unsupported bindings, custom drawing, runtime data, and platform behavior remain explicit gaps.
+- Preview and review keep application source read-only; applying a proposal is a separate step.
+- Derived cache and review state live outside the target repository by default.
+
+## Upgrade
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw install-skill codex
+```
+
+A Windows `.exe` is not published yet. PyPI + `pipx` is the primary cross-platform installation path.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Release and distribution guide](RELEASING.md)
+- [Agent integrations](references/agent-integrations.md)
+- [Fidelity contract](references/fidelity.md)
+- [Native rendering](references/native-rendering.md)
+- [IR schema](references/ir-schema.md)
+- [Review workflow](references/review-workflow.md)
+
+Current CLI version: `0.5.0`.

ui_design_workbench_cli-0.5.0/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ui-design-workbench
+description: Reconstruct, review, generate, or redesign repository UI as standards-aware interactive HTML previews; optionally guide ordinary UI implementation for Android, iOS, macOS, Windows, Flutter, or Web. Do not use when the user only wants to run the real application.
+metadata:
+  compatibility: "Python 3.10+. MCP is optional; CLI works standalone."
+---
+
+# UI Design Workbench router
+
+Use UIDW as a deterministic local utility. The CLI, not the skill prompt, owns scanning, cache invalidation, source graphs, IR, rendering, and projection checks.
+
+## 1. Get compact context
+
+Prefer MCP tools `ui_project` then `ui_scope` when the local UIDW MCP is configured. Otherwise use the complete CLI fallback:
+
+```text
+uidw --repo <repo> context --json
+uidw --repo <repo> scope --ir <ui-ir.json> --screen <id> --budget 4000
+```
+
+If `uidw` is unavailable, run `python <skill-dir>/scripts/uidw.py ...`. Reuse a clean cache. Never paste or read the complete `ui-ir.json` when a scoped context can answer the task. Request another screen/finding scope only when needed.
+
+If first-use context says `setupRequired`, ask only for `low`, `medium`, or `high` using its short descriptions. Mock-data depth follows that choice. Do not recommend a level. Optional `uiMode` remains off until explicitly enabled.
+
+## 2. Route the request
+
+- Reconstruct/generate/redesign: read [references/design-modes.md](references/design-modes.md), then only the matching platform section from [references/platform-standards.md](references/platform-standards.md). Use cached evidence and `uidw workbench`; validate transfer fidelity, not product UX. For Android or Apple visual accuracy also read [references/native-rendering.md](references/native-rendering.md) and call MCP `ui_native_status` (or `uidw native status`).
+- Explicit review/audit/critique: read [references/ui-reviewer.md](references/ui-reviewer.md) and [references/review-workflow.md](references/review-workflow.md). Review immutable Before only and work in bounded screen batches.
+- Workbench chrome behavior: read [references/workbench-ui.md](references/workbench-ui.md).
+- Ordinary UI source task with `uiMode.enabled=true`: read [references/ui-guidance-mode.md](references/ui-guidance-mode.md). Do not create a preview or review unless requested.
+- Cache/install/agent integration question: read only [references/cache-protocol.md](references/cache-protocol.md) or [references/agent-integrations.md](references/agent-integrations.md), respectively.
+
+## 3. Return sparse changes
+
+Review/proposal agents write `ui-ir.patch.json`, never a replacement full IR:
+
+```text
+uidw patch validate <ui-ir.patch.json> --ir <ui-ir.json>
+uidw patch apply <ui-ir.patch.json> --ir <ui-ir.json> --output <ui-ir.proposed.json>
+```
+
+Allowed operations are `upsert-findings`, `upsert-versions`, `merge-annotations`, and `record-verifications`. Baseline screens, nodes, tokens, themes, fixtures, and application source are immutable in this path. Create one restrained proposal by default; add a second only for a real UX tradeoff.
+
+## Invariants
+
+- Reconstruction, generation, redesign, Low/Medium/High, `workbench`, and `check` never trigger an automatic UI/UX audit. Only an explicit review request creates findings.
+- Do not run the target app, emulator, simulator, build, or dev server unless separately requested. Headless checks may open only generated local HTML.
+- Preserve discovered screens, routes, project components, platform idioms, tokens, themes, states, provenance, and unsupported gaps. Do not invent polish or browser-default replacements.
+- HTML is a projection. Base IR is immutable Before; proposal versions are sparse overrides.
+- Android/Apple source translation is structural-only until a source-matched native capture exists. Never call HTML a native render.
+- Applying a proposal to real source requires a separate explicit `Apply to project` or direct-fix authorization, bounded source targets, incremental sync, and targeted verification. Never repeat the full AI review automatically.
+- Keep cache and review artifacts outside source control unless the user explicitly requests otherwise.

ui_design_workbench_cli-0.5.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ui-design-workbench-cli"
+version = "0.5.0"
+description = "Repository UI indexing, graph, preview, and deterministic review CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Elgreed" }]
+keywords = ["agent-skills", "ui", "ux", "design-review", "code-analysis"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+uidw = "uidw:main"
+uidw-mcp = "uidw_mcp:main"
+
+[project.optional-dependencies]
+mcp = ["mcp>=2,<3"]
+
+[project.urls]
+Homepage = "https://github.com/Elgreed/ui-design-workbench"
+Repository = "https://github.com/Elgreed/ui-design-workbench"
+Changelog = "https://github.com/Elgreed/ui-design-workbench/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = { "" = "scripts" }
+py-modules = [
+  "uidw",
+  "uidw_mcp",
+  "scoped_context",
+  "android_xml_support",
+  "scan_ui",
+  "ir_contracts",
+  "fidelity_core",
+  "fidelity_adapter_api",
+  "fidelity_adapters",
+  "fidelity_platform_adapters",
+  "android_resource_resolver",
+  "apple_resource_resolver",
+  "native_render_contracts",
+  "native_render_android",
+  "native_render_apple",
+  "native_render_registry",
+  "quality_common",
+  "render_preview",
+  "coverage_report",
+  "validate_platform_profiles",
+]
+
+[tool.setuptools.data-files]
+"share/ui-design-workbench" = ["SKILL.md"]
+"share/ui-design-workbench/references" = ["references/*.md", "references/platform-profiles.json"]
+"share/ui-design-workbench/schemas" = ["schemas/*.json"]
+"share/ui-design-workbench/scripts" = [
+  "scripts/android_resource_resolver.py",
+  "scripts/android_xml_support.py",
+  "scripts/apple_resource_resolver.py",
+  "scripts/coverage_report.py",
+  "scripts/fidelity_adapter_api.py",
+  "scripts/fidelity_adapters.py",
+  "scripts/fidelity_core.py",
+  "scripts/fidelity_platform_adapters.py",
+  "scripts/generate_interaction_matrix.py",
+  "scripts/ir_contracts.py",
+  "scripts/merge_review_state.py",
+  "scripts/native_render_android.py",
+  "scripts/native_render_apple.py",
+  "scripts/native_render_contracts.py",
+  "scripts/native_render_registry.py",
+  "scripts/quality_common.py",
+  "scripts/render_preview.py",
+  "scripts/scan_ui.py",
+  "scripts/scoped_context.py",
+  "scripts/smoke_preview.js",
+  "scripts/uidw.py",
+  "scripts/uidw_mcp.py",
+  "scripts/validate_platform_profiles.py",
+  "scripts/visual_regression.py",
+]

ui_design_workbench_cli-0.5.0/references/adapter-api.md

@@ -0,0 +1,20 @@
+# Fidelity adapter API
+
+Fidelity adapters are deterministic, read-only translators from repository source to UI IR. They do not run the application, a browser dev server, an emulator, or a build.
+
+`SourceContext` contains the repository root, relative source path, text, detected platforms, and scanner role. An adapter exposes a stable `id`, `supports(context)`, and `translate(context) -> AdapterResult`. Results contain screens, nodes, tokens, themes, component mappings, and an explicit unsupported-expression list. Register additional adapters with `register_adapter`; the scanner consumes the registry rather than importing provider-specific agents.
+
+Every reconstructed visual or behavioral property must have a same-path entry in `node.provenance`, for example `style.background` or `layout.padding`. Evidence records have a stable hash ID, source file and line, original expression, adapter ID, and one of `exact`, `high`, `approximate`, or `unsupported`. Unsupported syntax is reported rather than guessed.
+
+The built-in adapters are:
+
+- `web`: static HTML plus deterministic simple CSS selectors, CSS custom properties, inline styles, semantic controls, lists, images, and text;
+- `react-jsx`, `vue`, `svelte`: source markup projected through the Web contract; dynamic expressions and unmapped project components remain unsupported;
+- `compose`: Android `@Composable` screens, common Material/Compose primitives, resources, modifiers, and tokens;
+- `android-xml`: Android layout/resources XML, common Views/Material controls, dimensions/colors, and `values-night` token overrides;
+- `swiftui`: iOS/macOS `View` bodies, common containers and controls, Asset Catalog resources, localization, SF Symbol fallbacks, modifiers, and source tokens;
+- `apple-interface-xml`: Storyboard/XIB controllers and common UIKit/AppKit views with assets, authored frames, and a conservative Auto Layout subset;
+- `xaml`: WinUI/WPF pages, common controls, resources, and basic layout/style attributes without evaluating bindings or templates;
+- `flutter`: common Material/Cupertino widget trees and basic dimensions without executing Dart.
+
+Golden source/expected fixtures live under `fixtures/golden`. Changing adapter output requires an intentional fixture update and the fidelity test suite. `uidw fidelity capabilities` returns the same installed matrix in machine-readable JSON.

ui_design_workbench_cli-0.5.0/references/agent-integrations.md

@@ -0,0 +1,39 @@
+# Agent integrations
+
+The repository follows the open Agent Skills layout: one `SKILL.md` plus `scripts/`, `references/`, and optional agent-specific metadata. The core workflow communicates through files and shell commands, not a proprietary API.
+
+## Discovery locations
+
+`~/.agents/skills/ui-design-workbench` is the preferred portable installation where supported. Native locations are also available:
+
+| Agent | Native user location |
+| --- | --- |
+| Codex | `~/.codex/skills/ui-design-workbench` |
+| Claude Code | `~/.claude/skills/ui-design-workbench` |
+| Cursor | `~/.cursor/skills/ui-design-workbench` |
+| Gemini CLI | `~/.gemini/skills/ui-design-workbench` |
+| GitHub Copilot CLI | `~/.copilot/skills/ui-design-workbench` |
+| OpenCode | `~/.config/opencode/skills/ui-design-workbench` |
+
+Install the published CLI and then copy its packaged Agent Skill into any supported discovery location:
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+Use `uidw install-skill all` for every supported location. Repeating the command refreshes UIDW-managed copies after a CLI upgrade and refuses to overwrite an unrelated existing skill. The packaged skill includes its references, schemas, and CLI fallback scripts, so it does not depend on a Git checkout.
+
+For contributor checkouts, `./install.ps1 -Agent all` on Windows or `./install.sh all` on macOS/Linux still creates development links to the repository. Repository-local installation can use `.agents/skills/ui-design-workbench` when team policy prefers checked-out skills.
+
+## Capability contract
+
+An agent needs local file read/write access and Python 3.10+. Node.js plus Chromium/Edge is optional but required for headless interaction and geometry diagnostics. The target application, emulator, simulator, bridge server, and internet access are not required.
+
+The portable handoff is `ui-agent-job.json`. It contains artifact directory, review scope, selected stable finding IDs, screen IDs, active/baseline versions, annotations, allowed output patterns, and `sourceChangeAllowed: false`. It also points to a bounded `ui-agent-context.json` and a sparse `ui-ir.patch.json`; the agent reads the bounded context and returns patch operations instead of loading or replacing the complete IR. Agents must modify only the declared review artifacts and return validation results.
+
+For ordinary source tasks, `uidw init` can opt a project into lightweight UI guidance. The mode is off by default and appears in `ui-context.json` as `uiMode`. A compatible agent loads only the relevant platform guidance, preserves the project's components and tokens, and stays within the requested implementation scope. This is independent of the review handoff and must not create a workbench or claim a full audit unless requested.
+
+Codex may opt into `render_preview.py --agent codex`, which enables the official local `codex://new` preparation path. Other agents use copied prompts or the JSON job. Provider-specific adapters are optional presentation conveniences and must not change the IR, cache, review semantics, permissions, or approval boundary.
+
+The optional `uidw-mcp` stdio server is a transport facade over the same deterministic CLI core. It exposes compact project discovery, bounded screen/finding context, job preparation, sparse patch application, preview building, and fidelity explanation. MCP is an optional dependency; installing or running the regular CLI must not require it. Configure an agent to launch `uidw-mcp --repo <absolute-project-path>` as a local stdio command; it opens no port and keeps all project data on the local machine.

ui_design_workbench_cli-0.5.0/references/cache-protocol.md

@@ -0,0 +1,61 @@
+# Project context and cache protocol
+
+The cache accelerates discovery; it is never authoritative application data and never replaces source evidence.
+
+## Storage model
+
+The default is a user-level, project-keyed operating-system cache:
+
+- Windows: `%LOCALAPPDATA%\UI Design Workbench\Cache\projects\<project-key>`
+- macOS: `~/Library/Caches/ui-design-workbench/projects/<project-key>`
+- Linux: `$XDG_CACHE_HOME/ui-design-workbench/projects/<project-key>` or `~/.cache/ui-design-workbench/projects/<project-key>`
+
+Set `UIDW_CACHE_HOME` for an isolated runner. The per-project `config.json` lives in this user cache by default. `init --project-cache` is an explicit opt-in that instead creates `.ui-design-workbench/config.json` and an ignore-all `.gitignore` inside the repository. Commit only a deliberately shared config or exported semantic UI map; never commit fingerprints, per-file records, timestamps, diagnostics, screenshots, or agent-local paths.
+
+The project key is derived from the normalized absolute repository path. The installed skill contains only reusable code and reference data; it must not contain project caches.
+
+## State files
+
+- `cache-state.json`: scanner/config versions, candidate manifest, content fingerprints, and reusable per-file analysis.
+- `ui-scan.json`: aggregated UI inventory from current per-file records.
+- `ui-ir.json`: synchronized projection combining the generated source index with preserved authored detail; still not a finished review deliverable.
+- `design-model.json`: durable authored screen/node/scenario detail preserved across source-index refreshes.
+- `review-state.json`: findings, annotations, decisions, and proposal metadata preserved separately from discovery.
+- `ui-context.json`: bounded model-facing summary with changed files and priority reads.
+- `ui-context-<screen>.json`: one screen subtree and its directly referenced sources.
+- `sync-report.json`: last invalidation reason, changed files, and affected screen IDs.
+- `config.json`: cache preferences, the opt-in `uiMode.enabled` flag, and derived `mockData.mode`. Mock data is always enabled and follows detail level: `minimal`, `representative`, or `exhaustive`; it is not a separate preference.
+
+## Commands
+
+```text
+uidw --repo <repo> init
+uidw --repo <repo> status --json
+uidw --repo <repo> sync
+uidw --repo <repo> context --screen <screen-id> --json
+uidw --repo <repo> context --screen <screen-id> --budget 4000 --format markdown
+uidw --repo <repo> map --output <docs-or-artifact-dir>/ui-graph.json
+uidw --repo <repo> diff
+uidw --repo <repo> workbench --output-dir <artifact-dir>
+uidw --repo <repo> check --ir <artifact-dir>/ui-ir.json --level full
+uidw --repo <repo> doctor --json
+uidw --repo <repo> ui-mode --enable
+```
+
+`init`, `sync`, `context`, `map`, and cache-backed workbench/review entry points share one internal `ensure_initialized` bootstrap. The first ordinary `context` or `review` request creates the default user-cache configuration, UI index, graph, and starter IR automatically; manual `init` is not required. Each result exposes `initialization.status` as `created`, `updated`, `reused`, or `stale`. Later calls reuse the existing cache and do not analyze unchanged source files. Use `sync --force` after scanner/schema upgrades or known discovery errors. Use `--verify-content` when timestamps may be unreliable, such as restored archives or unusual network filesystems.
+
+## Invalidation
+
+Candidate files use size, nanosecond mtime, and SHA-256. Unchanged metadata reuses the existing digest; changed metadata is rehashed. The manifest watches broad source candidates so that newly added UI files can be discovered, but `changedUiFiles` contains only records classified as UI or paths already referenced by the UI inventory. Non-UI source changes refresh manifest metadata without invalidating the UI cache. Only added or content-modified UI files are analyzed again. Removed UI files drop their cached record. A theme or navigation change invalidates all screens; a screen/component change invalidates mapped dependents; scanner/config/cache-version changes force full reconstruction.
+
+Metadata-only changes update the manifest without rescanning. `--verify-content` rehashes every candidate when correctness is more important than I/O cost.
+
+Every JSON write uses a same-directory temporary file plus atomic replacement. A short-lived project state lock serializes concurrent writers. Configuration schema upgrades keep `config.v<old>.backup.json`; disposable scanner/cache versions rebuild automatically. Source changes never discard authored scenarios, proposals, findings, or annotations: bindings for impacted screens and nodes are retained with `sourceState: stale` until an agent reconciles them.
+
+Do not run a watcher, bridge server, emulator, or target application. Lazy command-boundary synchronization is deterministic, portable, and inexpensive for agent workflows.
+
+Interactive `init` asks only for detail level and does not recommend or preselect a value. Automatic non-interactive initialization writes only the neutral technical config and never guesses a detail level: compact context reports `configuration.setupRequired` and one concise `questionsForUser` item until the user answers it. Use `config setup`, `config show`, or `config set detail <low|medium|high>` without rescanning unchanged UI files. `help config` describes the levels and `about` explains the tool boundary.
+
+UI guidance is not asked during setup and remains off unless explicitly enabled. `init --ui-mode` and `init --no-ui-mode` make automation deterministic. Later use `ui-mode --enable`, `ui-mode --disable`, or `config set ui-mode on|off`. Enabling guidance changes agent behavior only for UI-related tasks and does not imply review, redesign, preview generation, or source-edit permission.
+
+Mock data follows detail level automatically: `low` uses `minimal`, `medium` uses `representative`, and `high` uses `exhaustive`. This derived change refreshes model context but never causes another repository source scan by itself. Preserve existing `scenarioFixtures` and `screen.scenarios` for unaffected screen IDs during incremental sync; regenerate only fixtures whose source dependencies changed.

ui_design_workbench_cli-0.5.0/references/design-modes.md

@@ -0,0 +1,109 @@
+# Generation and redesign modes
+
+Choose one explicit `design.mode` before producing IR.
+
+| Mode | Source of truth | Allowed creativity | Required fidelity status |
+| --- | --- | --- | --- |
+| `reconstruct` | Existing repository UI | None; report gaps separately | `translated` |
+| `generate` | Product brief + project system + platform standards | Only reasoned choices within constraints | `designed` |
+| `redesign` | Existing task flow/content + approved brief + standards | Improve named UX problems; preserve unrelated behavior | `designed` |
+
+## Anti-randomness contract
+
+Every visible or interactive decision must come from at least one of:
+
+1. a literal project component, asset, token, or established pattern;
+2. an official platform component or documented interaction pattern;
+3. an explicit user/product requirement;
+4. a `design.decisions` record with alternatives considered and a concrete UX reason.
+
+Do not add gradients, glass effects, floating cards, oversized headings, novel navigation, decorative illustrations, animations, icon-only actions, or extra product copy merely to make a design look modern. If no product-specific visual direction exists, produce the restrained native baseline first.
+
+## Design metadata
+
+Generated and redesigned IR includes:
+
+```json
+{
+  "design": {
+    "mode": "redesign",
+    "targetPlatforms": ["android", "ios", "web"],
+    "brief": {
+      "primaryTask": "Complete checkout with minimal uncertainty",
+      "primaryUser": "Existing customer",
+      "constraints": ["Preserve current fields", "No new backend data"]
+    },
+    "standardProfiles": {
+      "android": {"id": "material3", "source": "official", "projectVersion": "from repository"},
+      "ios": {"id": "apple-hig", "source": "official", "deploymentTarget": "from repository"},
+      "web": {"id": "web-platform", "source": "WCAG 2.2 AA + APG"}
+    },
+    "decisions": [
+      {
+        "id": "decision-checkout-summary",
+        "scope": "checkout/summary",
+        "choice": "Keep order summary visible before confirmation",
+        "basis": "user-task",
+        "reason": "Reduces uncertainty before a consequential action",
+        "alternatives": ["Collapsed summary"]
+      }
+    ],
+    "stateMatrix": [
+      {
+        "screens": ["checkout"],
+        "covered": ["default", "loading", "error", "disabled", "success", "destructive-confirmation"],
+        "notApplicable": [
+          {"state": "empty", "reason": "An empty cart cannot enter checkout."},
+          {"state": "offline", "reason": "Handled by the shared network-error screen."},
+          {"state": "permission", "reason": "No system permission is requested."}
+        ]
+      }
+    ]
+  },
+  "fidelity": {"status": "designed", "sourceDerived": false}
+}
+```
+
+Use a `project` standard profile only when the repository has an intentional component system. Include a `reason` describing the override. Do not call a collection of incidental styles a design system.
+
+## Generate workflow
+
+1. Inspect the repository for brand tokens, components, navigation architecture, localization, assets, dependencies, and supported platforms. If no repository exists, derive only the minimum product brief needed to proceed.
+2. Define the primary task, user, content, data dependencies, constraints, success outcome, and target platforms. Separate known facts from assumptions.
+3. Create the task flow and screen/state inventory before visual styling. Avoid adding screens that do not advance the task or satisfy a platform requirement.
+4. Map each control and navigation container to the target platform profile. Add brand through shared semantic tokens, not per-screen decoration.
+5. Design representative default, loading, empty, error, offline/permission, disabled, success, destructive-confirmation, and long-content states where applicable. Record non-applicable states with a reason.
+6. Generate all screens, routes, transitions, focus behavior, and state actions in IR. Run the audit before presenting HTML.
+
+## Redesign workflow
+
+1. Reconstruct the current screen, task flow, content semantics, and states first. Preserve provenance to original files and symbols.
+2. Write a short problem statement based on user feedback, explicit requirements, or observable heuristic violations. Do not redesign merely because a different style is possible.
+3. Mark invariants: business rules, required fields, route contracts, analytics hooks, accessibility labels, data availability, and already accepted areas.
+4. Create a native-baseline redesign that fixes the stated problems. Keep each changed region linked to a `decisionId`; unchanged regions remain source-linked.
+5. Offer an additional variant only when it represents a meaningful tradeoff, not cosmetic randomness. State the tradeoff and keep content/functionality comparable.
+6. Present the redesigned preview without editing project source. After approval, propose an implementation diff separately.
+
+## Expert review workflow
+
+An expert review is a staged reconstruction plus redesign, not a fourth rendering mode. First reconstruct the existing UI as the immutable baseline. Record evidence-based findings under `review.audit` using [ui-reviewer.md](ui-reviewer.md). Then set `design.mode: redesign` for correction versions and link each version to the findings it addresses. This keeps current-state fidelity separate from proposed design judgment.
+
+Do not produce correction variants until the audit defines the problem, evidence, affected task, and preserved invariants. Do not treat a standards deviation as a defect when the repository documents an intentional, accessible project convention that serves the task.
+
+## UX completeness gate
+
+Before review, verify:
+
+- clear primary task and visual hierarchy;
+- predictable navigation, back/cancel behavior, and preserved context;
+- feedback for taps, submissions, waiting, completion, and failure;
+- prevention and recovery for destructive or costly actions;
+- form labels, instructions, validation timing, error placement, and retained user input;
+- empty/loading/error/offline/permission states where relevant;
+- light/dark and text scaling where supported;
+- keyboard/focus/assistive semantics and target sizes;
+- resolvable foreground/background tokens that pass WCAG text-contrast thresholds in each reviewed theme;
+- responsive/adaptive layouts, safe areas, RTL, localization expansion, and long content;
+- no unsupported data, product copy, feature, or backend behavior invented by the design.
+
+The HTML preview is evidence for review, not proof of runtime accessibility. Report which checks are structural and which still require platform testing after implementation.