claudetools/.claude/skills/human-flow/references/mouse-keyboard-heuristics.md

Human-Flow Heuristics: Mouse + Keyboard Intuition

This document defines the core detection rules and "why it hurts humans" reasoning for the human-flow scanner.

Guiding Principle: A human with a mouse and keyboard expects:

• Obvious targets that are big enough to hit reliably (even when in a hurry or on a trackpad).
• Actions that are visible without having to hunt with the pointer.
• Every mouse action to have a reasonable, discoverable keyboard equivalent.
• Immediate, unambiguous feedback on every interaction.
• Workflows that don't require pixel-perfect precision or constant context switching.
• The ability to recover gracefully from near-misses.

Anything that violates these creates "friction" — small delays, errors, or cognitive load that add up in real use.

---

1. Target Size & Precision (Fitts's Law Violations)

Anti-patterns to detect:

• Icon-only buttons or actions with visual size < 32px (ideally 44px minimum for reliable mouse).
• "sm" sized buttons used for primary or frequent actions in lists/tables.
• Clickable areas defined only by text or thin icons without generous padding.
• Dense table rows or toolbars where interactive elements are crammed together (risk of mis-clicks).
• Custom controls (fake checkboxes, row clicks) that have smaller effective hit areas than native ones.

Why unintuitive for humans:

• Small targets require slowing down and careful aiming. Under time pressure or with imperfect motor control (fatigue, trackpad, accessibility needs), this leads to errors and frustration.
• Frequent actions (view/control a session, end session, delete) should be the easiest to hit, not the hardest.

Better human workflow:

• Use at least min-height: 32px; min-width: 32px; (preferably 44px) for any actionable icon or compact button.
• Add invisible padding or use the dt__checkwrap pattern (generous hit area around small visual control).
• For row-level actions, make the entire "action zone" larger or always visible with good visual weight instead of tiny icons.
• Provide a clear "primary" large target per row/card and de-emphasize (but don't hide) secondary ones.

Detection hints:

• Look for size="sm", btn--sm, heights like 28px/24px/20px on interactive elements.
• CSS rules with width: 14px, height: 14px on buttons/icons inside lists.
• padding: 0 or very tight padding on actionable elements in data views.
• Lack of min-height / min-width or padding on icon buttons.

---

2. Hover-Only / Low-Visibility Actions (Discoverability Failures)

Anti-patterns:

• Row actions, kebab menus, or secondary buttons that are opacity: 0.3–0.6 at rest and only reach full opacity on :hover or :focus-within.
• Controls that only appear on hover (classic "hover-revealed actions").
• Important status or actions communicated only via subtle hover tooltips or color changes without text.
• "More actions" that require mousing to the edge of a row.

Why unintuitive for humans:

• A person scanning a list with their eyes + mouse doesn't want to "paint" every row with the pointer just to see what they can do.
• Keyboard users may never discover the actions (even if focus-within helps a bit).
• It creates a "hunting" workflow instead of a "glancing + acting" workflow.
• On touch or with imprecise pointing devices, the actions flicker or stay hidden.

Better human workflow:

• Make secondary actions dimmed but always legible (e.g. 70-85% opacity) so they are scannable at a glance.
• Or move them into a consistent, always-visible "Actions" column or a "..." menu that is obvious.
• Use progressive disclosure only for rare actions, not frequent ones.
• For keyboard: ensure focus-within or explicit focus styles surface the group, and document keyboard activation.

Detection hints:

• .rowactions, .actions with opacity: 0.5 (or lower) + transition on hover only.
• Comments like "hover-revealed", "shown on hover".
• CSS that uses :hover to control visibility/opacity of interactive elements in lists/tables.
• Absence of always-visible text labels next to icon actions.

---

3. Missing or Weak Keyboard Parity & Activation

Anti-patterns:

• Clickable rows, cards, or custom elements that only have onClick with no tabIndex, onKeyDown (Enter/Space), or role.
• Icon buttons or custom controls without aria-label / title that are reachable by Tab.
• Row selection or activation that works with mouse but has no keyboard story (or only works if you tab into every cell).
• Modals, drawers, or popovers opened by mouse that don't trap focus or provide clear Esc/close keyboard path.
• Drag-and-drop or multi-select that has no keyboard equivalent (arrow keys, Space to select, etc.).

Why unintuitive for humans:

• A keyboard user (or someone who prefers keyboard for speed) hits a wall — they can see the thing but can't reach or activate it efficiently.
• It forces context switching between input methods or makes power users slower.
• In data tables (very common in operator consoles), the expectation is "I can arrow or Tab through, Enter to act."

Better human workflow:

• Every mouse-activated element that is not a native control must be keyboard-focusable and activatable with standard keys (Enter for primary action, Space for toggle/selection).
• Provide visible focus states that are strong (not just the browser default if it's invisible on dark themes).
• For tables: support row activation via keyboard in addition to (or instead of) cell-by-cell navigation.
• Always offer a non-mouse way to do the primary task.

Detection hints:

• onClick handlers on <div>, <tr>, or custom components without accompanying tabIndex={0}, onKeyDown, or role="button".
• Custom checkboxes/radios without proper keyboard handling.
• Absence of aria-label on icon-only <button>s.
• cursor: pointer on non-native interactive elements without keyboard attributes.
• Focus styles that are commented out or only use outline: none without replacement.

---

4. Poor or Inconsistent Feedback & State Visibility

Anti-patterns:

• Actions that do something significant on click but give no immediate visual response (no loading, no highlight, no optimistic update).
• Disabled states that look almost the same as enabled (low contrast, no title explaining why).
• Hover/focus states that are too subtle or inconsistent across the UI.
• Selection (in tables, lists) that is only visible via checkbox and not reinforced on the row itself for mouse users.
• Long-running operations with no progress indication that is mouse/keyboard friendly (e.g. no way to cancel).

Why unintuitive for humans:

• Uncertainty: "Did my click register? Is it working? Why is this grayed out?"
• Forces the user to guess or wait and then retry, breaking flow.
• In a fast-paced operator console, lack of feedback creates anxiety and errors.

Better human workflow:

• Every click or keypress on an action should produce immediate visual change (active state, spinner in place, row highlight, toast, etc.).
• Disabled controls should have clear title or adjacent text explaining the reason.
• Selection models should be obvious at a glance (strong row highlight + checkbox).
• Provide "Cancel" or "Undo" affordances that are easy to hit with mouse or keyboard.

Detection hints:

• Buttons without loading state handling or visual active/pressed styles.
• Disabled buttons with no title or aria-disabled explanation.
• Lack of :active, .active, or transition feedback in button/link CSS.
• Row selection that only toggles a small checkbox without broader visual treatment.
• No visible "pending" or "in-flight" state on frequent actions.

---

5. Workflow Efficiency & Precision Requirements

Anti-patterns:

• Common tasks require many precise clicks (open menu → find item → click small target).
• Destructive actions (End, Delete, Remove) are as easy or easier to hit than safe actions, with weak or no confirmation that works well with mouse/keyboard.
• No keyboard shortcuts for high-frequency operations.
• Dense UIs where the mouse has to travel long distances between related controls (poor spatial grouping).
• "Click anywhere on row to open" combined with "click specific small icon for other action" — easy to mis-trigger.

Why unintuitive for humans:

• Every extra click or extra millimeter of precision adds time and error rate.
• In operator tools, technicians do the same actions hundreds of times a day — small frictions compound into real pain.
• Accidental destructive actions destroy trust.

Better human workflow:

• Make the most common action the largest, most obvious target (e.g. big "Control" or "View" on the row).
• Use consistent "primary action on row click + secondary in always-visible or easy-to-reach zone".
• Add title + disabled state + confirmation dialog for dangerous actions; make the confirmation target large and clear.
• Surface 1-2 keyboard shortcuts for the top actions (and show them in UI or tooltips).
• Group related controls spatially so the mouse doesn't have to hunt.

Detection hints:

• High-frequency actions (Control/View/Join) implemented as small size="sm" icon buttons.
• Destructive buttons (danger variant) placed right next to primary actions with no extra guard.
• Lack of onRowClick primary action or equivalent "big target" pattern.
• No evidence of keyboard shortcut wiring (useEffect for key listeners, etc.).
• Very narrow columns or tight gaps in action areas.

---

6. Affordance & Visual Expectation Mismatches

Anti-patterns:

• Text or areas that look like plain content but are clickable (no underline, no color change, no hover lift).
• Things that look like buttons (borders, backgrounds) but are not interactive.
• Custom "fake" UI controls that don't follow platform conventions for mouse (double-click expectations, right-click, etc.).
• Links that don't look like links on hover/focus.

Why unintuitive for humans:

• Breaks the mental model: users have to experiment ("is this clickable?") instead of acting on learned visual language.
• Wastes time and creates uncertainty.

Better human workflow:

• Interactive elements should have clear visual language (color, underline, cursor, hover scale/lift, focus ring).
• Non-interactive content should not mimic interactive styling.
• When using row-click, make the row itself look "selectable" or "activatable" on hover/focus (background change, subtle border).

Detection hints:

• cursor: pointer on elements that have no other interactive styling (no color change, no background on hover).
• Large clickable regions with no visual treatment on hover/focus.
• Text that is the only indicator of clickability with no other affordance.
• Absence of hover styles on things that have onClick.

---

Reporting Guidance

When reporting a finding, always answer three questions for a human reader:

1. What the human experiences (the friction moment with mouse or keyboard).
2. Why it is costly (time, errors, cognitive load, fatigue).
3. Concrete improvement that makes the anticipated next action easier and more obvious with mouse and keyboard.

Prioritize findings that affect the most frequent user workflows in the product (in operator consoles: viewing/controlling sessions, managing machines, acting on lists).

---

Related Anti-Patterns from Parent Skills

This skill deliberately overlaps with and specializes rules from impeccable (no identical card grids, no hero metrics, strong focus on cognitive load and emotional journey) and frontend-design (click targets 44px, hover states, focus states, disabled states).

human-flow adds the "human motor + expectation" layer on top: how these things feel when you're actually using the interface repeatedly with real hands and a real brain under real time pressure.