F Kitchen Sink

UX audit rules

App density balance

Rule handbook metadata

Rule
AI.APP.DENSITY_BALANCE · lane ai
Page status
stale
page_version
2d2d266d5695bd7cd7524f96ba9a8294900d4df7e4a061b26a5eea6b3681be28
generated_at
2026-05-19T18:22: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-app-density-balance. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink desktop interfaces (data-ks-type="desktop-interface", museum studio shell Msm, Lenses-style operator UIs) may show more controls per screen than marketing pages. This AI rule judges whether that density still feels governed: grouped regions, labeled chrome, and obvious next actions—not a flat wall of equal-weight widgets.

Deterministic checks (DET.APP.PERSISTENT_CHROME, DET.LANDMARKS.REQUIRED) catch stable shell landmarks and hashes; this rule covers judgment they miss: mystery icon toolbars, duplicate nav rails, diagnostic dumps without headings, and workspace panes where every block shouts at the same volume.

Plan: On shell screenshots, trace header → side nav → workspace. Note where labels, grouping, or hierarchy break down. Do: Regroup into forge-card / ks-wizard-flow__panel, promote mode switching into ks-workspace-lens__segments, and label persistent regions. Check: An operator can answer “where am I?”, “what failed?”, and “what do I click next?” in one pass. Adjust: If unlabeled control grids or panel stacks repeat, propose a deterministic DET.* threshold.

Passing signals

  • Persistent chrome (header, nav, aside) stays stable; route-specific density lives in main (DET.APP.PERSISTENT_CHROME).
  • Regions use visible labels: nav-section-label, card-label, ks-workspace-lens__eyebrow, or ks-wizard-flow__muted—not anonymous icon-only toolbars.
  • Related controls cluster in forge-card or ks-wizard-flow__panel blocks with one job per card (status, sessions, setup, diagnostics).
  • Workspace Lens (ks-workspace-lens__segments) and wizard session lists (ks-wizard-flow__session-list) separate modes instead of repeating the same destinations in three places.
  • Monospace or diagnostic output sits in bounded, scrollable panels with a takeaway heading; primary actions use btn btn-primary (or btn-sm when secondary) on labeled surfaces.
  • Overflow uses scroll containers; panels do not overlap unreadably at documented minimum widths (Msm contract).

Failing signals

  • Flat grids of identical btn btn-sm controls with no text labels, aria-label, or grouping—reads as “mystery icons.”
  • Three or more competing focal bands at the same visual weight (hero-sized titles inside a console, duplicate nav rails, floating unlabeled stacks).
  • Diagnostics, tables, and forms interleaved in one column with no forge-card or panel boundaries.
  • Support copy shrunk with ad-hoc opacity-50 or inline font-size hacks instead of promoting content to a labeled region.
  • Session lists, breadcrumbs, and global nav repeat the same destinations with different labels.
  • Dense data without takeaway headings—operators cannot tell which block answers “what failed?” vs “what do I do next?”

Before example

Before (failing example)

Studio

Workspace

job=forge-lenses-docs-health status=RUNNING queue=3 worker=node-7
last_event=2026-05-19T18:01:02Z detail=container argv drift

Select an item.

Failing KS markup: Msm shell with unlabeled icon wall, raw dumps, and no regional grouping.

After example

After (passing example)

Lenses Studio

Workspace Lens Flow

Active job

forge-lenses-docs-health

Container argv job · queue 3 · worker node-7

Diagnostics

Last event 2026-05-19T18:01:02Z — argv drift detected

detail=container argv drift

Passing KS markup: labeled chrome, Lens mode control, wizard session rail, and card-grouped workspace panes.

Evidence and remediation

Capture: full-shell screenshot at desktop width and at the Msm minimum width; crop header, side nav, and primary workspace card. On route change, confirm chrome stays stable while only main swaps.

Remediate (in order):

  1. Label every persistent region (nav-section-label, card-label, Lens eyebrows); add aria-label to icon-only controls or replace with text buttons.
  2. Group related blocks into forge-card or ks-wizard-flow__panel; one primary action per card.
  3. Move mode switching into ks-workspace-lens__segments; dedupe repeated nav links (DET.NAV.DEDUP candidate if stable).
  4. Bound diagnostics in scrollable panels with a takeaway heading—not raw <pre> stacks in the main column.
  5. Re-check DET.APP.PERSISTENT_CHROME and DET.LANDMARKS.REQUIRED; if icon grids or panel stacks repeat, propose a deterministic threshold (e.g. max unlabeled controls per toolbar).