F Kitchen Sink

UX audit rules

Chrome boundary separation

Rule handbook metadata

Rule
DET.CHROME.BOUNDARY · lane deterministic
Page status
stale
page_version
f76b4b124b9d5e2362faab0ea9bf8d6854faecdaee21e15455e8fc96a942335c
generated_at
2026-05-19T20:15:00.000Z
registry_fingerprint
6773fda516344e110b5a7b1435e655e1264e773825ca8bbe62194189891c42ba

How this rule is fixed

Pilot deterministic fixer: handbook_after · harness mode standalone · verify expect_rule_clean.

  • Harness: apply-harness-fixture-remediation.py copies the After example HTML from this handbook page onto the defect fixture, then invoke-det-ruleset-remediation-verify.sh re-audits and expects zero findings for this rule.
  • Production sites: run-website-ux-remediation-loop.sh runs handbook_html_patch (HTML patches in lib/ux-deterministic-fixers/fixers/patches/) before invoking the Cursor agent when the quality gate still fails.

Detection module: docs/design/ux-audit/deterministic-design-rules.md#det-chrome-boundary. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Handbook, product, and app shells use chrome regions outside main — site-header, Ksr doc rail (aside.forge-sidebar), Ksf footer (.ks-site-footer-region), product mastheads (Kpn), and [data-shell-region] roots. Readers must see where chrome ends and the content canvas begins without guessing from whitespace alone.

This deterministic rule samples computed styles on visible chrome roots that sit outside main and overlap the main column in the viewport. A region passes when at least one separation cue is present: a visible border on any edge (≥ 0.5px and non-transparent color), a non-zero box-shadow, a chrome background whose luminance differs from the main canvas by ≥ 0.06, or a qualifying ::before / ::after separator (border, shadow, or filled pseudo). Cues must match the chrome-region design contract (Ksr, Ksf, Kpn, etc.).

Plan: Identify contracted chrome roots per layout. Do: Apply KS tokens (var(--forge-border), var(--forge-bg) elevation) on the edge facing main. Check: chromeBoundaryReport.violations is empty. Adjust: Add border-right on .forge-sidebar, border-bottom on .site-header, or border-top on .ks-site-footer-region before weakening contrast.

Passing signals

  • aside.forge-sidebar (Ksr) shows border-right: 1px solid var(--forge-border) (theme default) or an equivalent contract-aligned edge facing main.
  • .site-header carries border-bottom (showcase/handbook CSS) so the masthead band separates from .doc-main / main.
  • .ks-site-footer-region (Ksf) uses a top border or distinct footer background so closing utilities do not bleed into the last main section.
  • Chrome background luminance differs from the effective main canvas by ≥ 0.06 when borders are omitted by design (for example a raised app header panel).
  • ::after / ::before pseudo separators on chrome roots register as cues when they draw a visible edge (.forge-sidebar::after texture is additive; the rail still needs a real boundary cue on the element or pseudo).
  • Modals, offcanvas drawers, cookie banners, and elements inside main are out of scope — only persistent shell chrome is measured.

Failing signals

  • missing-boundary: A visible header, footer, aside.forge-sidebar, .site-header, .landing-header, .ks-site-footer-region, or [data-shell-region] outside main overlaps the main column but reports cuesFound: none.
  • Chrome and main share the same flat var(--forge-bg) with no border, shadow, or luminance delta — sidebar and reading column look like one surface.
  • Inline overrides such as border-right: none / border-bottom: none on contracted rails remove all measurable cues.
  • Footer band flush with the last paragraph block — no top edge or background step before Ksf links.
  • Relying on text color alone without a structural separator on the chrome root (typography contrast does not count).

Before example

Before (failing example)

F Forge

Chapter

Body

Sidebar and header visually merge with main — no measurable boundary.

© Forge — footer band indistinguishable from main.

Failing KS markup: handbook-style shell with Ksr / Ksf hashes present but borders stripped and chrome background matched to main — auditor finds no border, shadow, or background cue.

After example

After (passing example)

F Forge

Handbook

Chapter

Body

Chrome edges are visible; reading column stays clearly inside main.

Docs

© Forge

Passing KS markup: same handbook anatomy with contract-aligned separators — theme .forge-sidebar border, .site-header bottom edge, Ksf top rule.

Evidence and remediation

Evidence: Metrics phase emits chromeBoundaryReport with chromeRegionCount and violations[] (kind: missing-boundary, role, selectorHint, cuesFound: none). Findings use area informationArchitecture, severity warn, and evidence such as missing_chrome_boundary role=sidebar hint="aside.forge-sidebar[@Ksr]" cues=none. Capture a full-viewport screenshot with devtools highlighting the chrome root and computed border/background on the edge facing main.

Remediate (in order):

  1. Restore the contract edge — re-enable border-right on .forge-sidebar, border-bottom on .site-header, or border-top on .ks-site-footer-region using var(--forge-border); remove inline border-*: none overrides.
  2. Use a distinct chrome background token — when borders are intentionally minimal, set a chrome surface token with ≥ 0.06 luminance delta from the main canvas (do not match var(--forge-bg) on both sides without another cue).
  3. Add a subtle shadow last — prefer borders/tokens first; use a sanctioned box-shadow only when the design contract allows elevation instead of a hairline.
  4. Update the design contract — if anatomy changes, revise Ksr / Ksf / Kpn expected-look and re-run showcase build so hashes and contracts stay aligned.
  5. Re-audit — run analyze-website-ux.mjs on representative handbook and product URLs; confirm chromeBoundaryReport.violations is empty.