UI quality detection system
The UI quality detection system finds visual, layout, typography, accessibility, content, and generated-UI antipatterns before they reach users. It examines local source, static HTML, and browser-rendered pages, then gives CLI and agent workflows one shared set of findings that can guide fixes or block poor edits.
System purpose
The detector turns design quality concerns into named findings that engineers can inspect and act on. It aims to catch both source-level signals, such as an overused font or unsafe motion rule, and page-level results, such as clipped content or unreadable contrast.
Its rule set includes two broad kinds of checks:
- Quality checks identify defects that affect clarity, access, reading, layout, or function.
- Slop checks identify repeated visual and copy patterns that make an interface feel generic or machine-made.
The detector does not replace human design judgment. It points to patterns that deserve review and keeps the same rule names and finding shape across each analysis surface.
Analysis surfaces
The system selects an analysis surface from the input. Source files use text analysis, HTML files use structural analysis, and URLs use a real browser so the detector can inspect the page after scripts, styles, and layout have taken effect. This keeps fast local checks available while reserving browser work for behavior that source text cannot prove.
flowchart LR
A[Input] --> B{Input kind}
B -->|CSS, JSX, TSX, or other source| C[Source analysis]
B -->|HTML file| D[Static HTML analysis]
B -->|HTTP or file URL| E[Browser-rendered analysis]
B -->|Running Chromium app| F[Attached page analysis]
C --> G[Shared findings]
D --> G
E --> G
F --> G
G --> H[CLI output or agent guidance]
The main trade-off is coverage. Source analysis can report exact file lines, static HTML can reason about elements and linked styles, and browser analysis can measure computed styles, runtime errors, viewport layout, and visual contrast. A source-only result is therefore an undercount when a rule needs parsed elements or rendered state.
References: crates/…/cli.rs• L34-116 crates/…/cli.rs• L360-397 cli/…/detect-html.mjs• L110-170 cli/…/detect-url.mjs• L165-213
Local source analysis
Local source analysis gives engineers a quick view of likely UI problems before a page is built. It reads styles and component source as text, recognizes CSS, utility-class, inline-style, CSS-in-JS, and component-style patterns, and preserves source line context for the resulting findings.
The scan also extracts page-level text checks when a source file is a complete page. It can resolve color values held in project-wide CSS custom properties, so a component can be judged with the token value declared in another style sheet. It cannot confirm the final cascade or rendered geometry, so browser-visible issues still need a rendered pass.
References: crates/…/detect_text.rs• L2153-2179 crates/…/detect_text.rs• L2182-2367 crates/…/project_tokens.rs• L37-85
Static HTML analysis
Static HTML analysis builds a view of an HTML document and its local style sources without starting a browser. It combines element structure with resolved style information to find problems in borders, color, motion, typography, layout, overflow, images, and page composition.
This surface sits between text matching and browser analysis. It can inspect linked local CSS and page structure more accurately than a text scan, while remaining suitable for local files and automated checks that do not need a browser session. Configured template extensions can opt into the HTML surface when their output is HTML-like.
References: cli/…/detect-html.mjs• L93-108 cli/…/detect-html.mjs• L157-287 crates/…/config.rs• L141-221
Browser-rendered analysis
Browser-rendered analysis loads a URL at a chosen viewport and inspects the page after its scripts and styles run. It adds evidence that only exists at runtime, including uncaught script errors, content that stays hidden after reveal behavior, computed contrast, clipping, overflow, and visual relationships between elements. It also judges type hierarchy from visible semantic heading and body roles instead of treating every distinct font size as equal evidence.
The browser surface can scan a remote page, a local file:// page, or a running development server. It also supports a visual contrast pass that uses browser measurements and, when needed, pixel evidence so a finding reflects what a person can see rather than only what the source declares. The live browser path skips all scan stages for a project-waived page, including the visual pass.
References: cli/…/detect-url.mjs• L42-67 cli/…/detect-url.mjs• L221-335
Detection model
The detector presents every issue as a finding tied to an antipattern rule. A finding carries the rule identity, a human-readable name and description, the source or URL target, an optional line, and a short piece of evidence. Consumers can therefore render the same result in text, JSON, hooks, or agent messages.
Antipattern registry
The antipattern registry is the shared vocabulary for the product. It groups rules into quality and slop categories, records severity and design-domain scopes when they apply, and maps each rule to the analysis engines that can support it.
The registry covers concerns such as:
- typography and text hierarchy;
- color, contrast, and palette choices;
- spacing, containers, overflow, and layout balance;
- motion and decorative effects;
- broken assets and runtime failures;
- copy patterns and repeated generated-UI signals; and
- drift from a project design system.
The detailed rule checks and engine support belong in Detection engines and antipattern rules.
References: cli/…/antipatterns.mjs• L1-55 cli/…/antipatterns.mjs• L384-505 cli/…/antipatterns.mjs• L559-605
Finding policy
Findings have two policy levels. Normal findings count as failures and can make a scan fail. Advisory findings remain visible as review notes but do not change the failure count or exit status. This lets teams inspect subjective signals without making automation brittle.
The CLI can return human-readable output, JSON, or GitHub Actions annotations. It can narrow results by design domain, such as type or layout. Shared ignore rules, value-level waivers, inline waivers, and disabled design-system checks let a project record intentional exceptions before results reach those outputs.
References: crates/…/cli.rs• L178-192 crates/…/cli.rs• L796-849 crates/…/config.rs• L858-920
Product surfaces
The detector is one capability with more than one entry point. The command-line surface is explicit and report-focused, while the agent surface uses the same analysis functions during edits so quality feedback appears near the change that caused it.
CLI surface
The CLI accepts files, directories, standard input, URLs, and pages in a running Chromium-based app. Local targets are routed to static HTML analysis when their configured extension is HTML-like; other files use source analysis. URL targets use browser analysis, while --cdp attaches to an existing app page without navigating or resizing it.
The command supports machine-readable output, quiet summaries, GitHub annotations, scope filters, viewport selection, advisory control, raw scans that bypass project context, and rule-catalog output. It reads shared and local detector configuration for ignored rules, files, values, design-system use, and extension-to-engine choices. Command details and configuration rules belong in Detector commands and configuration.
References: crates/…/cli.rs• L34-116 crates/…/cli.rs• L484-649 crates/…/cli.rs• L716-849 crates/…/config.rs• L82-139
Agent surface
Agent workflows use the detector as an edit check. Before or after an agent changes a file, the hook loads the shared detector and routes HTML through static analysis or other files through source analysis. The result is filtered with the same project rules before the workflow allows, reports, or asks the agent to address the edit.
For proposed HTML that does not yet exist on disk, the agent stages the proposed content as a temporary document. This gives pre-write checks the same structural coverage as post-edit checks without requiring the agent to save the change first.
References: .cursor/…/hook-lib.mjs• L1589-1606 .cursor/…/hook-lib.mjs• L1922-1954 .cursor/…/hook-before-edit.mjs• L336-349 .cursor/…/hook-before-edit.mjs• L464-491
Shared browser capability
The browser detector also exposes a page-side interface for interactive tools. It can collect findings without decoration, run a scan that highlights elements, return serialized results, and resolve visual contrast candidates as content enters the viewport.
This shared capability lets a browser-facing agent or extension inspect the same page facts as the URL CLI path. The presentation can differ, but the rule registry, finding types, project scan skips, and value-level waivers remain aligned.
References: cli/…/index.mjs• L1893-1970 cli/…/index.mjs• L1972-1986 cli/…/index.mjs• L2063-2072
Design-system context
The detector can compare observed UI values with a project design system. It reads documented typography, colors, rounded shapes, font sizes, selected shadow evidence, and named component selectors. It then reports values that drift from the documented vocabulary instead of treating every literal value as equally valid.
The design context is found for the target's project and may come from DESIGN.md plus a JSON sidecar. Workspace boundaries prevent a nested app from inheriting an unrelated system. The context can also suppress a palette signal when the project documents that palette as intentional. The broader profiling and evidence model belongs in Design system profiling.
References: crates/…/design_system.rs• L1467-1540 crates/…/design_system.rs• L1544-1677 crates/…/design_system.rs• L1945-2017
Analysis pipeline
The detector moves from input discovery to surface selection, rule evaluation, context filtering, and result delivery. Each stage has a clear owner so a finding can be traced from the scanned target to the interface that reports it.
When the detector processes a request, it follows a structured sequence:
- The CLI or agent identifies a file, directory, standard-input payload, URL, or attached app page.
- The shared orchestration selects source, static HTML, browser, or attached-page analysis.
- The selected engines evaluate supported rules and collect evidence.
- Project design-system context, project tokens, and ignore controls remove intentional exceptions.
- Findings are grouped, formatted, or sent to the agent workflow.
flowchart LR
A[Target] --> B[Route to analysis surface]
B --> C[Collect findings]
C --> D[Apply design and project context]
D --> E[Apply scopes and waivers]
E --> F[Report to CLI or agent]
The full discovery and orchestration path is described in Detector analysis pipeline. The engine and rule boundaries are described in Detection engines and antipattern rules.
References: crates/…/cli.rs• L716-849 crates/…/cli.rs• L952-1131 crates/…/detect_text.rs• L2153-2373 crates/…/engines.rs• L14-48
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the antipattern registry and each engine's supported rule set aligned.
- Preserve the finding fields used by CLI text output, JSON consumers, and agent hook filtering.
- When a rule gains or loses browser support, check both URL scans and page-side scans.
- When design-system fields change, keep source checks, static checks, and browser serialization consistent.
- When HTML engine behavior changes, verify that pre-write agent checks and post-edit hook checks still use the same route.
- When advisory status changes, review both CLI exit-code behavior and agent filtering because advisories must not silently become blocking findings.
- When project token lookup changes, verify that local component scans still resolve the nearest package values before shared checkout values.
- When extension routing changes, verify that template files still use the intended HTML or source surface and that coverage notes remain honest.
- When attached-app or viewport options change, keep their incompatible target rules and browser behavior aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A local file is routed to source analysis instead of parsed HTML analysis | Element-level rules do not run, so the result is an undercount rather than a clean bill of health | Scan the built HTML or running app, or configure the extension for the HTML engine |
| HTML parser modules are unavailable | The scan falls back to text matching and can undercount structural, cascade, and contrast issues | Restore the HTML parser dependencies; treat the degraded warning as incomplete coverage |
| Puppeteer is unavailable for a URL target | The URL scan cannot inspect the rendered page | Install Puppeteer or use a local source/static scan when browser access is not required |
| A page throws a script error during load | Dynamic content and reveals may fail, so later visual findings can describe a broken page state | Fix the reported script error before using the rest of the page findings as design feedback |
| A project uses the wrong or disabled design-system context | Drift checks can be absent or compare against the wrong documented values | Resolve the target's project context and confirm detector design-system settings |
| A token is declared outside the files read for the project | A token-based stripe or color check can miss the value and under-report the issue | Keep token sheets inside the owning package or checkout and scan the correct project target |
| A rule is added to one engine but not the registry support map | CLI, agent, and browser surfaces report different coverage | Update the rule registry and engine support together |
| A comp-led build has an open comp round or hero gate | An engineer can mistake a detector pass for a finished page | Read the workflow warning and follow the status command's next action |
Key files
| File | Why to read it |
|---|---|
| crates/…/lib.rs | Shows the detector's public entry points and the seams for static HTML and browser engines. |
| crates/…/cli.rs | Shows target routing, command options, scan policy, output modes, and exit status. |
| crates/…/config.rs | Shows project detector settings, extension routing, file and value waivers, and finding filtering. |
| crates/…/detect_text.rs | Shows the source-analysis lifecycle across matchers, page analyzers, design checks, deduplication, and inline waivers. |
| crates/…/regex_matchers.rs | Shows the source rule families and the distinction between line matchers and complete-page analyzers. |
| crates/…/project_tokens.rs | Shows how project-wide CSS custom properties inform source findings. |
| crates/…/design_system.rs | Shows design-system discovery, normalization, project boundaries, and drift checks. |
| crates/…/engines.rs | Defines the shared contracts for static HTML, URL, shared-browser, and attached-app scans. |
| cli/…/detect-html.mjs | Shows how the parsed HTML surface evaluates structure and linked styles. |
| cli/…/detect-url.mjs | Shows how a rendered URL scan gathers runtime, layout, and visual evidence. |
| .cursor/…/hook-lib.mjs | Shows how agent edit workflows load and apply the shared detector. |