F Kitchen Sink

UX audit rules

Product explanatory value

Rule handbook metadata

Rule
AI.VISUAL.PRODUCT_EXPLANATORY_VALUE · lane ai
Page status
stale
page_version
4dee66f4af47e261345697e2c7252c0e126ffd540c16c1b299bb248142f7b72f
generated_at
2026-05-19T22: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-visual-product-explanatory-value. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink product surfaces—render_product_landing_hero, landing-forge-visual, forge-diagram / ks-diagram-tile, outcome forge-card bands, and chart mounts—often pass hash, alt-classification, and label checks while still failing the visitor's real question: what does this product do, and what should I learn from this picture?

Deterministic rules prove diagrams have labels (DET.DIAGRAM.LABELS), alt policy is coherent (DET.DIAGRAM.ALT), assets are registered (DET.DIAGRAM.ASSET_REGISTRY), and charts expose summaries (DET.CHART.ALT_SUMMARY). Legacy product-visual heuristics flag missing or decorative hero imagery on homepages. This AI rule judges explanatory value: whether the visual teaches product structure, mechanism, or outcome tied to adjacent claims—not wallpaper, stock icon grids, or interchangeable cloud-platform art.

Plan: For each informative visual block, read the headline, support copy, and caption together with the figure. Ask what a first-time reader learns that they could not learn from text alone. Do: Replace decorative assets with mechanism diagrams, labeled architecture, or product screenshots; write captions that name actors, boundaries, and benefit. Check: Removing the visual would lose a concrete mental model, not just atmosphere. Adjust: When the same decorative pattern repeats (empty-alt spectral hero, unlabeled icon grids), propose a DET.* candidate or tighten catalog decorative_rule / contract semantics.

Passing signals

  • Hero visual answers the headline: landing-hero-visual shows a governance spine, workspace screenshot, or registered diagram whose alt names the same outcome as product-landing-title and landing-hero-tagline (informative images are not role="presentation" with empty alt).
  • Caption earns its space: figcaption, forge-support under the tile, or landing-hero-clarification states structure or benefit (Intent → Human review → Agent execution → Evidence)—not "our powerful platform."
  • Diagrams tied to claims: forge-diagram / ks-diagram-tile in a labeled forge-section uses a catalog key or template that matches the section mechanism story; expand triggers (forge-diagram-trigger, data-diagram-key) deepen the same narrative.
  • Icons map to product layers: card or band icons label control plane, data boundary, or workflow step—not anonymous glyphs at equal weight.
  • Charts teach outcome: takeaway copy sits beside ks-chart-mount (see AI.DATA.INSIGHT_LEGIBILITY); color emphasis supports the sentence, not decoration alone.
  • Decorative assets stay decorative: ambient sinusoids and spectral backgrounds use aria-hidden / empty alt behind copy, not as the only product proof in the fold.
  • Visual type matches intent: landing-hero-visual--cover raster art shows real UI chrome; SVG templates are chosen for the mechanism class (gate chain, linear flow)—not whichever thumbnail looked polished.

Failing signals

  • Generic hero filler: landing-forge-visual with role="presentation", empty alt, and a spectral or mesh background while copy promises governed delivery architecture.
  • Stock metaphor soup: unlabeled icon grids, cloud + lock + gear tiles, or assets/svg/diagrams/generic-cloud.svg with no mapping to product nouns on the page.
  • Caption-free mechanism: dense ks-diagram-canvas topology with no figcaption, support line, or expandable legend—visitor must infer structure from shapes alone.
  • Misleading classification: informative diagram marked decorative (DET.DIAGRAM.ALT may pass category while explanatory value still fails).
  • Duplicate story, zero visual information: hero image repeats the headline verbatim with no new nodes, boundaries, or workflow steps.
  • Decoration at hero scale: largest above-fold visual is ambient texture or brand flourish; real mechanism diagram pushed far below the headline.
  • Placeholder art: lorem diagram labels, Feature / Feature / Feature cards with identical glyphs and no anatomy link to contracts or hashes.

Before example

Before (failing example)

Forge Platform

Governed human and agent delivery

See how intent, review gates, and evidence connect across your workspace.

Why teams choose us

Everything you need

Secure

Enterprise-grade protection

Fast

Move at AI speed

Smart

Powered by agents

Failing KS markup: headline claims governed delivery, but the hero visual is decorative spectral art with empty alt; a generic cloud icon sits in an outcome card with no product mapping.

After example

After (passing example)

Forge Platform

Governed human and agent delivery

Structure intent, keep human review gates, and ship with evidence—not ambient decoration alone.

The diagram shows the same spine the product implements: intent → review → bounded agent work → release artifact.

Gate chain: Intent, Human review gate, Agent execution inside scope, Release with evidence

Outcomes

What each layer gives you

Human control

Review before agent work

Gates in the diagram match operator-owned approval points—not a generic lock icon.

Evidence

Artifacts you can inspect

Release node ties to logs and contracts linked from this handbook.

Mechanism

Full gate-chain detail

Expand the registered diagram below for labels and catalog legend keys.

How it works

Gate chain matches the hero visual

Follow left-to-right: intent is shaped, humans approve, agents execute inside scope, then release carries evidence.

Gate chain: Intent, Human review gate, Agent execution, Release checkpoint

Same topology as the hero: captions name actors and order so the visual teaches structure, not mood.

Passing KS markup: hero visual is an informative governance diagram with meaningful alt; outcome cards name mechanisms; a below-fold diagram section ties caption to topology.

Evidence and remediation

Capture: screenshot of hero and any diagram/chart band at desktop and narrow widths; copy alt, figcaption, and the headline or landing-hero-tagline they should support; note data-diagram-key, src, and catalog contract paths; record whether hero_primary_visual.decorative_guess fired in analyzer output.

Remediate (in order):

  1. State the one-sentence mechanism or benefit the visual must teach (actors, boundaries, order, artifact).
  2. Replace decorative hero assets with a registered diagram, product screenshot, or labeled architecture; fix alt and role / aria-hidden classification (DET.DIAGRAM.ALT).
  3. Add or tighten caption / clarification copy (landing-hero-clarification, forge-support under ks-diagram-tile) so it names structure—not marketing adjectives.
  4. Swap generic icon grids for outcome cards that reference real layers (card-label, linked trust or how-it-works sections).
  5. For charts, add takeaway titles and summaries (AI.DATA.INSIGHT_LEGIBILITY, DET.CHART.ALT_SUMMARY).
  6. Re-run AI review; if empty-alt spectral heroes repeat across consumers, propose a deterministic decorative-vs-informative proxy or homepage product-visual threshold tightening.