JavaScript behavior discoverability

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

Purpose

Kitchen Sink ships interaction scripts under js/ (family Ksj: nav/offcanvas, theme picker, diagram modals, chart mounts, presentation fullscreen, roadmap edits, home tile expansion). Many behaviors are progressive enhancements on markup from components/layouts.py and transforms—not obvious from static HTML alone.

Deterministic gates (DET.JS.PROGRESSIVE, DET.JS.NO_CONSOLE_ERROR, DET.NAV.FOCUS_ORDER, DET.MOTION.PREFERS_REDUCED) prove baseline degradation, console hygiene, focus order, and motion prefs. This AI rule judges discoverability: can a visitor or operator infer what will happen before they click, tap, or hover—and find a keyboard/touch path when the script adds behavior?

Plan: Walk golden paths on showcase and handbook shells; list controls whose behavior is script-only (expand, modal, offcanvas, theme, chart fetch, fullscreen). Do: Add visible affordances (forge-diagram-trigger, labeled buttons, forge-support helper lines) and document non-obvious shortcuts in page copy or contracts. Check: Each non-default interaction has at least one of: visible label/hint, persistent helper copy, or documented operator note; hover-only cues are supplemented for keyboard/touch. Adjust: When the same gap repeats (e.g. every expandable diagram missing forge-diagram-trigger), propose a DET.* candidate or tighten Ksj forbidden patterns.

Passing signals

• Expandable diagrams use forge-diagram-trigger / ks-diagram-trigger so CSS surfaces "Click to expand" (and catalog keys like data-diagram-key tie to openDiagramWithDetail).
• Mobile handbook chrome exposes a fixed data-bs-toggle="offcanvas" control with aria-label="Open navigation" and aria-controls="docNavOffcanvas" (Kco).
• Theme switching uses forge-theme-trigger with aria-label, title, and visible copy—not icon-only mystery meat.
• Script-driven nav (docs-nav.js, fs-nav-dropdown.js) keeps aria-expanded in sync with open panels.
• Chart mounts (data-ks-chart, ks-chart-mount) show loading/empty copy from forge-data-charts.js before data arrives.
• Non-obvious operator flows (presentation fullscreen exit, roadmap edit handles) have visible controls or in-page "How to use" copy.
• Keyboard users reach the same outcomes as hover-reveal hints (DET.NAV.FOCUS_ORDER when focus is managed).

Failing signals

• Clickable diagram or tile with no forge-diagram-trigger, no helper line, and no aria-label—behavior exists only after trial-and-error.
• Hover-only affordance (::after "Click to expand") with no focus-visible equivalent or persistent text for touch users.
• Mobile nav hidden behind a missing, unlabeled, or desktop-only control while main assumes sidebar IA.
• Global shortcuts or double-click edits (nested-roadmap.js) with no documented affordance on the page or in the contract.
• onclick handlers on inert-looking blocks (figure, div) with no role, label, or visual button metaphor.
• Theme, lens, or tab controls that change layout with no aria-expanded / active state and no helper copy.
• Chart or modal surfaces that open on load or timer with no dismiss hint (AI.MOTION.INTENTIONALITY overlap).

Before example

Before (failing example)

Architecture overview

Use the diagram to explain the flow.

Handbook content—no nav button on narrow viewports.

After example

After (passing example)

Architecture overview

Select the diagram to open a larger view with step-by-step notes.

Menu

Handbook

Theme

Evidence and remediation

Capture: For each scripted surface, record URL, viewport width, and interaction type (click, hover, keyboard). Screenshot default and hover/focus states for forge-diagram-trigger, offcanvas open, and theme dropdown. Note whether helper copy appears without hover. Log console for golden paths (DET.JS.NO_CONSOLE_ERROR).

Remediate (in order):

1. Classify interactions: obvious (native <button>, <a>) vs non-obvious (diagram expand, tile tilt, roadmap edit, fullscreen).
2. For non-obvious controls: add forge-diagram-trigger or a visible button/link; pair with forge-support one-liner above the control.
3. Fix naming: aria-label, title, aria-controls, aria-expanded on triggers; align with Kco / Ksj contracts.
4. Replace hover-only discovery with persistent text or focus-visible hints; verify keyboard path (DET.NAV.FOCUS_ORDER).
5. Document operator shortcuts in page prose or catalog contract when behavior cannot be inlined.
6. Re-run progressive check: core content readable with JS disabled (DET.JS.PROGRESSIVE).
7. If the same missing hint repeats across pages, propose a deterministic companion (e.g. require forge-diagram-trigger when onclick opens diagram modal).

Related rules

• DET.JS.PROGRESSIVE — critical content visible without script; enhancements gated.
• DET.JS.NO_CONSOLE_ERROR — scripted golden paths do not throw uncaught errors.
• DET.MOTION.PREFERS_REDUCED — motion scripts honor reduction prefs.
• DET.NAV.FOCUS_ORDER — focus order and traps when scripts manage focus (modals, offcanvas).
• AI.MOTION.INTENTIONALITY — motion should guide attention, not replace discoverability cues.