F Kitchen Sink

UX audit rules

Visual hierarchy

Rule handbook metadata

Rule
AI.VISUAL.HIERARCHY · lane ai
Page status
stale
page_version
ec93b09eb3c72879f87748ded10effcf98d81ad21640eebac2c9f0c27019584a
generated_at
2026-05-19T23:48: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-visual-hierarchy. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink landing_page, product_page, and forge-section bands communicate through visual weight—type scale, contrast steps, grouping, and CTA prominence—not only copy order. This AI rule judges whether a first-time scanner can answer "what do I read next?" without hunting: a clear hero focal point, a proof or outcomes band that supports it, then depth (mechanism, trust, reference) at deliberately lower weight.

Deterministic checks (DET.CTA.HIERARCHY, DET.BUTTON.GROUP.MAX, DET.SECTION.HEADING) catch button-class scans and heading ladders; they do not judge whether every tile, label, and accent competes at the same volume. A page can pass CTA class rules yet still present four equal primaries, three display-scale headlines in one viewport, or outcome cards that all shout with card-amber and forge-gradient-text.

Plan: Mark the intended focal path (hero headline → primary CTA → first proof band → mechanism). Do: Demote secondary actions to btn-cyan-outline / landing-hero-secondary-link; reserve card-amber and gradient display type for one beat per band. Check: Squint test—one dominant shape in the hero; proof band reads as support, not a second homepage. Adjust: When the same equal-weight pattern repeats, propose deterministic companions (CTA count caps, accent-role lint) or align with AI.VISUAL.HIERARCHY_CONFIDENCE promotion.

Passing signals

  • Single hero focal: one product-landing-title (font-display forge-gradient-text) dominates the fold; supporting copy uses landing-hero-tagline / forge-support at clearly lower weight.
  • CTA ladder: one btn btn-forge primary in landing-hero-actions__buttons; secondary uses btn-cyan-outline or landing-hero-secondary-link—not four filled buttons at the same size.
  • Contrast steps: section eyebrows use section-label text-cyan; band titles use h3; card titles use h5—no band opens with two display-scale headlines side by side.
  • Hero → proof → depth: outcomes or trust tiles (forge-card + card-label) appear before dense reference tables or API indexes; proof cards share one elevation language (breathe-link / breathe-static).
  • Restrained accent: at most one card-amber column per row draws extra attention; sibling tiles stay default forge-card so the featured outcome is obvious.
  • Grouping: related controls sit in one landing-hero-actions or forge-section container with consistent g-3 / g-4 gaps—readers perceive chunks, not scattered widgets.
  • Visual defers to narrative: hierarchy supports problem → outcome → mechanism (AI.NARRATIVE.COHERENCE); decorative diagrams in landing-hero-visual do not outrank the headline.

Failing signals

  • Equal-weight shouting: hero shows multiple h2/h3 elements, badge rows, and stat callouts at similar size—no clear first read.
  • CTA democracy: three or four filled buttons (btn-forge, btn-warning, btn-success) in one landing-hero-actions row—scanner cannot pick a primary path (DET.BUTTON.GROUP.MAX may pass class heuristics while judgment still fails).
  • Accent overload: every outcome tile uses card-amber, cyan borders, and forge-gradient-text—nothing reads as support material.
  • Competing focal bands: sticky promo bar, sidebar signup, and hero primary CTA share the same visual volume and color role.
  • Proof before focal: reference/API forge-card or diagram wall sits in the first viewport beside a half-size headline—depth competes with the hero job.
  • Flat section bands: five consecutive forge-section blocks each open with h3 + three equally styled cards—no contrast step between "main story" and "supporting detail".
  • Typography drift: inline font-size / font-weight overrides on headings break the Forge scale; body copy outside forge-support patterns fights card titles for attention.
  • Decorative dominance: ambient mesh, oversized raster in landing-hero-visual, or animated accents draw the eye before product-landing-title copy.

Before example

Before (failing example)

Forge Platform

New: Agent orchestration

Governed delivery

Plus LCDL · Fleet · Lenses

Everything you need for AI-assisted SDLC—in one banner.

Start free Book demo See pricing Read docs

Live stats

99.9% uptime

Why teams choose Forge

Control

Human gates everywhere.

Speed

Ship 10× faster with agents.

Compliance

Certified out of the box.

Failing KS markup: competing display headlines, four equal primaries, and outcome tiles that all shout at the same weight.

After example

After (passing example)

Forge Platform

Governed delivery you can inspect

One headline carries the fold; tagline and CTAs stay visibly subordinate.

Start with Quickstart See how it works

Read architecture docs

Spine from intent through review to evidence

Outcomes

What changes for your team

Primary outcome

Human-owned gates

One accented tile marks the hero proof point; siblings stay quieter.

Supporting

Evidence trail

Default elevation and body scale—readable, not competing.

Supporting

Bounded automation

Depth links appear after the eye learns the focal path.

How it works

Mechanism at lower weight

Mechanism and reference bands use section labels and body copy—not a second display headline in the fold.

Passing KS markup: one hero focal, restrained CTA pair, proof band with a single accented tile, and calmer siblings.

Evidence and remediation

Capture: first-viewport screenshot with blur/squint check annotated; DOM outline of headings (h1–h3) and button classes in landing-hero-actions; list of accent roles per row (card-amber, forge-gradient-text, filled vs outline buttons). Note where a second band equals hero weight.

Remediate (in order):

  1. Collapse hero to one product-landing-title; demote announcements to landing-hero-kicker or a later forge-section.
  2. Enforce one btn-forge primary; move extras to btn-cyan-outline, landing-hero-secondary-link, or below the fold (DET.CTA.HIERARCHY).
  3. Cap horizontal hero actions at two visible primaries; tuck overflow behind docs/nav (DET.BUTTON.GROUP.MAX).
  4. In outcome rows, feature one card-amber tile; set siblings to forge-card breathe-static without gradient titles.
  5. Re-stage bands: proof before API/reference dumps; lower mechanism/reference headings to h3 + forge-support (AI.NARRATIVE.COHERENCE).
  6. Remove inline heading overrides; restore section-label → h3 → card h5 ladder (DET.SECTION.HEADING).
  7. If the same equal-weight defect repeats, record a candidateDeterministicRule (for example accent-role count per row) and cross-link AI.VISUAL.HIERARCHY_CONFIDENCE.