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

Purpose

Kitchen Sink landing_page shells (components/layouts.py, css/forgesdlc-theme.css) are meant to lead with a product story: curated landing-header / landing-nav, a landing-hero band, and depth routes under /docs or /handbook. When a public homepage reuses handbook chrome—fs-primary-nav-global, persistent fs-sidebar, offcanvas trees, and wide link walls—the first screen reads as documentation before the visitor sees what the product does.

This deterministic rule enforces the Forge enterprise first-screen budget from docs/design/forge-enterprise-ai-website-standard.md using crawl metrics and a Playwright hero-fold probe:

Interactive controls count visible <button>, [role="button"], .btn anchors, and submit/button inputs in the hero fold, excluding pagination, dropdown menus, and in-nav controls. Platform handbook inner routes are skipped (same pattern as docs readers).

Plan: Audit / and primary landing URLs for chrome and link counts above the fold. Do: Switch root pages to landing_page shell; curate landing-nav-link items; demote depth to sidebars on deep routes only. Check: Confirm crawl metrics and contextBurdenReport.heroInteractiveCount are within caps. Adjust: When subjective overload persists after counts pass, escalate to AI.CONTEXT.BURDEN_SUBJECTIVE.

Passing signals

• Root homepage uses landing-header + landing-nav with 4–7 visible top-level destinations (Overview, How it works, Trust, Docs, etc.).
• No persistent fs-sidebar or generated handbook tree on desktop homepage view; full trees live under /docs, /handbook, or /reference.
• preMainFirstH1LinkCount ≤ 10 — skip links, theme toggles, and cookie banners excluded from the count.
• outsideMainHeaderNavLinkCount ≤ 7 — curated global nav, not an exhaustive product index.
• navChromeContainerCount ≤ 4 — header + one mobile offcanvas band, not stacked sidebars and duplicate nav rails.
• On home: firstViewportLinkCount ≤ 28 and heroInteractiveCount ≤ 3 (typically one btn btn-forge primary, one btn-cyan-outline secondary, optional low-emphasis third).
• Additional destinations use landing-hero-secondary-links / landing-hero-secondary-link text links below the button row.

Failing signals

• preMainFirstH1LinkCount > 10 — link walls, cross-ref asides, or chrome links appear above the primary in-main headline (pre_main_first_h1_link_count=N max=10, major; critical when count exceeds max + 2).
• outsideMainHeaderNavLinkCount > 7 — landing-nav or fs-primary-nav-global exposes too many top-level choices (outside_main_header_nav_links=N max=7).
• navChromeContainerCount > 4 — competing header, nav, aside, fs-sidebar, and offcanvas bands outside main (nav_chrome_container_count=N max=4).
• On home: firstViewportLinkCount > 28 — first viewport dominated by navigational anchors (critical).
• On home: heroInteractiveCount > 3 — four or more hero-fold .btn / button controls in landing-hero-actions__buttons (major; critical when count exceeds max + 1).
• Homepage screenshot reads as handbook reader despite hero copy — often co-fails DET.PAGE.MODE and DET.NAV.DEDUP.

Before example

After example

After (passing example)

Skip to content

ForgeSDLC

Governed human + agent delivery

Shape intent, delegate safely, and release with evidence—not ad hoc prompts.

Start quickstart See how it works

Full documentation · Trust model

Three outcomes teams need

Clear intent before agent work starts.

Evidence and remediation

Evidence: Crawl metrics from lib/dom-metrics.js — preMainFirstH1LinkCount, outsideMainHeaderNavLinkCount, navChromeContainerCount, firstViewportLinkCount (home only). Playwright probe contextBurdenReport.heroInteractiveCount from collectContextBurdenReport. Finding messages cite keys such as pre_main_first_h1_link_count=14 max=10, outside_main_header_nav_links=12 max=7, nav_chrome_container_count=6 max=4, first_viewport_link_count=30 max=28, hero_interactive_controls=5 max=3.

Remediate (in order):

1. Shell: Route / through landing_page, not product_page with persistent fs-sidebar. Move handbook trees to /docs / /handbook deep routes.
2. Header nav: Trim landing-nav / fs-primary-nav-global to 4–7 curated destinations; nest the rest under Docs or a single mega-menu on interior pages only.
3. Pre-main links: Remove fs-cross-refs, breadcrumb walls, and maintainer indexes above the hero h1; link dense reference from below the fold or dedicated pages.
4. Hero controls: Collapse to one btn-forge + one btn-cyan-outline; demote extras to landing-hero-secondary-link (align with DET.BUTTON.GROUP.MAX).
5. Chrome bands: Consolidate duplicate mobile/desktop nav trees; keep offcanvas for small viewports without also exposing full sidebar on homepage desktop.
6. Re-run analyze-website-ux.mjs on /; if counts pass but the viewport still feels noisy, review AI.CONTEXT.BURDEN_SUBJECTIVE.

Related rules

• DET.BUTTON.GROUP.MAX — horizontal hero button row cap (feeds hero interactive count).
• DET.CTA.HIERARCHY — one primary CTA class per viewport region.
• DET.NAV.DEDUP — duplicate destination labels across competing nav bands.
• DET.NAV.DEPTH — global primary nav nesting depth (.landing-nav, .fs-primary-nav-global).
• DET.PAGE.MODE — root / must use landing/product shell, not handbook reader mode.
• AI.CONTEXT.BURDEN_SUBJECTIVE — perceived overload when numeric caps pass.
• AI.CONTEXT.COGNITIVE_CLARITY — acronyms and technical depth before product explanation.