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 / design-system-profiling

Design system profiling

Design system profiling turns a project's declared visual rules and its authored or rendered UI into comparable evidence. The detector uses that evidence to find drift in fonts, colors, corner shapes, and type sizes without treating missing or unreadable design data as a clean result. It is part of the UI quality detection system, alongside the command and configuration, analysis pipeline, and detection engines.

Evidence extraction

Extraction turns different CSS and markup forms into common values before comparison. This lets source scans and rendered-page scans recognize the same design evidence even when authors use CSS functions, font stacks, shorthand declarations, or Google Fonts URLs.

Color evidence

The shared color utility reads common CSS color forms and converts them to a comparable RGB representation. It also handles modern color spaces, transparency, gradients, color-mix(), and selected named colors. Other checks use the same representation for luminance, contrast, chroma, hue, and compositing, so color analysis can work across authored and computed values. cli/…/color.mjs• L74-129 cli/…/color.mjs• L342-398 cli/…/color.mjs• L432-553

Color matching allows a small channel difference because a browser or authoring format can produce a near-equivalent value. Shadow colors remain a separate vocabulary: a shadow token must match both its color channels and its alpha, and it is allowed only in a shadow context. This keeps a documented shadow black from becoming an allowed page background. cli/…/color.mjs• L74-129 cli/…/color.mjs• L342-398 cli/…/color.mjs• L432-553

References: cli/…/color.mjs• L74-129 cli/…/color.mjs• L342-398 cli/…/color.mjs• L432-553

Font evidence

Font extraction reduces a font stack to its first non-generic family. The shared font utility also reads every family in Google Fonts links, which supports page-level typography checks when a font is declared in markup rather than in a local stylesheet. cli/…/fonts.mjs• L1-30 cli/…/checks.mjs• L4054-4089

Font profiling also has a catalog index for matching measured lettering to likely font faces. It routes a crop to a size-specific catalog view and uses a separate all-caps view when available; it limits repeated results from one family and excludes catalog faces that are not usable text. If the index is absent, callers can use a built-in shortlist instead. skill/…/font-index.mjs• L29-41 skill/…/font-index.mjs• L63-129

References: cli/…/fonts.mjs• L1-30 cli/…/checks.mjs• L4054-4089 skill/…/font-index.mjs• L29-41 skill/…/font-index.mjs• L63-129

Page evidence

The page utility distinguishes a complete document from a component or partial. Full-page checks use this boundary so a fragment is not judged as if it defined the whole page. The same distinction is shared by the regex engine and the public detector API. cli/…/page.mjs• L1-7 cli/…/detect-text.mjs• L39 cli/…/detect-html.mjs• L210-234

References: cli/…/page.mjs• L1-7 cli/…/detect-text.mjs• L39 cli/…/detect-html.mjs• L210-234

Detector profiling

Detector profiling measures the work that produces findings and the work that prepares evidence. A profile is an event stream grouped by engine, phase, rule, and target; each event records duration and finding count, with optional detail and finding IDs.

Profile events

The profiler wraps synchronous and asynchronous steps without changing their return values. Finding-producing steps record how many findings they return and which rule IDs they contain. Setup and other analysis phases can therefore be compared in one view. cli/…/profiler.mjs• L7-93

References: cli/…/profiler.mjs• L7-93

Profile summaries

Profile summaries group repeated events and report call count, total time, average time, and p50 and p95 samples. The summary sorts groups by total time, which helps an engineer find the costly analysis phase without reading every event. cli/…/profiler.mjs• L95-152

References: cli/…/profiler.mjs• L95-152

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep color parsing and color comparison changes shared across source, static cascade, and browser paths. A format supported in one path but not another creates inconsistent results.
  • Keep profiler phase and rule names stable when consumers compare profile summaries over time.
  • Keep the font index schema, stored sizes, and fingerprint fields aligned with the catalog builder and font matcher. A stale index can return plausible but wrong font candidates.

Important failure modes

TriggerConsequenceGuard
A font catalog index is missing or uses a mismatched schemaFont matching falls back or ranks faces from the wrong catalog viewRebuild and load the index with the shared schema, sizes, and feature list

Key files

FileWhy to read it
cli/…/color.mjsDefines the shared color vocabulary and conversion used by consistency and visual checks.
cli/…/fonts.mjsDefines Google Fonts family extraction used by typography evidence checks.
skill/…/font-index.mjsDefines the catalog index used to shortlist measured font faces by fingerprint and cap-height view.
cli/…/page.mjsDefines the full-page boundary used by page-level analysis.
cli/…/profiler.mjsDefines profile events and performance summaries for detector phases.