# 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.