uxaudit
UX/UI audit tool that captures screenshots and analyzes them with Gemini.
Highlights
- Full-page and section screenshots with evidence links.
- Multi-page crawling from header, nav, and footer.
- Structured JSON output for agents and pipelines.
Requirements
- Python 3.10+
- Playwright browsers:
playwright install - Gemini API key:
GEMINI_API_KEY(orGOOGLE_API_KEY)
Install
PyPI
python3 -m pip install uxaudit
Editable (dev)
python3 -m pip install -e .[dev]
Usage
export GEMINI_API_KEY="your-key"
uxaudit analyze https://example.com --model flash
Outputs are written to runs/<run_id>/ with manifest.json and report.json.
Redesign mode (visual alternatives)
Generate bold, visual redesign concepts plus NanoBanana-ready prompts:
uxaudit redesign https://example.com \\
--variants 4 \\
--goals "premium, conversion-focused" \\
--style-notes "bold typography, large imagery" \\
--constraints "keep logo, keep primary CTA"
Outputs are written to runs/<run_id>/ with redesign.json and a local preview
at redesign/index.html. By default, uxaudit auto-generates renders using
Gemini image generation (NanoBanana Pro) with the same API key. To skip auto
rendering, use --render-mode none. You can override the image model with
--render-model (default nano-banana-pro maps to gemini-3-pro-image-preview).
Save or replace visuals at redesign/concept-<page>-<index>.png
to update the preview.
Crawling multiple pages
uxaudit analyze https://example.com --max-pages 5
Style consistency analysis
By default uxaudit runs a cross-screenshot style consistency pass. You can disable it or tune the batch size:
uxaudit analyze https://example.com --no-style-consistency
uxaudit analyze https://example.com --style-consistency-batch-size 10
Login (form-based)
# Example with fake credentials
export UXAUDIT_AUTH_USERNAME="alex.rios@example.test"
export UXAUDIT_AUTH_PASSWORD="P@ssw0rd-Example-123"
uxaudit analyze https://demo.example.test \\
--auth-mode form \\
--auth-login-url https://demo.example.test/login \\
--auth-post-login-url https://demo.example.test/app \\
--auth-username-selector "#email" \\
--auth-password-selector "#password" \\
--auth-submit-selector "button[type=submit]" \\
--auth-success-selector ".dashboard"
Login (storage state)
uxaudit analyze https://app.example.com \\
--auth-mode storage_state \\
--auth-storage-state /path/to/storage_state.json
Development
ruff check .
ruff format .
mypy uxaudit
pytest
Project links
- Source: https://github.com/albertoburgosplaza/uxaudit
- Issues: https://github.com/albertoburgosplaza/uxaudit/issues
- Changelog: https://github.com/albertoburgosplaza/uxaudit/blob/main/CHANGELOG.md
CLI options
uxaudit analyze --help
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file uxaudit-0.2.0.tar.gz.
File metadata
- Download URL: uxaudit-0.2.0.tar.gz
- Upload date:
- Size: 31.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
d334a2701a4ba820e74f12d2eed85b8912e7ac0ca7f28e6d2d5a46e811d73e43
|
|
| MD5 |
a270b51fb2d9131c4ea5f649cae3ef19
|
|
| BLAKE2b-256 |
23a10f4496421866bcbd66b79196f5a33563037ebe5e1f5bba27036d7c4c86af
|
Provenance
The following attestation bundles were made for uxaudit-0.2.0.tar.gz:
Publisher:
release.yml on albertoburgosplaza/uxaudit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
uxaudit-0.2.0.tar.gz -
Subject digest:
d334a2701a4ba820e74f12d2eed85b8912e7ac0ca7f28e6d2d5a46e811d73e43 - Sigstore transparency entry: 785295180
- Sigstore integration time:
-
Permalink:
albertoburgosplaza/uxaudit@6206437b66ea1aeef8c7ab87855da94380e98fdd -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/albertoburgosplaza
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@6206437b66ea1aeef8c7ab87855da94380e98fdd -
Trigger Event:
push
-
Statement type:
File details
Details for the file uxaudit-0.2.0-py3-none-any.whl.
File metadata
- Download URL: uxaudit-0.2.0-py3-none-any.whl
- Upload date:
- Size: 32.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9f2a0422928486e93b9656a6cf57b2213e7909f551d4faafb4b4bdcb6b94a20a
|
|
| MD5 |
ca6bc70c1cdc08daae62a5ebd69b1480
|
|
| BLAKE2b-256 |
2acabdf85715f600bd7e568b396827ea1ca4f4869322f1c433f715731966abb0
|
Provenance
The following attestation bundles were made for uxaudit-0.2.0-py3-none-any.whl:
Publisher:
release.yml on albertoburgosplaza/uxaudit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
uxaudit-0.2.0-py3-none-any.whl -
Subject digest:
9f2a0422928486e93b9656a6cf57b2213e7909f551d4faafb4b4bdcb6b94a20a - Sigstore transparency entry: 785295191
- Sigstore integration time:
-
Permalink:
albertoburgosplaza/uxaudit@6206437b66ea1aeef8c7ab87855da94380e98fdd -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/albertoburgosplaza
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@6206437b66ea1aeef8c7ab87855da94380e98fdd -
Trigger Event:
push
-
Statement type:
