Detection engines and antipattern rules
The detector turns source text and rendered-page evidence into findings about design quality and generated-UI signals. Regex, static HTML, browser, and visual checks use different levels of evidence, while a shared rule vocabulary and finding policy keeps their results comparable.
Detection model
An antipattern rule is a stable description of a quality problem or a generated-UI signal. A check tests evidence against that rule and returns a small match. The detector then adds the rule metadata, target, and policy that downstream reports need.
The main path is:
flowchart LR
I[Source, HTML, or live page] --> E[Evidence engine]
E --> C[Rule check]
C --> M[Rule match]
M --> F[Shared finding]
F --> O[CLI, hook, browser tool, or JSON]
Each engine can support element, page, source, layout, or visual evidence. A rule ID therefore identifies the concern across engines, but the detail explains which evidence caused the match.
Engine coverage
The engines form an evidence ladder. Regex reads authored text, static HTML adds a resolved document view, browser analysis adds runtime layout and paint, and visual analysis reads pixels when style data is not enough.
| Engine | Main evidence | Main limit |
|---|---|---|
| Regex | CSS, JavaScript, JSX, TSX, component text, and page text | Cannot prove the final cascade or rendered state |
| Static HTML | Parsed HTML, local styles, cascade, structure, and source patterns | Cannot prove runtime layout, scripts, hit tests, or pixels |
| Browser | Live or captured DOM, computed styles, geometry, state, and paint | Depends on page capture and browser evidence |
| Visual | Rendered text and background pixels | Unreadable or missing pixels stay unresolved |
Browser engine
The browser engine evaluates the page a visitor can meet after scripts and styles run. It reads the DOM, computed styles, geometry, text ranges, animation state, hit-test stacks, page errors, and paint state through a common browser probe. The probe can use a live page or a bounded page snapshot, so the rule core can run in both normal and content-policy-safe browser paths. (crates/…/driver.rs• L2903-2953, crates/…/background.rs• L108-160)
The browser pass checks elements first and then checks page relationships. It groups element findings by their owner, keeps page findings separate, and removes matches that belong to ignored or unpainted content. Source pattern findings are also resolved against the live DOM before they become browser findings. (crates/…/driver.rs• L2954-3057, crates/…/driver.rs• L1164-1235)
Browser checks use context to avoid treating valid interface behavior as a defect. Active tabs, status regions, controls, real scrollers, moving tracks, embedded media, and content inside product mockups each receive the context that changes the rule decision. (crates/…/element_checks.rs• L78-113, crates/…/page_checks.rs• L934-1013, crates/…/text_collectors.rs• L206-305)
References: crates/…/driver.rs• L2903-2953 crates/…/element_checks.rs• L78-113 crates/…/page_checks.rs• L934-1013
Paint and runtime state
Paint gating means that a check reports only when its target is visible at capture, unless the rule is specifically about hidden or authored state. Runtime checks use visibility, opacity, clipping, geometry, and animation state to separate content a visitor sees from content that only exists in the DOM. (crates/…/element_checks.rs• L322-375, crates/…/text_collectors.rs• L299-305)
The detector also distinguishes real scrolling from a box that only clips overflow. Text near a viewport edge is therefore treated as an issue unless a measured scroller or moving track explains the edge. (crates/…/text_geometry.rs• L219-287, crates/…/text_geometry.rs• L289-377)
This distinction matters for rules about text, images, motion, glow, palette, nested cards, and page-level CSS patterns. A closed menu, parked carousel slide, or unrevealed row can have valid style and geometry records while showing nothing to a visitor. The detector therefore separates authored evidence from what is painted at rest. (crates/…/driver.rs• L1200-1235, crates/…/text_layers.rs• L757-831)
References: crates/…/element_checks.rs• L322-375 crates/…/text_geometry.rs• L219-377 crates/…/text_layers.rs• L757-831
Static HTML engine
The static HTML engine builds a browser-like view of a local document without opening a page. It parses the document, collects local style sources, resolves the cascade, and applies element, page, pattern, and text checks to the resulting structure. This makes it useful for inherited values, custom properties, pseudo-element surfaces, and source patterns that need more than a single text token. (crates/…/css_scan.rs• L39-66, crates/…/css_scan.rs• L1311-1355)
Static analysis can show what the authored document resolves to, but it cannot confirm scripts, viewport geometry, hit-test order, reveal state, or painted pixels. It keeps findings when the partial document cannot disprove a source signal. Runtime-only checks remain the browser engine's responsibility.
References: crates/…/css_scan.rs• L39-66 crates/…/css_scan.rs• L1311-1355
Regex engine
The regex engine treats source as text when a document model is not needed. It finds authored signals such as unusual motion, glow, gradients, stripes, buried rasters, organic shapes, repeated spacing, and generated-copy phrases. CSS scanners preserve source positions and can resolve custom properties where the source contains enough information. (crates/…/css_scan.rs• L39-66, crates/…/css_scan.rs• L159-227)
The source path also builds separate style and class corpora from HTML. Page text analyzers remove markup, scripts, styles, and comments before looking for aggregate copy patterns. These findings describe author intent or source risk; they do not prove that a selector applies or that a visitor sees the result. (crates/…/css_scan.rs• L656-673, crates/…/vectors_a.rs• L398-419)
References: crates/…/css_scan.rs• L159-227 crates/…/css_scan.rs• L656-673 crates/…/vectors_a.rs• L398-419
Visual engine
The visual engine checks contrast when declared colors do not describe the surface behind text. It selects visible text affected by images, gradients, opacity, filters, blend modes, shadows, backdrop effects, pseudo-element faces, or detached paint. (crates/…/visual.rs• L106-245)
The browser-side pixel pass samples the painted surface and can retry content outside the first viewport. The structural path now resolves translucent fills, gradients, layered gradients, and gradient geometry under the text before it asks pixels to decide. A dot grid or hairline decoration remains texture over its fill, while a picture or an unreadable layer keeps the verdict unresolved. (crates/…/background.rs• L132-160, crates/…/text_layers.rs• L263-333, crates/…/visual.rs• L2430-2470)
The visual path reports the same low-contrast rule as analytic contrast and suppresses the duplicate when it owns that result. Cross-origin or unreadable images, unknown layer order, and surfaces that cannot be placed do not become passing results. (crates/…/text_layers.rs• L676-755, crates/…/visual.rs• L1094-1173)
References: crates/…/visual.rs• L106-245 crates/…/background.rs• L132-160 crates/…/text_layers.rs• L676-755
Antipattern registry
The antipattern registry is the shared vocabulary for rule identity and report meaning. Each rule has a stable ID plus a human name, description, category, supported evidence phases, optional scope, and optional severity. The registry also accepts namespaced rule packs without changing the built-in engine. (crates/…/rules.rs• L23-25, crates/…/vectors_a.rs• L17-50)
The registry's practical contract is:
- A rule ID has one meaning across all engines.
- A check returns a rule match, not a complete report record.
- A missing severity uses the normal warning policy.
- An advisory severity keeps the finding visible without making it a normal scan failure.
- Scope and design-system waivers filter a match after the check has enough evidence to report it.
Shared rule checks
Shared checks hold decisions that do not depend on a particular document model. They cover contrast, colors, borders, motion, glow, typography, palette signals, card-like traits, and other rule gates. The static and browser adapters gather facts in their own form, then call the same rule intent where the evidence is equivalent. (crates/…/rules.rs• L334-423, crates/…/rules.rs• L957-1067)
The checks are grouped by the evidence they need:
| Check group | What it decides |
|---|---|
| Element checks | One element and the context that gives it meaning |
| Page checks | Relationships among elements, source regions, or viewport areas |
| Source and text checks | Authored CSS, markup, code, copy, or aggregate text patterns |
| Pattern checks | Wider HTML, CSS, and class corpora such as stripes, grids, scenes, and copy framing |
References: crates/…/rules.rs• L334-423 crates/…/rules.rs• L957-1067
Context and exceptions
Guards are part of a rule's meaning. They remove controls, status content, selected states, decorative text, legal text, chart labels, embedded media, and mockup content when those contexts change what a visitor is meant to read. They also prevent source declarations that are inactive, neutral, transparent, or only used for a state from producing a finding. (crates/…/text_context.rs• L1142-1193, crates/…/text_rules.rs• L150-274, crates/…/css_scan.rs• L587-594)
The detector distinguishes a declared mockup from a guessed mockup. Decorative text classification accepts explicit picture or mockup signals only with positive evidence, while structured framed demos can mark short interface labels as mockup content. Sentence-length copy, controls, captions, and real page landmarks keep their normal reading role. (crates/…/decorative_text.rs• L184-237, crates/…/text_context.rs• L1029-1112, crates/…/decorative_text.rs• L102-143)
Fine print has two levels of context. Legal and footnote blocks can be exempt from line-length and tiny-text findings, while other fine print remains advisory. Controls and form labels do not inherit the exemption just because they sit in a legal region. (crates/…/text_context.rs• L1136-1193, crates/…/text_context.rs• L1314-1450)
References: crates/…/decorative_text.rs• L184-237 crates/…/text_context.rs• L1029-1112 crates/…/text_context.rs• L1136-1193
Rule families
The rule families share a finding model but use different evidence shapes. The important distinction is whether a single element can prove the concern or whether the check needs page context.
Element checks
Element checks judge one rendered or authored object. They report concerns such as low contrast, gray text on color, gradient text, side accents, glow, bounce easing, tiny text, clipping, overflow, and design-system drift. Browser adapters add geometry, paint, animation, and hit-test context; static adapters use resolved document values. (crates/…/element_checks.rs• L117-179, crates/…/element_checks.rs• L2638-2710, crates/…/rules.rs• L957-1067)
Contrast checks score the surface a reader meets. The browser background walk composites translucent fills, samples gradients where text sits, and keeps layered gradient colors in the order they paint. When geometry is missing, the check falls back to the safest resolvable stop set instead of claiming a precise surface. (crates/…/background.rs• L171-303, crates/…/background.rs• L398-443, crates/…/background.rs• L509-548)
Text geometry checks use rendered text extents rather than only the element box. This supports rules about line length, viewport gutters, cramped padding, tight leading, text overflow, and line breaks. They stand down when a real scroller, moving track, authored break, clamp, or hidden text changes the meaning of the measured edge. (crates/…/text_geometry.rs• L125-217, crates/…/quality.rs• L683-763, crates/…/quality.rs• L947-1053)
References: crates/…/element_checks.rs• L117-179 crates/…/quality.rs• L683-763 crates/…/text_geometry.rs• L125-217
Page checks
Page checks need several elements or a page-wide relationship before they can decide. They cover typography usage, type hierarchy, nested cards, heading rhythm, hidden content, occlusion, first-viewport balance, palette context, and viewport overflow. Browser checks add rendered rectangles, scroll state, paint order, and hit-test evidence. (crates/…/page_checks.rs• L238-349, crates/…/page_checks.rs• L1266-1311)
The browser page pass treats the visible page as the source of truth for relationships. A card nested inside another card must be a separately painted card, a heading rhythm must follow normal flow, and an occlusion must cover the text in the captured paint order. Media frames, output blocks, players, fields, control strips, dialogs, and mockups are excluded when their structure explains the appearance. (crates/…/page_checks.rs• L462-482, crates/…/page_checks.rs• L981-1172, crates/…/page_checks.rs• L4808-4890)
References: crates/…/page_checks.rs• L238-349 crates/…/page_checks.rs• L462-482 crates/…/page_checks.rs• L4808-4890
Source and text checks
Source and text checks describe patterns that remain meaningful without a browser. CSS and HTML scanners identify source forms such as pseudo-element stripes, inset stripes, repeating gradients, grid backgrounds, radial halos, glows, marquees, buried rasters, organic clips, and shape-assembled SVG scenes. Text checks identify aggregate copy patterns after non-page text is removed. (crates/…/css_scan.rs• L229-310, crates/…/css_scan.rs• L703-878, crates/…/css_scan.rs• L2455-2505)
These checks use conservative source rules. Comments are blanked without moving offsets, custom properties can be followed when resolvable, and unknown interpolation or mixin input keeps the result uncertain. A source match is not proof that the final cascade uses the declaration. (crates/…/css_scan.rs• L39-66, crates/…/css_scan.rs• L1121-1193)
References: crates/…/css_scan.rs• L39-66 crates/…/css_scan.rs• L656-673 crates/…/css_scan.rs• L1121-1193
Pattern checks
Pattern checks combine a wider source view with optional live-page context. The shared pass reports a selector when CSS or HTML text shows a pattern. The browser adapter then resolves that selector against the live DOM and checks whether the matched elements are visible, painted, active, and still carry the declared effect. (crates/…/driver.rs• L1164-1235)
The browser can therefore reject a dead token, inactive media rule, overridden gradient, unpainted stripe, or selector that matches nothing. It can also map pseudo-element selectors to their host elements without broadening inactive state selectors such as :hover or :focus into resting-state findings. (crates/…/driver.rs• L621-764, crates/…/driver.rs• L1238-1302)
References: crates/…/driver.rs• L1164-1235 crates/…/driver.rs• L1238-1302
Text pattern checks
Text pattern checks look for repeated layout language rather than one isolated token. Browser collectors identify tracked labels above headings, numbered section labels, repeated text in bounded containers, and excessive em-dash use after removing hidden or non-page text. (crates/…/text_collectors.rs• L194-315, crates/…/text_collectors.rs• L363-456, crates/…/text_collectors.rs• L648-761)
These checks use layout and semantic context to avoid charging normal content. A label beside a heading, a ranked list, a hidden carousel copy, a code or media block, and a dash used as a list separator do not carry the same meaning as the matching source shape. (crates/…/text_collectors.rs• L366-455, crates/…/text_rules.rs• L522-577)
References: crates/…/text_collectors.rs• L194-315 crates/…/text_collectors.rs• L363-456 crates/…/text_rules.rs• L522-577
Finding contribution
Each check contributes a rule ID and a short detail. The shared finding layer resolves that ID and adds the stable rule metadata, severity, category, target, source location when known, and evidence. Browser results can keep several checks together under one element group, while page results have no single owner. (crates/…/driver.rs• L41-64, crates/…/driver.rs• L2903-3057)
The contribution path is:
- An engine gathers evidence for an element, page, or source region.
- A check applies its guards and returns one or more rule matches.
- The engine removes duplicates, inactive forms, ignored targets, and findings that fail the engine's evidence gate.
- The finding layer applies metadata, severity, advisory policy, attribution, and serialization.
- Consumers present the result as a flat report or as a grouped browser result.
Duplicate ownership
Some concerns have several evidence forms. A browser element result can own a computed declaration, so its matching class or stylesheet form is removed. Visual contrast can own a low-contrast result when the pixel path resolves the surface, so the analytic duplicate is not emitted. Safe-tag contrast uses a per-page claim so one ignored or partial element does not silence a later valid claimant. (crates/…/driver.rs• L3030-3057, crates/…/driver.rs• L3070-3105, crates/…/rules.rs• L591-747)
References: crates/…/driver.rs• L3030-3057 crates/…/driver.rs• L3070-3105 crates/…/rules.rs• L591-747
Severity and advisory policy
Normal findings count as scan failures. Advisory findings remain visible for review but do not change the normal failure result. A check can set advisory severity when context makes the issue less direct, such as decorative text, framed demos, legal copy, micro-labels, mockup panels, and near-threshold contrast. Consumers should use the effective severity rather than infer policy from the rule name. (crates/…/rules.rs• L827-926, crates/…/text_context.rs• L1-39)
References: crates/…/rules.rs• L827-926 crates/…/text_context.rs• L1-39
Ignore boundaries
Element findings can be waived by an ancestor's data-impeccable-ignore. Source and static findings can use inline directives such as impeccable-disable, impeccable-disable-line, and impeccable-disable-next-line. The browser driver applies scoped ignores while grouping findings, which keeps an ignored element from claiming a page-wide duplicate. (crates/…/driver.rs• L16-64, crates/…/driver.rs• L1200-1205, crates/…/rules.rs• L627-747)
References: crates/…/driver.rs• L16-64 crates/…/driver.rs• L1200-1205 crates/…/rules.rs• L627-747
Change checklist
When these files or sections are changed, remember to consider these:
- Keep rule IDs, registry metadata, supported evidence phases, and all engine adapters aligned.
- When a shared check changes, compare static, browser, regex, and visual forms so their guards still express the same rule intent.
- When browser evidence changes, review snapshot fields, geometry, paint gates, hit-test answers, animation state, shadow-tree relationships, and the generated browser bridge together.
- When source extraction changes, preserve source offsets and keep style, class, and page-text corpora distinct.
- When pattern selectors change, define behavior for pseudo-element hosts, invalid selectors, no live matches, inactive state selectors, ignored ancestors, and unpainted matches.
- When visual contrast changes, keep candidate selection, surface ownership, pixel sampling, unresolved states, and duplicate suppression aligned.
- When context changes, review mockups, legal text, controls, status rows, selected states, chart labels, and design-system waivers together.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Source text matches a selector that is inactive or matches no live element | A source-only result can describe a pattern that a visitor never sees | Browser pattern checks resolve the selector and require a painted match; static scans keep the source result when runtime proof is unavailable |
| A browser capture lacks geometry, paint, or hit-test data | Runtime checks can lose the evidence needed to prove layout or visible contrast | Treat missing data as unresolved and use the source or analytic path instead of treating it as a pass |
| A target is hidden, clipped, transparent, or parked in a moving track | A style-based finding describes content that is not visible at rest | Apply the shared paint gate and the track/scroller context checks |
| A detached image, gradient, pseudo-element, or SVG shape sits under text | Analytic contrast can use the wrong background surface | Use structural layer checks, hit-test stacks, and visual sampling; keep unresolved surfaces unresolved |
| A source match and computed match describe one declaration | The report contains duplicate findings for one design choice | Let the computed browser finding or owning visual result suppress its source twin |
| A hidden app, carousel copy, modal background, or split-text node looks like a mockup | Real page content can be dropped or demoted incorrectly | Require the hidden mockup gates and preserve base behavior when the evidence is uncertain |
| A status-row stripe is sent through the card stripe path | A table or ARIA row marker can be missed or misread as a card accent | Route row and cell selectors through the dedicated row stripe check |
| An advisory context is inferred from a weak marker | A real control, legal action, or readable page body avoids a normal failure | Require positive structural evidence and keep controls, headings, forms, and policy bodies in their normal context |
Key files
| File | Why to read it |
|---|---|
| crates/…/rules.rs | Defines shared element decisions, contrast policy, advisory severity, and duplicate-claim behavior. |
| crates/…/css_scan.rs | Shows how authored CSS becomes source pattern findings and how uncertain source declarations stay unresolved. |
| crates/…/text_rules.rs | Defines shared text candidates and aggregate text rules used by browser adapters. |
| crates/…/decorative_text.rs | Defines decorative text shapes and the boundary between content and illustration text. |
| crates/…/text_context.rs | Defines framed demos, fine print, and micro-label context used to change finding policy. |
| crates/…/vectors_a.rs | Shows the replay contract for shared rules and source scanners. |
| crates/…/driver.rs | Shows browser collection, selector scoping, design-system checks, paint filtering, deduplication, and final attribution. |
| crates/…/element_checks.rs | Shows how browser measurements, pseudo-elements, surfaces, and context feed per-element rule decisions. |
| crates/…/page_checks.rs | Shows page-level layout, typography, card, occlusion, and viewport relationships. |
| crates/…/quality.rs | Shows browser text-quality checks and the use of rendered text geometry. |
| crates/…/text_collectors.rs | Shows browser collectors for kicker, numbered-label, repeated-text, and em-dash findings. |
| crates/…/text_geometry.rs | Shows text extents, scroller context, and moving-track handling. |
| crates/…/background.rs | Shows background walks, translucent compositing, and gradient surfaces under text. |
| crates/…/text_layers.rs | Shows hit-test interpretation for covered text and detached surfaces. |
| crates/…/visual.rs | Shows visual contrast candidates and the boundary between structural analysis and pixel sampling. |
| crates/…/decorative_text.rs | Shows how browser facts identify avatars, wordmarks, mockups, and other non-reading text. |
Related pages: UI quality detection system, detector command and configuration, detector analysis pipeline, browser analysis runtime, and design-system profiling.