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

Purpose

Visitors should recognize one primary job for the page within the first screen: public marketing (landing_page), handbook reading (handbook_page), product guide (product_page), listing hub, showcase presentation, or app shell. When a route mixes incompatible shells—layout-landing hero plus a persistent forge-sidebar doc tree, or marketing copy inside a handbook reader—the page fails information-architecture review before copy edits can help.

Kitchen Sink layouts emit mode through layout_shell_attrs on the layout root (typically <body>): data-ks-type="layout", data-ks-name="layout-*", plus optional <meta name="forge-page-mode" content="…">. The auditor maps layout slugs to canonical modes (layout-landing → marketing, layout-handbook → handbook, layout-listing → listing, layout-product → product, layout-showcase / layout-gallery / layout-split → presentation) and infers competing modes from visible chrome: doc sidebars outside main, showcase header bands, app-shell regions, handbook phrase density, and sidebar link counts (≥ 6 links) on marketing routes.

Plan: Assign each URL to a mode from docs/design/forge-enterprise-ai-website-standard.md (modes 1–4). Do: Use landing_page on / with curated landing-header / landing-nav only; route depth to /docs or handbook layouts. Check: pageModeReport.violations is empty and modes has a single primary token. Adjust: Remove handbook sidebars and duplicate nav trees from marketing shells before rewriting hero text.

Passing signals

Root / uses landing_page: layout root carries data-ks-type="layout" data-ks-name="layout-landing" (hash Ldg) with landing-header, landing-hero fs-landing-hero-band, and main.fs-landing-main—no visible forge-sidebar, #ks-sidebar-aside, or fs-sidebar outside main.
Handbook routes use handbook_page / chapter_page: data-ks-name="layout-handbook" or layout-chapter; Ksr doc sidebar is expected on handbook-native layouts and does not register as a competing handbook signal.
Listing and product routes use layout-listing or layout-product with matching interior shells (fs-listing-layout, product chrome) and no app-shell regions on marketing paths.
Optional metadata aligns with layout: <meta name="forge-page-mode" content="marketing"> on landing shells; content="handbook" on docs pages.
pageModeReport.modes is a single mode (for example ["marketing"] on home) or only modes compatible with the declared layout slug.
No competing-modes violation for marketing↔handbook, marketing↔app, marketing↔dashboard, or listing↔app.
Home path (/, /index.html) does not trigger home-handbook-shell (critical when handbook chrome appears above the fold).

Failing signals

competing-modes — detected modes include both marketing and handbook (for example layout-landing on the layout root plus six or more sidebar links in .forge-sidebar outside main).
home-handbook-shell — / exposes handbook/doc chrome while expected mode is marketing (often co-fails DET.CONTEXT.BURDEN and DET.NAV.DEDUP).
undeclared-mode — KS layout marker present, substantial main copy (≥ 80 words), but no data-ks-name layout slug and no forge-page-mode meta (warn).
Visible .site-header .site-header-content showcase band on a non-presentation layout adds presentation as a competing mode.
[data-shell-region], .museum-studio, or data-ks-name="museum-studio" on a marketing page adds app as a competing mode.
Handbook phrase density above threshold on a marketing/home route forces an extra handbook mode via handbookChromeAboveFold.
Evidence shapes: competing_modes=marketing↔handbook detected=marketing+handbook layout=layout-landing; home_modes=marketing+handbook expected=marketing.

Before example

Before (failing example)

Forge SDLC — Governed delivery

ForgeSDLC

Methodology

Governed human + agent delivery

Hero reads as marketing while sidebar reads as handbook.

Quickstart Read the handbook

Failing KS markup: public landing declares layout-landing but still mounts a handbook doc rail beside the hero—marketing and handbook modes compete above the fold.

After example

After (passing example)

Forge SDLC — Governed delivery

Methodology

Governed human + agent delivery

Single marketing mode: outcome-first hero without handbook chrome.

Quickstart Read the handbook

Outcome

Clear intent and reviewable execution.

Passing KS markup: same landing story with landing_page anatomy only—layout marker, curated header nav, hero band, and body shell; handbook tree lives under /docs routes, not on /.

Evidence and remediation

Evidence	Meaning	Remediation
`competing_modes=marketing↔handbook`	Landing layout plus doc sidebar or handbook chrome	Remove `forge-sidebar` / `fs-sidebar` from `/`; use `landing_page` only
`home_modes=…+handbook expected=marketing`	Homepage reads as docs reader	Switch root generator to `landing_page`; move trees under `/docs`
`undeclared_mode`	Layout slug or meta missing on KS-marked page	Emit `layout_shell_attrs("landing_page")` or `<meta name="forge-page-mode" content="marketing">`
`layout=layout-handbook` on `/`	Wrong layout function for URL	Fix `build-site.py` / content-map routing before copy edits

Kitchen Sink: Call landing_page for public roots (components/layouts.py); use handbook_page / chapter_page only on handbook URLs. Confirm layout_shell_attrs resolves to data-ks-name="layout-landing" (registry slug layout-landing, hash Ldg). Rebuild showcase and consumer sites after layout changes.

Consumer sites: Map URLs to mode 1–4 in docs/design/forge-enterprise-ai-website-standard.md. Re-audit with analyze-website-ux.mjs; inspect metrics.pageModeReport in crawl JSON.

Harness: generator/build_rule_defect_fixtures.py and auditor-tests/invoke-det-ruleset-harness.sh --only-rule DET.PAGE.MODE. Implementation: tools/website-ux-auditor/design-rules/deterministic/generated/det-page-mode.check.js.

Related rules

DET.CONTEXT.BURDEN — quantitative first-screen caps; handbook chrome on / often fails both rules.
DET.NAV.DEDUP — duplicate destinations across masthead and sidebar when modes are mixed.
DET.NAV.DEPTH — global nav depth; marketing shells should stay shallow.
DET.LANDMARKS.REQUIRED — main, nav, and header landmarks differ by layout mode.
DET.PAGE.LANG — html lang on the same document shells.
AI.NARRATIVE.COHERENCE — story arc after mode is unambiguous (hero → outcomes → trust).
DET.CONTEXT.BURDEN — Quantitative caps on header navigation, pre-main link clusters, nav chrome bands, and hero-fold interactive controls keep public homepages story-led instead of docs-shaped.
DET.NAV.DEDUP — Same navigational destination must not repeat across conflicting chrome bands (primary, sidebar, offcanvas) without breadcrumb hierarchy or intentional IA split.
DET.NAV.DEPTH — Global primary nav outside main stays at top level plus one flyout tier (list depth ≤ 2); deeper trees belong in Ksr sidebar, offcanvas, or an explicit mega-menu pattern (≤ 4 tiers).
DET.LANDMARKS.REQUIRED — Each page exposes exactly one main landmark, a navigation landmark when global wayfinding exists outside main, and semantic header/footer landmarks when site chrome is present—each unique at document…
DET.PAGE.LANG — The root html element declares a BCP 47 language tag so assistive tech, hyphenation, and translation tools can infer the page's primary language.
AI.NARRATIVE.COHERENCE — The page tells one ordered story—problem, outcome, mechanism, next step—with section sequencing that does not contradict earlier claims.