Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / detector-engines-and-rules

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.

EngineMain evidenceMain limit
RegexCSS, JavaScript, JSX, TSX, component text, and page textCannot prove the final cascade or rendered state
Static HTMLParsed HTML, local styles, cascade, structure, and source patternsCannot prove runtime layout, scripts, hit tests, or pixels
BrowserLive or captured DOM, computed styles, geometry, state, and paintDepends on page capture and browser evidence
VisualRendered text and background pixelsUnreadable 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 groupWhat it decides
Element checksOne element and the context that gives it meaning
Page checksRelationships among elements, source regions, or viewport areas
Source and text checksAuthored CSS, markup, code, copy, or aggregate text patterns
Pattern checksWider 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:

  1. An engine gathers evidence for an element, page, or source region.
  2. A check applies its guards and returns one or more rule matches.
  3. The engine removes duplicates, inactive forms, ignored targets, and findings that fail the engine's evidence gate.
  4. The finding layer applies metadata, severity, advisory policy, attribution, and serialization.
  5. 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

TriggerConsequenceGuard
Source text matches a selector that is inactive or matches no live elementA source-only result can describe a pattern that a visitor never seesBrowser 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 dataRuntime checks can lose the evidence needed to prove layout or visible contrastTreat 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 trackA style-based finding describes content that is not visible at restApply the shared paint gate and the track/scroller context checks
A detached image, gradient, pseudo-element, or SVG shape sits under textAnalytic contrast can use the wrong background surfaceUse structural layer checks, hit-test stacks, and visual sampling; keep unresolved surfaces unresolved
A source match and computed match describe one declarationThe report contains duplicate findings for one design choiceLet 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 mockupReal page content can be dropped or demoted incorrectlyRequire the hidden mockup gates and preserve base behavior when the evidence is uncertain
A status-row stripe is sent through the card stripe pathA table or ARIA row marker can be missed or misread as a card accentRoute row and cell selectors through the dedicated row stripe check
An advisory context is inferred from a weak markerA real control, legal action, or readable page body avoids a normal failureRequire positive structural evidence and keep controls, headings, forms, and policy bodies in their normal context

Key files

FileWhy to read it
crates/…/rules.rsDefines shared element decisions, contrast policy, advisory severity, and duplicate-claim behavior.
crates/…/css_scan.rsShows how authored CSS becomes source pattern findings and how uncertain source declarations stay unresolved.
crates/…/text_rules.rsDefines shared text candidates and aggregate text rules used by browser adapters.
crates/…/decorative_text.rsDefines decorative text shapes and the boundary between content and illustration text.
crates/…/text_context.rsDefines framed demos, fine print, and micro-label context used to change finding policy.
crates/…/vectors_a.rsShows the replay contract for shared rules and source scanners.
crates/…/driver.rsShows browser collection, selector scoping, design-system checks, paint filtering, deduplication, and final attribution.
crates/…/element_checks.rsShows how browser measurements, pseudo-elements, surfaces, and context feed per-element rule decisions.
crates/…/page_checks.rsShows page-level layout, typography, card, occlusion, and viewport relationships.
crates/…/quality.rsShows browser text-quality checks and the use of rendered text geometry.
crates/…/text_collectors.rsShows browser collectors for kicker, numbered-label, repeated-text, and em-dash findings.
crates/…/text_geometry.rsShows text extents, scroller context, and moving-track handling.
crates/…/background.rsShows background walks, translucent compositing, and gradient surfaces under text.
crates/…/text_layers.rsShows hit-test interpretation for covered text and detached surfaces.
crates/…/visual.rsShows visual contrast candidates and the boundary between structural analysis and pixel sampling.
crates/…/decorative_text.rsShows 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.