200 lines
12 KiB
Markdown
200 lines
12 KiB
Markdown
# 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. |