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

Purpose

Readers on doc and product hubs need a compact where am I trail separate from primary rails (Ksr sidebar) and page titles. Kitchen Sink layouts (showcase_page, handbook_page, product shells) contract Kbc — .ks-doc-breadcrumb with hash="Kbc" and data-ks-hash="Kbc" — inside header.site-header masthead bands.

This deterministic rule runs during the metrics phase. It sets requiresBreadcrumb=true when the page is not home and any doc-hub signal is present:

• Layout slug in layout-handbook, layout-chapter, layout-product, layout-showcase, layout-listing, layout-gallery, or layout-split ([data-ks-type="layout"] / data-ks-name).
• Visible doc sidebar: .forge-sidebar, #ks-sidebar-aside, .fs-sidebar, or aside[data-ks-hash="Ksr"] / aside[data-ks-name="doc-sidebar"].
• Visible showcase masthead: .site-header .site-header-content.

Exempt: layout-landing and layout-marketing (and home /, /index.html).

A page passes when a visible breadcrumb root matches .ks-doc-breadcrumb, [data-ks-hash="Kbc"], nav[aria-label="breadcrumb"], or Bootstrap .breadcrumb inside header/main with meaningful content (linked trail, two or more items, or separator-delimited path text). When breadcrumb is present, Kbc catalog markers must also appear on the root.

Plan: Map layout contracts to breadcrumb emission before shipping HTML. Do: Use render_breadcrumbs() or _showcase_header() defaults in components/layouts.py. Check: navBreadcrumbReport.requiresBreadcrumb && breadcrumbPresent && kbcMarkerPresent. Adjust: Add Kbc to masthead; do not rely on sidebar labels alone for orientation.

Passing signals

• nav.ks-doc-breadcrumb with hash="Kbc", data-ks-hash="Kbc", data-ks-type="chrome-region", data-ks-name="doc-breadcrumb" sits in .site-header-content above or beside the page title.
• Ordered trail via <ol class="breadcrumb"> with .breadcrumb-item links for upstream crumbs and aria-current="page" on the terminal crumb — matches render_breadcrumbs() in components/components.py.
• Default showcase header fallback emits Home to current page when breadcrumb_html is empty (_showcase_header in layouts.py).
• nav[aria-label="Breadcrumb"] with visible linked segments passes even without the Kbc class, but Kbc markers must still be present to avoid the secondary catalog finding.
• Home (/, /index.html) and layout-landing / layout-marketing pages correctly skip the requirement (requiresBreadcrumb=false).

Failing signals

• missing_breadcrumb: Doc hub signals fire (layout:layout-handbook, doc-sidebar, or showcase-header) but no visible .ks-doc-breadcrumb, nav[aria-label*="breadcrumb"], or .breadcrumb with meaningful content — readers see only sidebar nav and an h1 title.
• Empty or decorative strip: breadcrumb root exists but has no links, fewer than two meaningful words, and no separators (/, ›, →).
• Hidden or zero-size chrome: breadcrumb node present in DOM but display:none, visibility:hidden, or bounding box below visibility thresholds.
• kbc_marker_missing: Visible breadcrumb uses generic nav[aria-label="breadcrumb"] or .breadcrumb without hash="Kbc" / data-ks-hash="Kbc" on .ks-doc-breadcrumb — orientation works but visual catalog contract is unmet.
• Landing/marketing exemption misapplied: deep handbook page tagged layout-marketing solely to skip breadcrumb while still shipping Ksr sidebar chrome.

Before example

After example

Evidence and remediation

1. Confirm hub signals — inspect navBreadcrumbReport.docHubSignals (layout:…, doc-sidebar, showcase-header, or landing-exempt). Home and pure marketing shells should not require breadcrumb.
2. Emit Kbc in layout Python — pass breadcrumb_html into showcase_page / handbook_page, or call render_breadcrumbs([("index.html", "Home"), (None, page_title)]) from components/components.py.
3. Preserve catalog markers — root must include hash="Kbc" and data-ks-hash="Kbc" per docs/design/catalog/chrome/Kbc-doc-breadcrumb.md and chrome_region_attrs("doc-breadcrumb").
4. Keep content meaningful — at least one upstream link or separator-delimited path; terminal crumb uses aria-current="page"; decorative separators use aria-hidden="true" when not in link text.
5. Rebuild and re-audit — run python3 generator/build-showcase.py for KS surfaces, then node tools/website-ux-auditor/analyze-website-ux.mjs or auditor-tests/invoke-det-ruleset-harness.sh --only-rule DET.NAV.BREADCRUMB.
6. Harness fixtures — defect/pass pairs live under auditor-tests/ via generator/build_rule_defect_fixtures.py; compare HTML against the before/after blocks above.

Finding text (when failing): Doc or product hub page is missing visible breadcrumb orientation chrome (Kbc / .ks-doc-breadcrumb) or Visible doc breadcrumb chrome lacks Kbc catalog markers — severity warn, area informationArchitecture / visual-catalog.

Related rules

• DET.LANDMARKS.REQUIRED — breadcrumb nav complements sidebar nav landmarks; both sit outside main.
• DET.CHROME.BOUNDARY — Kbc stays visually lighter than Ksr rails; orientation chrome must not replace primary wayfinding.
• DET.APP.PERSISTENT_CHROME — breadcrumb belongs in stable masthead chrome across in-app routes.
• DET.NAV.DEPTH — deep IA paths need breadcrumb when sidebar depth alone is insufficient on condensed viewports.
• DET.NAV.DEDUP — do not duplicate the full sidebar tree inside the breadcrumb strip.
• DET.HASH.MARKERS — Kbc roots require paired hash / data-ks-hash markers on emitted HTML.
• AI.APP.WORKFLOW_CONTINUITY — judgment layer for breadcrumb labels that read as generic "Workspace" on every route.