sync: auto-sync from GURU-5070 at 2026-06-03 20:07:24

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-03 20:07:24

.claude/skills/human-flow/references/improvement-patterns.md

@@ -0,0 +1,103 @@
+# Common Human-Flow Improvement Patterns
+
+Quick, copy-paste-friendly patterns that directly address the most frequent friction found by this scanner.
+
+## 1. Always-Visible Row Actions (instead of hover-revealed)
+
+**Before (friction)**:
+```tsx
+<span className="dt__rowactions">  {/* opacity 0.5 until hover */}
+  <Button size="sm" ...>Control</Button>
+  <Button size="sm" variant="danger">End</Button>
+</span>
+```
+
+**Better for humans**:
+```tsx
+// Option A: Dedicated actions column, always visible, slightly dimmed but scannable
+<td className="dt__actions">
+  <div className="dt__rowactions" style={{ opacity: 0.85 }}>
+    <Button size="sm" variant="primary" ...>Control</Button>
+    <Button size="sm" variant="danger" ...>End</Button>
+  </div>
+</td>
+
+// Option B: Primary action is the row itself + one very obvious secondary
+<tr onClick={openDetail} ...>
+  ...
+  <td>
+    <Button onClick={e => { e.stopPropagation(); takeControl(); }}>
+      Control
+    </Button>
+  </td>
+</tr>
+```
+
+Add good focus styles so keyboard users see the group light up.
+
+## 2. Generous Hit Area Around Small Visual Controls
+
+```tsx
+// Instead of 15px checkbox as the only target
+<label className="dt__checkwrap">  {/* extra 6px+ invisible padding all around */}
+  <input type="checkbox" className="dt__check" ... />
+</label>
+```
+
+The wrapper is the real hit target. The visual control can stay small and crisp.
+
+## 3. Primary Row Action + Clear Secondary
+
+Make the thing the human does most often the easiest to hit.
+
+- Row click (or big left area) = primary (View / Open detail / Control)
+- Always-visible, slightly larger button on the right = secondary (End, more actions)
+- Tiny icons only for truly rare actions inside a "..." menu
+
+## 4. Strong, Consistent Focus + Hover
+
+In your global or table CSS:
+
+```css
+.dt tbody tr:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 2px var(--accent);
+  background: var(--panel-2);
+}
+
+.dt tbody tr:hover {
+  background: var(--panel-2);
+}
+
+/* Make sure buttons inside also have excellent focus */
+.btn:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent-ring);
+}
+```
+
+## 5. Icon Button with Good Labeling
+
+```tsx
+<Button
+  variant="ghost"
+  size="sm"
+  aria-label="End session for this machine"
+  title="End session"
+  onClick={...}
+>
+  <StopIcon width={16} height={16} />
+</Button>
+```
+
+Prefer visible text for frequent actions. Icons + text is often the sweet spot for speed + scannability.
+
+## 6. Make "Control" or Primary Action the Dominant Target
+
+In a sessions/machines list, the #1 thing an operator wants 80% of the time should be the biggest, highest-contrast, easiest-to-hit target on the row — not the smallest icon.
+
+This single change often has the biggest impact on perceived "this tool feels good to use."
+
+---
+
+Apply these patterns, then re-run `human-flow scan` (or ask the agent to re-apply the heuristics) to verify the friction has been reduced.