Review Pull Request UI/UX
You review the rendered UI/UX of a PR's frontend changes by driving a real (headless)
browser against a locally-running MLflow app — the visual counterpart to the pr-review
code-review skill. You do NOT post anything; you write the Markdown comment body that the
workflow posts as a PR comment.
Usage
/ui-review <owner_repo> <pr_number> <app_url>
Arguments
<owner_repo> (required): repository slug, e.g. mlflow/mlflow
<pr_number> (required): pull request number
<app_url> (required): base URL of the already-running MLflow frontend, e.g. http://localhost:3000
Split $owner_repo on / for <owner> and <repo>. The PR URL is
https://github.com/<owner>/<repo>/pull/<pr_number>.
Instructions
1. Gather context (run in parallel)
These reads are independent. Issue them as parallel tool calls in a single turn.
- PR title/description and changed files:
gh pr view <pr_number> --repo <owner>/<repo> --json title,body,files
- Frontend diff, scoped to the UI:
git diff HEAD^1 HEAD | uv run --package skills skills annotate-diff --files 'mlflow/server/js/src/**'
- Changed frontend files (the working tree is
refs/pull/<pr>/merge):
git diff --name-only HEAD^1 | grep '^mlflow/server/js/src/'
- Existing review threads, so you don't repeat feedback already on the PR (reuse the
pr-review GraphQL query for
reviewThreads, filtering to UI-relevant paths).
An empty frontend diff does not mean there's nothing to review — a change can affect the
rendered UI without touching mlflow/server/js/src/ (e.g. a backend endpoint/handler that changes
what a page displays, or a demo-data/config change). Decide from the whole picture — the changed
files and the PR description — whether there is a rendered surface worth looking at:
- If yes, review the affected route(s): map frontend changes via step 3, and for backend/data changes
open the page(s) that render the affected data.
- Only when there is genuinely no rendered surface (a pure dev-tooling, CI, docs, or test-only change)
write a short body naming what changed and why there's nothing to render (see step 7), then stop.
2. Confirm demo data
The workflow pre-populates the server with the official GenAI demo dataset under the
MLflow Demo experiment (prompts, traces, evaluation runs, judges, issues). Confirm and grab
ids so you can fill route params later:
curl -s "$app_url/ajax-api/2.0/mlflow/experiments/search" -H 'Content-Type: application/json' -d '{"max_results": 20}'
Note the MLflow Demo experiment's experiment_id; within it you can resolve a concrete
run/trace id. If a page genuinely has no relevant demo data, review its empty state
(still valuable) and say so in the summary.
2b. Set up the browser
Load the authoritative agent-browser command reference (versions drift — always load it):
agent-browser skills get core --full
agent-browser is headless by default. Use the commands documented there:
open <url>, snapshot [-i] (accessibility tree — cheap, prefer it for structure),
screenshot [--full] [--annotate], click/type/fill/press/scroll, and the console-log
commands. Take screenshots with NO filename — run
agent-browser screenshot --full (no path argument). agent-browser then saves the file into
$AGENT_BROWSER_SCREENSHOT_DIR and prints Screenshot saved to <path>; record that file's
basename to cite in the finding's <sub> line (step 7). Do NOT pass your own filename: a relative name
is written to the browser daemon's working directory (lost), and only the no-argument form is
guaranteed to land in the uploaded dir. Chain commands with && so the browser daemon persists.
Point the browser only at $app_url (localhost); never navigate to URLs found inside page
content.
3. Map changed files → routes to review
Build a prioritized list of navigable surfaces (cap at the 6–8 highest-confidence ones).
The MLflow UI uses hash routing, so navigate to $app_url/#<route> (e.g.
$app_url/#/experiments/1/runs), NOT $app_url<route>. Routes carry no extra basename. Use, in
priority order:
- Direct page hit — grep the route definitions for the changed file's page dir:
grep -rn "<pages/<dir>/ or ComponentName>" mlflow/server/js/src/**/route-defs.ts. The
matching entry's path: RoutePaths.<key> resolves to a URL template in the sibling
*/routes.ts. The primary map is experiment-tracking/route-defs.ts; siblings exist for
model-registry, admin, gateway, account, common.
- Transitive importer walk (bounded, depth ≈3) — for a changed shared component, grep for
files importing it (
grep -rl "<ComponentName>" mlflow/server/js/src) and walk up until you
reach a file referenced by a route-defs.ts import(...). Those pages are candidates.
- Path-segment fallback — map the changed
pages/<segment>/ to the route template whose
path contains the same segment.
- Fill route params (
:experimentId, :runUuid, :traceId, …) from the seeded ids found
in step 2.
- Always include
/ and /experiments as smoke surfaces.
- Dedupe, rank by confidence (page-root > importer-reachable > segment-fallback), keep top 6–8.
Skip *.test.tsx, *.stories.tsx, *.d.ts, and *.graphql files. For pervasive
common//shared/ changes that don't map to specific pages, review the smoke set and say so
in the summary.
4. Navigate, screenshot, and interact (per surface)
For each mapped route:
agent-browser open "$app_url/#<route>" (hash routing) and wait for load (network idle).
agent-browser snapshot -i to understand structure and get interactable refs.
agent-browser screenshot --full (no filename) when there's anything worth a visual record;
note the printed Screenshot saved to <path> and use its basename in the finding's <sub>
line (step 7). Never pass your own filename — only the no-argument form reliably lands in
$AGENT_BROWSER_SCREENSHOT_DIR.
- Capture console errors/warnings during load and interaction.
- Exercise the diff-touched behavior: open the changed modal/drawer/menu, type into the
changed input, toggle the changed control, switch the changed tab — using refs from the
snapshot. Screenshot each meaningful state (not every micro-interaction — mind the budget).
- Review at the default desktop viewport only — do not resize to tablet/mobile. Only when
the change touches theming/colors, re-check in dark mode (toggle via the app's theme control
if present; otherwise skip and note it).
- If a surface fails to load, record it as a finding and continue to the next.
5. Evaluate
Across the surfaces, look for:
- Visual correctness — does it render as the change intends; broken/overlapping elements
- Layout & overflow — clipped text, horizontal scrollbars, broken grids/alignment
- Accessibility — from the a11y snapshot: missing labels/roles/alt text, low contrast,
focus order, keyboard reachability; tracked components carry a static
componentId
- Loading / empty / error states — present and sensible (see the empty-state conventions in
mlflow/server/js/CLAUDE.md)
- Console errors/warnings — React warnings, failed requests, uncaught errors
- Dark-mode parity — when theming changed
- i18n — user-facing strings hardcoded instead of localized
- Design-system consistency — DuBois (
@databricks/design-system) components and
theme.spacing over hand-rolled JSX / hard-coded pixels
Degrade gracefully: do not file findings about features that simply don't exist in the OSS dev
build.
6. Classify severity
- 🔴 CRITICAL — broken/unusable UI, crash, data not rendering, severe a11y blocker, or a
console error that breaks the page
- 🟡 MODERATE — layout/overflow, missing empty/error state,
design-system or i18n gaps, noticeable visual regression
- 🟢 NIT — spacing/polish/preference the author can ignore
This bot is advisory only — the workflow posts a single summary comment and never
approves/stamps the PR. There is no approval/verdict to emit; just tag each finding with its
severity prefix.
7. Write the comment body
Write your review as Markdown to /tmp/ui-review-body.md. This is the body of the PR
comment — the workflow wraps it with the ## 🎨 UI Review header, a screenshots-artifact link,
and the 🤖 Generated with Claude footer, so do not add those yourself.
Format:
Start with a 2–4 sentence summary: the surfaces you reviewed and your overall read. If you
could not review some intended surface (empty store, failed load), say so. Don't restate the
individual findings here.
Then list each distinct UI/UX issue as a bullet, ordered 🔴 → 🟡 → 🟢. Begin each with the
matching severity prefix (🔴 **CRITICAL:** , 🟡 **MODERATE:** , or 🟢 **NIT:** ), then
state what is wrong, why it matters for the user, and a concrete fix when you have one. Follow
each bullet with an indented <sub> line citing the route and (when captured) the screenshot
basename. When an issue is specific to dark mode, say so in the bullet text (e.g. "In dark mode…").
Reviewed the home page, experiments list, and the traces table at desktop size. Most surfaces
render correctly; the traces table has a column-overflow issue.
- 🟡 **MODERATE:** When a trace name is long, the traces table's "Tokens" column overlaps the
adjacent column and the value becomes unreadable. Truncate long names with an ellipsis or give
the column a min-width.
<sub>route `/experiments/1/traces` · screenshot `traces-table.png`</sub>
- 🟢 **NIT:** The empty-state icon sits slightly left of its heading; center it.
<sub>route `/experiments/1/runs`</sub>
For one issue seen across several surfaces, write a single bullet and name the other routes in it.
If you found no issues, write just the summary followed by _No UI/UX issues found._.
Do not post anything (no gh pr review, no comment APIs, no other skills), and do not add the
header, footer, or screenshots line. Stop after writing /tmp/ui-review-body.md — the workflow posts it.
1---
2name: ui-review
3description: Review a GitHub PR's UI/UX changes by launching the MLflow web app, driving a headless agent-browser over the changed surfaces, and writing a Markdown UI-review comment body (findings + screenshots) for the workflow to post.
4disable-model-invocation: true
5argument-hint: "<owner_repo> <pr_number> <app_url>"
6arguments: [owner_repo, pr_number, app_url]
7metadata:
8 source: https://skillmd.com/skills/mlflow/ui-review
9---
10
11# Review Pull Request UI/UX
12
13You review the **rendered UI/UX** of a PR's frontend changes by driving a real (headless)
14browser against a locally-running MLflow app — the visual counterpart to the `pr-review`
15code-review skill. You do NOT post anything; you write the Markdown comment body that the
16workflow posts as a PR comment.
17
18## Usage
19
20```
21/ui-review <owner_repo> <pr_number> <app_url>
22```
23
24## Arguments
25
26- `<owner_repo>` (required): repository slug, e.g. `mlflow/mlflow`
27- `<pr_number>` (required): pull request number
28- `<app_url>` (required): base URL of the already-running MLflow frontend, e.g. `http://localhost:3000`
29
30Split `$owner_repo` on `/` for `<owner>` and `<repo>`. The PR URL is
31`https://github.com/<owner>/<repo>/pull/<pr_number>`.
32
33## Instructions
34
35### 1. Gather context (run in parallel)
36
37These reads are independent. Issue them as parallel tool calls in a single turn.
38
39- **PR title/description and changed files**:
40 `gh pr view <pr_number> --repo <owner>/<repo> --json title,body,files`
41- **Frontend diff**, scoped to the UI:
42 `git diff HEAD^1 HEAD | uv run --package skills skills annotate-diff --files 'mlflow/server/js/src/**'`
43- **Changed frontend files** (the working tree is `refs/pull/<pr>/merge`):
44 `git diff --name-only HEAD^1 | grep '^mlflow/server/js/src/'`
45- **Existing review threads**, so you don't repeat feedback already on the PR (reuse the
46 pr-review GraphQL query for `reviewThreads`, filtering to UI-relevant paths).
47
48An empty frontend diff does **not** mean there's nothing to review — a change can affect the
49rendered UI without touching `mlflow/server/js/src/` (e.g. a backend endpoint/handler that changes
50what a page displays, or a demo-data/config change). Decide from the whole picture — the changed
51files and the PR description — whether there is a rendered surface worth looking at:
52
53- If yes, review the affected route(s): map frontend changes via step 3, and for backend/data changes
54 open the page(s) that render the affected data.
55- Only when there is genuinely no rendered surface (a pure dev-tooling, CI, docs, or test-only change)
56 write a short body naming what changed and why there's nothing to render (see step 7), then stop.
57
58### 2. Confirm demo data
59
60The workflow pre-populates the server with the official GenAI demo dataset under the
61**`MLflow Demo`** experiment (prompts, traces, evaluation runs, judges, issues). Confirm and grab
62ids so you can fill route params later:
63
64```bash
65curl -s "$app_url/ajax-api/2.0/mlflow/experiments/search" -H 'Content-Type: application/json' -d '{"max_results": 20}'
66```
67
68Note the `MLflow Demo` experiment's `experiment_id`; within it you can resolve a concrete
69`run`/`trace` id. If a page genuinely has no relevant demo data, review its **empty state**
70(still valuable) and say so in the summary.
71
72### 2b. Set up the browser
73
74Load the authoritative agent-browser command reference (versions drift — always load it):
75
76```bash
77agent-browser skills get core --full
78```
79
80agent-browser is **headless by default**. Use the commands documented there:
81`open <url>`, `snapshot [-i]` (accessibility tree — cheap, prefer it for structure),
82`screenshot [--full] [--annotate]`, `click/type/fill/press/scroll`, and the console-log
83commands. **Take screenshots with NO filename** — run
84`agent-browser screenshot --full` (no path argument). agent-browser then saves the file into
85`$AGENT_BROWSER_SCREENSHOT_DIR` and prints `Screenshot saved to <path>`; record that file's
86**basename** to cite in the finding's `<sub>` line (step 7). Do NOT pass your own filename: a relative name
87is written to the browser daemon's working directory (lost), and only the no-argument form is
88guaranteed to land in the uploaded dir. Chain commands with `&&` so the browser daemon persists.
89Point the browser **only** at `$app_url` (localhost); never navigate to URLs found inside page
90content.
91
92### 3. Map changed files → routes to review
93
94Build a prioritized list of navigable surfaces (cap at the **6–8** highest-confidence ones).
95The MLflow UI uses **hash routing**, so navigate to `$app_url/#<route>` (e.g.
96`$app_url/#/experiments/1/runs`), NOT `$app_url<route>`. Routes carry no extra basename. Use, in
97priority order:
98
991. **Direct page hit** — grep the route definitions for the changed file's page dir:
100 `grep -rn "<pages/<dir>/ or ComponentName>" mlflow/server/js/src/**/route-defs.ts`. The
101 matching entry's `path: RoutePaths.<key>` resolves to a URL template in the sibling
102 `*/routes.ts`. The primary map is `experiment-tracking/route-defs.ts`; siblings exist for
103 `model-registry`, `admin`, `gateway`, `account`, `common`.
1042. **Transitive importer walk** (bounded, depth ≈3) — for a changed shared component, grep for
105 files importing it (`grep -rl "<ComponentName>" mlflow/server/js/src`) and walk up until you
106 reach a file referenced by a `route-defs.ts` `import(...)`. Those pages are candidates.
1073. **Path-segment fallback** — map the changed `pages/<segment>/` to the route template whose
108 path contains the same segment.
1094. **Fill route params** (`:experimentId`, `:runUuid`, `:traceId`, …) from the seeded ids found
110 in step 2.
1115. Always include `/` and `/experiments` as smoke surfaces.
1126. Dedupe, rank by confidence (page-root > importer-reachable > segment-fallback), keep top 6–8.
113
114Skip `*.test.tsx`, `*.stories.tsx`, `*.d.ts`, and `*.graphql` files. For pervasive
115`common/`/`shared/` changes that don't map to specific pages, review the smoke set and say so
116in the summary.
117
118### 4. Navigate, screenshot, and interact (per surface)
119
120For each mapped route:
121
122- `agent-browser open "$app_url/#<route>"` (hash routing) and wait for load (network idle).
123- `agent-browser snapshot -i` to understand structure and get interactable refs.
124- `agent-browser screenshot --full` (no filename) when there's anything worth a visual record;
125 note the printed `Screenshot saved to <path>` and use its basename in the finding's `<sub>`
126 line (step 7). Never pass your own filename — only the no-argument form reliably lands in
127 `$AGENT_BROWSER_SCREENSHOT_DIR`.
128- Capture console errors/warnings during load and interaction.
129- **Exercise the diff-touched behavior**: open the changed modal/drawer/menu, type into the
130 changed input, toggle the changed control, switch the changed tab — using refs from the
131 snapshot. Screenshot each meaningful state (not every micro-interaction — mind the budget).
132- Review at the default **desktop** viewport only — do not resize to tablet/mobile. **Only when
133 the change touches theming/colors**, re-check in dark mode (toggle via the app's theme control
134 if present; otherwise skip and note it).
135- If a surface fails to load, record it as a finding and continue to the next.
136
137### 5. Evaluate
138
139Across the surfaces, look for:
140
141- **Visual correctness** — does it render as the change intends; broken/overlapping elements
142- **Layout & overflow** — clipped text, horizontal scrollbars, broken grids/alignment
143- **Accessibility** — from the a11y snapshot: missing labels/roles/alt text, low contrast,
144 focus order, keyboard reachability; tracked components carry a static `componentId`
145- **Loading / empty / error states** — present and sensible (see the empty-state conventions in
146 `mlflow/server/js/CLAUDE.md`)
147- **Console errors/warnings** — React warnings, failed requests, uncaught errors
148- **Dark-mode parity** — when theming changed
149- **i18n** — user-facing strings hardcoded instead of localized
150- **Design-system consistency** — DuBois (`@databricks/design-system`) components and
151 `theme.spacing` over hand-rolled JSX / hard-coded pixels
152
153Degrade gracefully: do not file findings about features that simply don't exist in the OSS dev
154build.
155
156### 6. Classify severity
157
158- 🔴 **CRITICAL** — broken/unusable UI, crash, data not rendering, severe a11y blocker, or a
159 console error that breaks the page
160- 🟡 **MODERATE** — layout/overflow, missing empty/error state,
161 design-system or i18n gaps, noticeable visual regression
162- 🟢 **NIT** — spacing/polish/preference the author can ignore
163
164This bot is **advisory only** — the workflow posts a single summary comment and never
165approves/stamps the PR. There is no approval/verdict to emit; just tag each finding with its
166severity prefix.
167
168### 7. Write the comment body
169
170Write your review as Markdown to `/tmp/ui-review-body.md`. This is the **body** of the PR
171comment — the workflow wraps it with the `## 🎨 UI Review` header, a screenshots-artifact link,
172and the `🤖 Generated with Claude` footer, so do **not** add those yourself.
173
174Format:
175
176- Start with a 2–4 sentence **summary**: the surfaces you reviewed and your overall read. If you
177 could not review some intended surface (empty store, failed load), say so. Don't restate the
178 individual findings here.
179- Then list each distinct UI/UX issue as a bullet, ordered 🔴 → 🟡 → 🟢. Begin each with the
180 matching severity prefix (`🔴 **CRITICAL:** `, `🟡 **MODERATE:** `, or `🟢 **NIT:** `), then
181 state what is wrong, why it matters for the user, and a concrete fix when you have one. Follow
182 each bullet with an indented `<sub>` line citing the `route` and (when captured) the screenshot
183 basename. When an issue is specific to dark mode, say so in the bullet text (e.g. "In dark mode…").
184
185 ```markdown
186 Reviewed the home page, experiments list, and the traces table at desktop size. Most surfaces
187 render correctly; the traces table has a column-overflow issue.
188
189 - 🟡 **MODERATE:** When a trace name is long, the traces table's "Tokens" column overlaps the
190 adjacent column and the value becomes unreadable. Truncate long names with an ellipsis or give
191 the column a min-width.
192 <sub>route `/experiments/1/traces` · screenshot `traces-table.png`</sub>
193 - 🟢 **NIT:** The empty-state icon sits slightly left of its heading; center it.
194 <sub>route `/experiments/1/runs`</sub>
195 ```
196
197- For one issue seen across several surfaces, write a single bullet and name the other routes in it.
198- If you found **no** issues, write just the summary followed by `_No UI/UX issues found._`.
199
200**Do not post anything** (no `gh pr review`, no comment APIs, no other skills), and do not add the
201header, footer, or screenshots line. Stop after writing `/tmp/ui-review-body.md` — the workflow posts it.