Metadata-Version: 2.4
Name: ui-design-workbench-cli
Version: 0.6.10
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)

Explore an application's screens and navigation in an interactive HTML preview built from its source code. No application build or launch is needed.

Use it to understand a project, inspect supported UI states, or request a separate UI/UX review. Parsing does not execute application logic or guarantee the same pixels as the running application.

![Review view: demo screen on the left and findings on the right](https://raw.githubusercontent.com/Elgreed/ui-design-workbench/v0.6.10/fixtures/golden/workbench-review/problems-wide.png)

*Review view of the bundled demonstration fixture. Findings belong to the separate review workflow.*

## Install

For source analysis and basic checks, install Python 3.10+ and [pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html), then run:

```sh
pipx install ui-design-workbench-cli
uidw --version
uidw doctor
```

`doctor` reports dependencies and cache settings. **Full browser checks additionally need Node.js 22+ and Chrome, Edge or Chromium.** Basic `--level quick` checks do not need them. To view the generated HTML, use a browser.

CLI use does not require an agent or MCP. For Codex and other agents, follow [agent setup](references/agent-integrations.md).

## First preview

Open a terminal in your application's root directory. These commands work in PowerShell and a POSIX shell:

```sh
uidw config setup --detail medium
uidw workbench --output-dir ../ui-preview --level quick --open
```

This example selects representative preview data (`medium`). Run `uidw config setup` without the option to choose interactively. The first command stores settings; the second writes `../ui-preview/ui-preview.html` and opens it. Check reports are under `../ui-preview/validation/`.

Look for `проверка pass` in the CLI output. If checks fail, HTML may still exist as a diagnostic preview: read the reports before treating reconstruction as complete. CLI messages are primarily Russian; the HTML interface supports English and Russian. Add `--lang en` to select English in the preview.

For absolute paths, Windows examples, detail levels and recovery steps, see [first run](references/getting-started.md).

## Choose the task

| Task | Command, from the application root |
| --- | --- |
| Explore screens without a UI/UX audit | `uidw workbench --output-dir ../ui-preview --level quick --open` |
| Include browser checks | `uidw workbench --output-dir ../ui-preview --level full --open` |
| Request a UI/UX review | `uidw review --output-dir ../ui-review --level full` |
| Check translation limits | `uidw fidelity report` |
| Inspect available adapters | `uidw fidelity capabilities` |
| Diagnose installation | `uidw doctor` |

`workbench` and `check` validate reconstruction. `review` requests UI/UX findings. Detail (`low/medium/high`) controls preview content; `--level quick/full` controls validation. No detail level starts a UI/UX audit.

See [using the preview](references/using-preview.md), `uidw --help` and `uidw help advanced` for further commands.

## Source support and accuracy

Each adapter supports a subset of its framework. Evidence below concerns small fixtures, not every platform configuration or application.

| Source | Supported examples | Limits and validation evidence |
| --- | --- | --- |
| HTML/CSS | Elements, simple selectors, spacing, linked stylesheets | Dynamic scripts and complex CSS limited; plain HTML fixture compared in a browser |
| React, Vue, Svelte, React Native | Recognized components, literal properties and supported styles | Arbitrary JavaScript not evaluated; source tests, not framework-wide runtime comparisons |
| Android Compose | Local components, literal themes/resources, preview arguments | Runtime Kotlin and custom drawing limited; selected YaDonor preview compared with Android capture |
| Android Views XML | Layouts, resources, navigation | Custom views and dynamic bindings limited; source tests |
| SwiftUI on iOS/macOS | Local views, literal values, ordered layout modifiers | Dynamic branches and some SF Symbols unresolved; source-only tests, no Apple runtime comparison |
| Storyboard/XIB | Recognized XML views and attributes | Runtime UIKit/AppKit behavior limited; source tests |
| WPF / WinUI XAML | Grid placement, literal thickness, colors and states | Complex templates/bindings limited; WPF fixture compared through WPF, WinUI not natively verified |
| Flutter | Nested widgets, literal constructors, insets and text styles | Arbitrary Dart and runtime state limited; fixture compared with the Flutter test engine |

Missing values and unsupported constructs are reported as gaps. Fonts, system controls and runtime data can change the result. Optional native Android/Apple discovery never launches an emulator or simulator automatically. See [accuracy details](references/fidelity.md) and [native rendering](references/native-rendering.md).

## Files and application source

Preview and review leave application source unchanged. Applying an accepted proposal is a separate action. The default cache lives outside the application repository; an explicit output directory receives HTML and reports. Export browser review state before moving the preview or clearing browser storage.

## Upgrade

For a pipx installation:

```sh
pipx upgrade ui-design-workbench-cli
uidw --version
```

For a managed skill copy, also run `uidw install-skill codex` (or your agent name) and start a new agent session. Linked development skills and separate MCP environments have different steps: see [agent upgrades](references/agent-integrations.md#upgrade-and-development-links).

## Documentation

**User guides:** [First run](references/getting-started.md) · [Using the preview](references/using-preview.md) · [Agent setup](references/agent-integrations.md) · [Troubleshooting](references/troubleshooting.md).

**Technical references (English):** [Fidelity](references/fidelity.md) · [Native rendering](references/native-rendering.md) · [Cache](references/cache-protocol.md) · [Components](references/component-catalog.md) · [IR schema](references/ir-schema.md) · [Review contract](references/review-workflow.md).

Current CLI version: `0.6.10`.
