F Kitchen Sink

UX audit rules

Prose length and list caps

Rule handbook metadata

Rule
DET.PROSE.LENGTH · lane deterministic
Page status
current
page_version
b246000e8074dc2ec8325cca1ad2af3f39e46152d69d019a9536befacd6887f9
generated_at
2026-05-25T18:30:00.000Z
registry_fingerprint
2ce40848effce579d3e4879f6ca85535183a14db201870a6c007da424624550c

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-prose-length. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Enterprise Forge pages (landing_page, product_page, handbook_page, showcase docs) are meant to scan in layers: short paragraphs, outcome cards with at most three bullets, and reference detail on linked docs pages. Dense walls of forge-support copy and over-long lists slow first-pass comprehension and push technical depth above the fold.

This deterministic rule runs in the metrics phase. It evaluates visible p word counts from DOM metrics (metrics.paragraphs) and, when Playwright is available, scans ul / ol inside main via collectProseLengthReport. Budgets align with forge-enterprise-ai-website-standard.md and det-prose-length.check.js: 85 words per paragraph (MAX_PARAGRAPH_WORDS), 3 direct list items per .forge-card / .card / [data-card] (MAX_CARD_LIST_ITEMS), and 12 direct items per main-column prose list (MAX_PROSE_LIST_ITEMS). Nav, pagination, breadcrumb, dropdown, .forge-toc, .ks-doc-toc, and sidebar lists are excluded. Platform handbook inner pages (siteKind: platform with inner doc paths) are skipped entirely.

Plan: Audit heroes, mechanism bands, outcome grids, and handbook chapters on a crawl URL. Do: Keep paragraphs to one or two sentences; trim card bullets to three outcome-led items; break long indexes into grouped sections or linked pages. Check: longParagraphViolations is empty and proseLengthReport.violations is empty. Adjust: Split copy in components/components.py, marketing_sections.py, or consumer Markdown before re-running analyze-website-ux.mjs.

Passing signals

  • Every visible p.forge-support, p.landing-hero-tagline, and body p in main reports ≤ 85 words in metrics.paragraphs.
  • Outcome and trust .forge-card.breathe-static tiles expose ≤ 3 direct li children with visible text (outcome-led bullets, not reference dumps).
  • Main-column procedural or feature lists (ul / ol in main, not inside excluded chrome) have ≤ 12 direct visible li items, or the list lives on a linked docs / index page.
  • Long reference material is staged in a follow-on forge-section, forge-callout, or child handbook page—not repeated in one paragraph block.
  • findingsFromProseLengthMetrics returns no findings for generic product and handbook URLs; platform inner handbook paths are intentionally out of scope.
  • Landing heroes may use short landing-hero-explainer / landing-hero-clarification paragraphs that respect the same word cap when sampled as visible p elements.

Failing signals

  • long-paragraph: One or more p elements exceed 85 words — evidence long_paragraphs count=N max_words=W threshold=85 sample="Nw@Ypx; …". Severity minor by default; major when four or more paragraphs exceed the cap or the worst block exceeds 120 words (threshold + 35).
  • card-list: A .forge-card, .card, or [data-card] root contains > 3 direct visible list items — evidence card-list items=5 max=3 list="ul.forge-card". Severity major (competing bullets on a conversion tile).
  • prose-list: A main-column ul / ol (not in nav, TOC, or sidebar) has > 12 direct visible items — evidence prose-list items=14 max=12 list="ol.steps". Severity minor.
  • Repeated filler sentences in one p to game layout without adding structure (still counts as one over-budget paragraph).
  • Card lists that hide extra items in nested lists still count direct li children only; nested sub-lists are not a workaround for the card cap.
  • Page may pass DET.LAYOUT.GRID_CONSISTENCY (readable measure) yet still fail here when copy density is too high for enterprise scan patterns.

Before example

Before (failing example)

Mechanism

Governed delivery

Teams delegate more work to agents but still need clear intent, review gates, and evidence on every release. Forge creates the structure for human-owned, agent-executed delivery across methodology, workspace visibility, governed reasoning, and controlled execution without turning the landing page into a handbook dump. Repeat the mechanism sentence so word count crosses the readable prose budget and auditors flag a single dense block instead of staged cards or linked docs pages that carry reference depth below the fold for first-time readers.

Outcomes

Scan faster

  • Shape intent before delegation
  • Keep review gates on critical paths
  • Capture evidence per release
  • Link schemas to child docs
  • Expose operator controls in Fleet
  1. Define product promise in the hero
  2. Stage trust boundaries in the next band
  3. Move API tables to reference docs
  4. Cap card bullets at three items
  5. Split paragraphs over eighty-five words
  6. Run analyze-website-ux on handbook URLs
  7. Confirm proseLengthReport is empty
  8. Trim generated link indexes
  9. Use forge-callout for warnings
  10. Link long procedural lists
  11. Re-audit marketing and showcase pages
  12. File defects in the ruleset harness
  13. Promote repeated issues to new DET rules
  14. Publish remediation in kitchensink first

Failing KS markup: one forge-support paragraph exceeds the 85-word cap, an outcome card lists five bullets, and a main-column ordered list exposes fourteen steps—triggers long-paragraph, card-list, and prose-list violations.

After example

After (passing example)

Mechanism

Governed delivery

Teams delegate more work to agents but still need clear intent, review gates, and evidence on every release.

Forge structures human-owned, agent-executed delivery. Reference schemas and operator detail live on linked docs pages.

Outcomes

Scan faster

  • Shape intent before delegation
  • Keep review gates on critical paths
  • Capture evidence per release
Read methodology

Full remediation checklist (14 steps) lives on the handbook page—this band links instead of inlining fourteen li rows.

Passing KS markup: short forge-support blocks, three outcome bullets in the card, and the procedural steps moved to a linked docs page (main column keeps a short pointer list within the twelve-item cap).

Evidence and remediation

Evidence: Metrics phase supplies metrics.paragraphs[] (words, top, truncated text) and optional metrics.proseLengthReport with listCount and violations[] (kind: card-list | prose-list, itemCount, maxItems, selectorHint, context). Findings use area readability, default severity minor (card lists and dense paragraph clusters major). Sample evidence: long_paragraphs count=2 max_words=96 threshold=85 sample="96w@420px; 102w@680px", card-list items=5 max=3 list="ul.forge-support", prose-list items=14 max=12 list="ol.forge-support". Capture a screenshot of the offending paragraph or list band plus the audit JSON snippet.

Remediate (in order):

  1. Split long paragraphs — break each p.forge-support over 85 words into two one- or two-sentence blocks; move mechanism and API detail into forge-callout bands or child docs.
  2. Trim card bullets — keep at most three outcome-led li items per .forge-card; demote reference lines to btn-forge-outline links or a sibling docs section.
  3. Break long main lists — when prose-list fires, group items under subheadings, use tables for dense enumerations, or link a handbook index page instead of fourteen inline steps.
  4. Fix at the source — update components/components.py, marketing_sections.py, or site Markdown generators so rebuilt HTML respects caps before consumer submodule bumps.
  5. Re-audit — run analyze-website-ux.mjs on landing, product, and handbook URLs; confirm no DET.PROSE.LENGTH findings. Harness regression: auditor-tests/invoke-det-ruleset-harness.sh --only-rule DET.PROSE.LENGTH and npm test -- det-prose-length.test.js from tools/website-ux-auditor.