ui-regression-audit

name	ui-regression-audit
description	OnMyAgent UI regression audit for theme consistency, i18n copy, settings pages, and screenshot-based visual checks. Use when scanning UI regressions, verifying design-system token usage, checking mixed Chinese/English copy, or producing page-by-page visual audit reports.
display_name_zh	UI 回归巡检
display_name_en	UI Regression Audit

UI Regression Audit

Goal

Run a repeatable UI regression pass for OnMyAgent / OnMyAgent after visual, copy, settings, or layout changes. The output must include evidence: scan commands, changed files, screenshots when UI behavior changed, and a short pass/fail report.

Trigger Conditions

Use this skill when the user asks for any of these:

• 全局扫描 UI 问题、主题色、颜色不一致、页面太挤、标题重复、按钮含义不清
• 检查中英文混杂、i18n 文案、设置页文案、页面标题和描述
• 每个页面截图测试、截图巡检、回归报告、修改计划
• 验证某次 UI 调整是否仍然符合 docs/design/theme-system.md
• 修复 Settings、sidebar、account menu、model picker、provider auth、composer 等可见 UI
• 用户贴 Session / 专家 empty / files 侧栏 / 技能矩阵 / composer 截图抱怨交互或高度（优先 session 清单，不要先扫整站 Settings）

Inputs And Outputs

Item	Required Content
Input	User request, affected page or screenshot if provided, current repo state.
Output	Audit table, concrete fixes, validation commands, screenshot paths when taken.
Evidence	rg scan output summary, pnpm task check app, optional reports/.../*.png.
State	Update local .loop/state/PROGRESS.md only when a local handoff is useful; do not write tracked state docs for routine UI work.

For non-trivial UI loops, long-running visual sweeps, repeated validation failures, or work that needs durable resumption, read docs/loop/rules.md after AGENTS.md. Store temporary screenshots, CDP transcripts, and validation evidence under .loop/evidence/ or ignored report paths; do not add them to tracked docs/.

🔴 CHECKPOINTS

Checkpoint	STOP Condition	Required Action
Scope expansion	Scan finds broad product semantics outside the requested UI area	Stop and classify; do not mass-edit without user approval.
Semantic color change	A color encodes error, warning, success, online, diff, chart, file type, or brand identity	Stop and report as “review/keep” unless the user explicitly asks to change it.
Data/schema change	Fix requires changing business schema, persisted data, or API contract	Stop and ask user.
Screenshot unavailable	UI app or CDP port is not running and user did not ask to start it	Report command to start; do not claim screenshot verification.
Repeated failure	Same validation command fails 3 times	Stop, summarize blocker, and ask for direction.

Workflow

1. Load Project State

Run:

test -f .loop/state/PROGRESS.md && sed -n '1,220p' .loop/state/PROGRESS.md || true
sed -n '1,220p' docs/design/theme-system.md

If either file is missing:

Failure	Recovery
.loop/state/PROGRESS.md missing	Continue with repo scan; create no replacement unless a local handoff is useful.
docs/design/theme-system.md missing	Use existing dls-* token usage as the source of truth and note missing doc in the report.

2. Define The Page Inventory

For settings-related work, list available settings pages before editing:

find apps/app/src/react-app/domains/settings -maxdepth 3 -type f \( -name '*view.tsx' -o -name '*section.tsx' -o -name '*shell*.tsx' \) | sort

For broader UI work, inspect routes and common surfaces:

rg -n "route|settings|sidebar|composer|modal|dialog" apps/app/src/react-app/shell apps/app/src/react-app/domains -g '*.tsx' --no-heading

2b. Session surface checklist (prefer for session/files/composer PRs)

Surface	Required check
Assistant draft / new task	No agent top header; hero + composer only
Expert empty	Prompt cards: readable spacing/height; no metallic gradient hover
Composer empty height	Expert matches assistant compact empty height (homeLayout)
Files side panel	Tree-only until a file is selected; then detail; Office → unavailable not binary dump
Skill matrix	Loading shows skeleton/spinner — not “暂无匹配 Skill”
Plan mode chip	Icon + label only (no hover ✕)
i18n	New strings in en + zh + zh-TW

Boundary: mechanical token/class consolidation → frontend-primitive-refactor. This skill owns visual contracts, copy, and evidence.

3. Run Theme Token Scan

Use this scan for hard-coded Tailwind color classes that may bypass the design system:

rg -n "\b(bg|text|border|ring|from|via|to)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-" apps/app/src/react-app apps/app/src/components -g '*.tsx' -g '*.ts' --no-heading

Classify every hit before editing:

Class Type	Decision
Selected/current/active/highlight UI	Convert to dls-accent token family.
Background, border, text neutrals	Convert to dls-surface, dls-border, dls-text, dls-secondary, or existing local token.
Error/warning/destructive	Keep semantic dls-status-* or existing red/amber if no token exists.
Success/online/connected	Treat as semantic; change only if user explicitly wants brand-blue status.
Diff/chart/file-type/brand/platform color	Keep unless the task specifically targets that component.

4. Run Copy And I18n Scan

rg -n "[\u4e00-\u9fff].*[A-Za-z]|[A-Za-z].*[\u4e00-\u9fff]|Team|Hub|Provider|Settings|Current|Connected|Connect|Cancel|Save|Delete" apps/app/src/react-app apps/app/src/i18n -g '*.tsx' -g '*.ts' --no-heading

Rules:

Hit	Action
User-visible text inside React component	Move to existing i18n system or reuse an existing key.
Brand, model ID, provider ID, API term, file extension	Keep as literal.
Settings section title	Match existing Chinese terminology and page description style.
Duplicate generic page title	Remove the duplicate header; keep the page-specific title.
New user-visible string	Update en + zh + zh-TW locales together (not en+zh only).

5. Patch With Minimal Diff

Patch only the files required by the audit finding. Prefer existing components and tokens:

Need	Preferred Token / Component
Primary accent	bg-dls-accent, text-dls-accent, border-dls-accent/25
Soft accent badge/card	bg-dls-accent/10, text-dls-accent, border-dls-accent/20
Text	text-dls-text, text-dls-secondary
Surface	bg-dls-surface, bg-dls-surface-muted, bg-dls-hover
Border	border-dls-border, border-dls-border-strong
Danger	dls-status-danger token family

6. Validate

Always run focused validation first:

rg -n "<target-regex>" <changed-files> --no-heading || true
pnpm task check app

For long UI token or component-consolidation loops, avoid running Graphify after every tiny patch. Batch related UI-only diffs into a checkpoint, run git diff --check and the focused app typecheck for each batch, then run incremental graphify update . once at the checkpoint or final handoff. Do not use graphify update . --force unless incremental update is explicitly refused by the CLI or a cache anomaly is confirmed; record the reason when --force is used.

If UI behavior, layout, or visual state changed, verify with browser/CDP screenshots.

Port checks:

lsof -nP -iTCP:5173 -sTCP:LISTEN
lsof -nP -iTCP:9823 -sTCP:LISTEN

Report folder:

mkdir -p reports/ui-regression-$(date +%Y%m%d-%H%M%S)

Screenshot checklist:

Area	Required Evidence
Settings root	Header, duplicate title check, centered layout.
Settings subpage	Page-specific title/description, spacing, token usage.
Account menu	Selected language/theme indicator and hover state.
Model picker	Current model badge, selected row, disabled state.
Provider/MCP auth	Connected/disconnected method badges.
Sidebar/session list	Active item, status indicator, account footer.
Composer	Send/stop button, tool menu, enabled badges, notice state; plan chip without ✕.
Assistant draft home	No top agent chrome; composer compact empty height.
Expert empty	Prompt cards + composer height vs assistant.
Files side panel	Tree-only default; detail after select.
Skill matrix	Loading skeleton vs empty copy.

If screenshot tooling fails:

Failure	Recovery
UI port closed	Start only if user requested startup; otherwise report pnpm dev.
CDP port closed	Use manual browser screenshot if available; mark CDP evidence missing.
Electron-only surface	Structure assert + user screenshot is acceptable evidence; do not claim CDP pass.
Page requires state/auth	Capture reachable shell and report missing state requirement.
Screenshot script errors	Save DOM/text evidence and include the error.

7. Report

Use this table:

Area	Result	Evidence	Action
Theme tokens	Pass / Review / Fail	scan count + top files	fixed or classified
Copy/i18n	Pass / Review / Fail	scan examples	fixed or deferred
Screenshots	Pass / Missing / Fail	report image paths	verified or blocker
Typecheck	Pass / Fail	command	fixed or blocker

End with:

• changed files
• validation commands run
• remaining review items
• whether local .loop/state/PROGRESS.md was updated

8. Update Progress

For non-trivial work, append one concise note to local .loop/state/PROGRESS.md only when handoff value exceeds noise:

- YYYY-MM-DD UI regression: audited theme tokens/copy/screenshots; fixed visible regressions; typecheck passed; remaining items classified as semantic/decorative/product-review.

Append current-day validation summaries to .loop/runs/YYYY-MM-DD.md only when they help future resumption. Keep tracked state docs such as docs/LOOP-RUN-LOG.md, docs/intent-debt.md, and docs/STATE.md as compatibility pointers, not routine UI audit outputs; docs/PROGRESS.md is removed in favor of .loop/state/PROGRESS.md.

Test Prompts

Use these prompts to verify this skill produces useful behavior:

ID	Prompt	Expected Output
T1	“设置页看起来还是不统一，全局扫一下主题色并给我报告。”	Runs state read, token scan, classifies semantic vs theme hits, proposes minimal fixes, includes validation plan.
T2	“每个设置页面截图检查，不要漏，看看标题和中英文有没有问题。”	Builds page inventory, checks i18n/copy, captures or requests screenshot prerequisites, returns page-by-page report.
T3	“这个弹窗的选中态颜色不对，修完怎么验证？”	Locates component, patches token usage, runs focused scan + typecheck, explains screenshot verification path.

Anti-Patterns

Do not do these:

Anti-Pattern	Why It Fails	Correct Behavior
Mass replacing every color class	Breaks semantic status, charts, file types, and brand identity.	Classify first; edit only requested or clearly wrong UI highlights.
Claiming screenshot coverage without images	Gives false confidence.	Provide screenshot paths or state why screenshots were not captured.
Editing only one of en / zh / zh-TW	Creates i18n drift.	Update en + zh + zh-TW when adding user-visible copy.
Ignoring dirty workspace	May overwrite unrelated work.	Inspect git status --short; only touch task files.
Using npm/yarn	Violates project rules.	Use pnpm.
Adding new UI primitives unnecessarily	Increases design drift.	Reuse existing components and dls-* tokens.
Leaving validation vague	Makes regression unrepeatable.	Include exact commands and pass/fail result.
Hand-writing tab bars as inline-flex rounded-lg border p-1 around pill NavTabButton	Two shape families in one container (r=10 outer, r=999 inner) reads unbalanced.	Use <SegmentedTabGroup> + <NavTabButton size="tab" shape="tab"> (canonical since manage-page R17 fix).
Using rounded-full for ordinary CTAs	Only avatars, NavTabButton pill chips, SendButton, and architecture-mismatch-gate.tsx may.	Prefer rounded-lg (10) or rounded-xl (14) per DESIGN.md § 11.
Editing signature primitives without checking components.contracts	Radius/height/surface drift silently reappears.	Cross-reference the YAML components.contracts block in DESIGN.md in the same PR.

Runtime Neutrality

This skill is runtime-neutral. Do not assume a single agent runtime. If browser automation tools are unavailable, use shell scans and state the missing screenshot capability in the report.