F Kitchen Sink

UX audit rules

Ambient readability conflict

Rule handbook metadata

Rule
AI.AMBIENT.READABILITY_CONFLICT · lane ai
Page status
stale
page_version
b57d41c04c058844ed2078a8c6d7d7c371c12771c57c68fe8ae70e719a110e9b
generated_at
2026-05-19T16:45:00.000Z
registry_fingerprint
6773fda516344e110b5a7b1435e655e1264e773825ca8bbe62194189891c42ba

How this rule is fixed

This is an AI-enabled rule. Pass/fail requires model judgment; there is no deterministic fixer in the pilot registry.

  • Harness: invoke-ai-ruleset-harness.sh runs design-rules/ai/run-design-ai-rule.sh on the Before fixture and expects findings with matching principleId.
  • Remediation: Cursor agent plans from forge-ux-remediation.plan.md after sitewide audit — not handbook After copy.

Detection module: docs/design/ux-audit/ai-enabled-design-principles.md#ai-ambient-readability-conflict. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink ships Forge ambient (.forge-ambient, .forge-ambient-bg, .forge-ambient-scrim, .forge-ambient-content) and the living background system (#ks-living-scene, .ks-living-layer--back|mid|front) to add atmosphere without replacing content. This AI rule judges whether those layers still let visitors read headlines, support copy, and primary actions at a glance.

Deterministic checks (DET.AMBIENT.Z_INDEX, DET.THEME.CONTRAST_MIN) catch stacking and sampled contrast; this rule covers judgment that numbers miss: busy particles behind thin type, sparks crossing button edges, parallax drift that makes labels feel unstable, or scrims so weak that accent lines read through body text.

Plan: On hero and band screenshots, note where ambient intensity, motion, or missing separation overlaps readable UI. Do: Tune intensity modifiers (forge-ambient--subtle), scrim tokens, and foreground surfaces before weakening brand motion. Check: First-screen copy and CTAs stay legible in still captures and with prefers-reduced-motion: reduce. Adjust: If the same failure repeats across pages, propose a deterministic companion (for example mandatory scrim when hero and expressive modifiers combine).

Passing signals

  • Foreground copy and CTAs sit in forge-ambient-content with a readable scrim (forge-ambient-scrim) when the ambient style is medium or stronger.
  • Intensity modifiers match the job: forge-ambient--subtle for explanatory bands; reserve forge-ambient--hero + forge-ambient--expressive for short headlines with strong scrim and card/surface wrappers.
  • Support and secondary text use full theme contrast (forge-support without ad-hoc opacity-50 on critical lines).
  • Primary actions use btn btn-primary on an opaque or card-backed surface (forge-card), not directly on un-scrimmed mesh lines.
  • Ambient SVG/canvas stays behind content per DET.AMBIENT.Z_INDEX; reduced-motion paths quiet animation without removing the scrim.

Failing signals

  • Hero + expressive mesh-bloom behind a full paragraph and CTA with no forge-ambient-scrim.
  • Body or support copy forced to opacity-50 (or similar) to fit the atmosphere instead of adjusting ambient intensity.
  • Spark/node density competes with link underlines, focus rings, or card borders.
  • Multiple stacked ambient planes (mesh + parallax + living background) with no unified scrim on the reading column.
  • Controls appear disabled because contrast under particles/canvas fails the intended hierarchy—even when raw token math is borderline.

Before example

Before (failing example)

Governed agent delivery

Intent, delegation, review gates, and evidence—without losing readability under the mesh.

Failing KS markup: hero + expressive mesh-bloom, no scrim, faded support text.

After example

After (passing example)

Governed agent delivery

Intent, delegation, review gates, and evidence—with ambient tone behind a scrim and card surface.

Passing KS markup: subtle mesh-bloom with scrim and forge-card wrapper for copy and CTA.

Evidence and remediation

Capture: full-section screenshot (light and dark if themed), zoom on first-screen copy + primary CTA, and a contrast sample under the ambient stack. Note prefers-reduced-motion behavior.

Remediate (in order):

  1. Add or strengthen forge-ambient-scrim; step down to forge-ambient--subtle (or medium) if hero/expressive modifiers are not required.
  2. Remove opacity hacks on forge-support; fix ambient intensity instead.
  3. Wrap reading columns in forge-card or an equivalent opaque surface when mesh/canvas remains visible.
  4. Re-check DET.THEME.CONTRAST_MIN on real foreground colors (not assumed defaults).
  5. If the pattern repeats, propose a deterministic companion (e.g. scrim required when hero and expressive modifiers combine).