azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-03 20:07:24
This commit is contained in:
Mike Swanson
2026-06-03 20:07:28 -07:00
parent 10e8d7b6bb
commit 37ccc5f35c
12 changed files with 1241 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.claude/skills/human-flow/README.md Normal file
View File

@@ -0,0 +1,52 @@
# human-flow
A focused UI/UX scanner for **human mouse + keyboard workflow intuition**, with a dedicated "Fancy as Fuck" mode for beauty and elegance.
It expands the excellent foundations in `frontend-design` (visual + interaction correctness) and `impeccable` (critique, heuristics, anti-slop, cognitive load) with a narrow lens:
> What feels clunky, hidden, imprecise, or frustrating when a real person is sitting there with a mouse in one hand and a keyboard in the other, trying to get real work done?
The fancy mode adds an important principle: **"In the course of being as useful as possible, do it with panache."** "Useful decoration" (elegance that improves mental models, reduces anxiety, provides better feedback, or creates positive emotional connection) is explicitly welcomed, while gratuitous prettiness is discouraged. The mode carefully calibrates expectations based on whether the surface is a high-density internal tool or one that can benefit from more expressive delight.
## Quick Start (as the agent)
```bash
# Fast static scan (friction / workflow)
node .claude/skills/human-flow/scripts/scan.mjs --path dashboard/src
# "Fancy as Fuck" beauty & elegance pass (useful decoration welcome)
node .claude/skills/human-flow/scripts/scan.mjs --path dashboard/src --fancy
# or: npm run fancy -- --path dashboard/src
# Or let the agent drive it naturally:
# "human-flow scan the sessions feature"
# "human-flow fancy the main interactive surfaces — look for useful decoration and panache where it enhances the experience"
# "Run a human-flow audit on the main data tables and action patterns"
```
The script emits structured findings (stronger in friction mode; signals + prompts in fancy mode). The agent then augments them with full file reads, task flow understanding, and the richer heuristics in `references/`. The fancy pass is intentionally more qualitative.
## Core Files
- `SKILL.md` — the contract and invocation rules
- `references/mouse-keyboard-heuristics.md` — the detailed "why this hurts a human" rules
- `references/human-flow-checklist.md` — rapid mental model / quick checklist
- `references/improvement-patterns.md` — concrete before/after patterns that improve real workflows
- `references/report-template.md` — consistent output format
- `scripts/scan.mjs` — lightweight static detector you can run from the terminal
## Philosophy
- Prioritize **frequent tasks** done by humans under real conditions (time pressure, imperfect pointing, mix of mouse and keyboard).
- Small targets, hidden-on-hover actions, and mouse-only gestures are the most common sources of daily friction in data-heavy tools.
- Good solutions usually involve making the right thing bigger, more visible, and reachable by both input methods — not just "adding more aria".
This skill is deliberately opinionated toward **making the anticipated next action obvious and low-effort** for a human operator.
## Relationship to Sibling Skills
- Use `frontend-design` for visual/layout/contrast validation.
- Use `impeccable critique|audit|polish` for broader UX, emotional journey, and anti-slop.
- Use `human-flow` when you specifically want the "does this feel good in my hands with a mouse and keyboard?" pass.
They compose beautifully. Run them in sequence on the same target when doing serious interface work.

152
.claude/skills/human-flow/SKILL.md Normal file
View File

@@ -0,0 +1,152 @@
---
name: human-flow
description: >
A UI/UX scanner that specializes in detecting interaction patterns unintuitive or inefficient for humans using a mouse and keyboard.
Expands on frontend-design and impeccable by focusing on real human workflow friction: motor control (Fitts's Law, target sizing, precision),
discoverability (affordances, hover vs always-visible), keyboard parity (full navigation and activation without mouse),
feedback loops (immediate state changes, error recovery), task efficiency (click/keystroke count, context switches),
and forgiving interaction models. It produces structured reports with code locations, "why this feels bad for a human" explanations,
and specific, actionable recommendations to make mouse+keyboard workflows smoother, faster, and more intuitive.
Use when reviewing or building any interactive UI, especially data-heavy tools, dashboards, lists, forms, and complex workflows.
user-invocable: true
argument-hint: "[scan|audit|report] [target path or component]"
---
# human-flow — Human Mouse + Keyboard Workflow Scanner
This skill is a specialized scanner for **human intuition and ergonomics** in pointer + keyboard interfaces. It goes beyond visual polish, code quality, and general UX heuristics (covered by `frontend-design` and `impeccable`) to focus on what actually feels *clunky, hidden, or frustrating* when a real person is driving with a mouse and keyboard.
**Core Philosophy**
- Humans have limited precision, attention, and patience.
- Mouse users hate tiny targets, hidden controls, and precision clicking.
- Keyboard users hate missing focus, no activation keys, and mouse-only gestures.
- Good workflow design makes the *anticipated next action* obvious and low-effort with either input method.
- The best interfaces feel "just right" — large enough targets, immediate feedback, discoverable without hunting, and consistent models.
It is **mandatory** to consider human-flow when any mouse or keyboard interaction is involved.
## When to Invoke
- Before or after implementing interactive features (buttons, tables, lists, modals, forms, drag, selection).
- When reviewing a dashboard, admin tool, or data-heavy UI (e.g. session lists, machine management).
- To audit an existing interface for workflow friction.
- As a complement to `impeccable critique` / `audit` and `frontend-design` validation.
Run via natural language ("human-flow scan the sessions table", "run human-flow audit on the dashboard components") or explicitly.
## Commands
| Command | Description |
|---------------------|-------------|
| `scan [target]` | Quick static + heuristic scan of files or directories for mouse/keyboard friction. Produces a prioritized report. |
| `audit [target]` | Deeper pass: combines code analysis, component review, and workflow walkthroughs. Scores intuitiveness and suggests specific refactors. |
| `fancy [target]` | **"Fancy as fuck" mode** — a second, beauty- and elegance-focused pass. Evaluates opportunities for tasteful delight (transitions, micro-interactions, hover states, view transitions, loading experiences, etc.), determines appropriateness, and suggests refinements/polish. |
| `report [target]` | Generate a clean, user-facing markdown report suitable for sharing with designers/devs. |
If no command, defaults to `scan` on the provided target (or current frontend dir).
You can combine: e.g. run `scan` first for friction, then `fancy` for delight opportunities.
## Usage in Practice (for the Agent)
1. Resolve the target (file, component, page, or directory of .tsx/.jsx/.css/.ts).
2. Load the heuristics from `references/`.
3. Use code tools (read_file, grep, list_dir) + the scanner script if helpful to find candidate patterns.
4. For each finding:
- Cite exact file:line or component.
- Explain *why it is unintuitive for a human with mouse and/or keyboard*.
- Give a concrete "better for humans" recommendation (with example diff or pattern when useful).
5. Prioritize by impact on common workflows (high-frequency actions first).
6. End with an overall "Human Workflow Score" (0-10) and top 3-5 recommended changes.
Always separate **mouse friction** and **keyboard friction** in reports, then **combined workflow** issues.
## Heuristics (Core Categories)
The full detailed list with examples and detection guidance lives in `references/mouse-keyboard-heuristics.md`.
High-level categories the scanner always checks:
- **Target Size & Motor Precision** (Fitts's Law)
- **Discoverability & Affordance** (does it look clickable/tappable? do secondary actions hide?)
- **Hover vs Always-Visible** (actions that require mouse hover to even see options)
- **Keyboard Parity & Activation** (can you do everything the mouse can, with reasonable keys?)
- **Focus & Navigation Flow** (tab order, focus trapping, visible focus, escape hatches)
- **Feedback & State Transitions** (does the UI react immediately and clearly to every mouse/keyboard action?)
- **Selection & Multi-Action Models** (row click vs checkbox, drag vs buttons — are they consistent and forgiving?)
- **Workflow Efficiency** (number of steps, precision required, dead space, context loss for common tasks)
- **Error Prevention & Recovery** (destructive actions, undo, clear "I didn't mean that" paths)
- **Density vs Clarity** (too much crammed into small areas forcing careful mousing)
The scanner is **opinionated toward making the happy path for a human operator faster and less error-prone**, even if it means slightly more visual weight or always-visible controls.
## Scripts & Tooling
- `scripts/scan.mjs` — runnable Node scanner.
- `node scripts/scan.mjs --path <target>` → friction mode (default)
- `node scripts/scan.mjs --path <target> --fancy` → fancy mode (collects signals + prompts for the qualitative beauty pass)
- The agent is expected to supplement with semantic understanding (reading full components, understanding the user task flow in the app) and the rich references. The fancy pass is intentionally more qualitative than the friction scanner.
## Integration with Other Skills
- Run **after** `frontend-design` visual validation and **alongside** `impeccable critique/audit`.
- Use `stop-slop` thinking when generating any example fixes or new component code.
- Can feed findings into `impeccable polish` or `harden` passes.
## Output Format (Preferred)
```markdown
## Human-Flow Scan: <target>
**Overall Human Workflow Score:** 6.5/10 (Mouse: 7/10, Keyboard: 6/10)
### High Friction (P0)
- **File:** ...:123 — Hover-only row actions
Why unintuitive: Secondary actions (End, Control) are at 0.5 opacity until hover. A keyboard user or rushed mouse user scanning the list will miss or struggle to target them.
Human impact: Common task (ending a session) requires extra precision and discovery step.
Recommendation: ...
```
See `references/report-template.md` for the full structure.
## "Fancy as Fuck" Mode (`fancy`)
This is a deliberate second (or standalone) pass focused on **beauty, refinement, and elegant interaction**.
### Philosophy
- Not every interface needs (or should have) fancy elements. The first question is always: *"Does this beauty make the experience more useful?"*
- **Core principle**: Don't be pretty just to be pretty. In the course of being as useful as possible, do it with panache.
- "Useful decoration" is explicitly welcomed on surfaces where beauty can amplify comprehension, guidance, emotional reassurance, decision speed, or long-term connection to the product.
- On dense internal tools (operator consoles, admin dashboards): favor *restrained luxury* and precision. Think "high-end instrument." Only add panache where it clearly helps the operator.
- On other surfaces (onboarding, public tools, marketing moments, creative experiences): more room for expressive, delightful "useful decoration."
- Fancy must **serve the human workflow**. It should increase perceived quality, clarity, emotional satisfaction, or effectiveness without adding cognitive load, slowing tasks, or hurting performance/accessibility.
- "Fancy" includes (but is not limited to): transitions & easing, micro-interactions, hover/focus states, page/view transitions (View Transitions API), loading & skeleton experiences, selection/confirmation moments, empty/success states, scroll reveals, depth/layering, typography shifts, cursor feedback, and tasteful celebration moments.
### How the Fancy Pass Works
1. Assess appropriateness for the surface and user context.
2. Look for **opportunities** where a small amount of elegant motion or feedback would make interactions feel more premium and alive.
3. Critique existing attempts that are half-baked, janky, overused, or performance-negative.
4. Suggest specific, high-craft refinements and polish.
5. Always respect `prefers-reduced-motion` and provide graceful fallbacks.
See `references/fancy-as-fuck.md` for the full set of beauty/elegance heuristics, appropriateness guidelines, and examples.
### Recommended Invocation Pattern
```bash
# Friction first
human-flow scan the dashboard
# Then delight
human-flow fancy the dashboard
```
The output of a `fancy` pass should live in its own section of the report (or a dedicated delight report) and feed nicely into `impeccable polish` or `delight` work.
## Creating / Extending
- Add new heuristics to `references/mouse-keyboard-heuristics.md` (with detection hints and "better human workflow" examples).
- Add fancy/delights ideas to `references/fancy-as-fuck.md`.
- Update the scanner script for new static patterns (fancy detection is intentionally more qualitative).
- The skill is designed to be extended — new categories of mouse/keyboard friction **and** opportunities for tasteful elegance are welcome.
**Remember:** The goal is not "perfect accessibility" in isolation or "pretty UI". It is **making the actual anticipated physical and cognitive workflow of a human with a mouse and a keyboard feel natural, fast, and low-friction** — and, when appropriate, doing so with panache and high craft. Beauty that serves usefulness is excellent. Beauty for its own sake is noise.

10
.claude/skills/human-flow/package.json Normal file
View File

@@ -0,0 +1,10 @@
{
"name": "human-flow",
"version": "0.1.0",
"description": "UI/UX scanner focused on human mouse + keyboard workflow intuition and ergonomics. Includes 'fancy as fuck' delight & polish mode.",
"type": "module",
"scripts": {
"scan": "node scripts/scan.mjs",
"fancy": "node scripts/scan.mjs --fancy"
}
}

215
.claude/skills/human-flow/references/fancy-as-fuck.md Normal file
View File

@@ -0,0 +1,215 @@
# "Fancy as Fuck" — Beauty, Elegance & Delight Pass
This reference defines the second pass of `human-flow`: the deliberate search for opportunities to make interfaces feel premium, alive, and quietly luxurious through motion, feedback, and refined interaction details.
**Core Rule**: Fancy is never mandatory. It must earn its place by making the interface *more useful*, not just prettier.
## Appropriateness Filter (Ask This First)
Before suggesting any fancy element, answer these questions honestly:
1. **User context & frequency**
- High-frequency, heads-down work (operator console, admin tools, data-heavy workflows)? → Strong bias toward restraint. Every motion costs attention and time.
- Lower-frequency or higher-emotion surfaces (onboarding, marketing pages, public tools, creative experiences, success flows)? → More room for "useful decoration" — elegance that guides, delights, reduces anxiety, or makes the experience memorable in a positive way.
2. **Does the fancy serve usefulness?**
- Does this motion/transition/state change help the user understand the system, complete their task faster or with less friction, feel more confident, or build a better mental model?
- Or is it purely decorative?
**Key principle**: In the course of being as useful as possible, do it with panache. Beauty that amplifies clarity, feedback, guidance, or emotional connection is excellent. Beauty that exists only to look nice is noise.
3. **Aesthetic register**
- Current design language: "Operations terminal" / control room? Clinical? Playful? Luxury? Brand-forward?
- Does the proposed elegance support or fight that language?
4. **Performance & environment budget**
- Will this run on modest hardware, potentially over remote desktop / VDI, or in varied network conditions?
- Are we already at risk of animation jank or battery drain?
5. **Reduced motion & accessibility**
- Can this be completely disabled via `prefers-reduced-motion` with no loss of function or information?
- Does the fancy version ever convey information that the static version doesn't?
**Strong recommendation by surface type**:
- Dense internal tools / operator consoles: Favor *restraint and precision*. Think "expensive mechanical instrument" — satisfying, confident, never showy. Over-the-top sparkle or bouncy motion will feel wrong and unprofessional here.
- Onboarding, public-facing, marketing, or higher-emotion flows: More permission for expressive, delightful "useful decoration" that makes the experience feel alive and premium while still serving clear user goals.
---
## Categories of Elegant Delight
### 1. Transitions & Easing (The Foundation)
**Look for opportunities**:
- View/page transitions when navigating between major sections (instead of hard cuts).
- Modal / drawer enter/exit (scale + fade + backdrop blur is often elegant).
- List item additions/removals (staggered, but capped and performant).
- State changes (expand/collapse, filter results, tab switches).
- Button press → action feedback (subtle scale or color shift with excellent easing).
**Good patterns**:
- `cubic-bezier(0.2, 0.8, 0.2, 1)` or `cubic-bezier(0.16, 1, 0.3, 1)` — these feel premium.
- Short durations for frequent actions (120-180ms), slightly longer for "bigger" moments (240-320ms).
- Use the project's existing `--ease` and `--ease-out` tokens when possible.
**When to say no**:
- Every single hover does a 300ms transform.
- Long staggered lists on every filter change (use `maxStaggerRows` discipline).
- Animating layout properties (width, height, top) — causes jank.
### 2. Mouseover / Hover States (Extra Fancy)
**Look for**:
- Subtle lift + shadow increase on cards/rows (depth without glassmorphism).
- Accent color "wash" or underline expansion on hover for links and primary actions.
- Icon color or slight rotation/scale on interactive icons (tasteful only).
- Background or border "breathing" on important live elements (very restrained).
- Cursor feedback beyond the default pointer (e.g., a custom but elegant grab cursor for draggable areas).
**Human value**: Makes the interface feel responsive and high-quality. The pointer "lands" on something that acknowledges it.
**Danger zones**:
- Hover states that are too loud or change too many properties.
- Anything that requires the user to keep the mouse perfectly still to read information.
**Elegant example**:
Row in a sessions table gets a gentle background lift + the primary action button gets a tiny scale + the accent ring appears. All timed perfectly and using existing tokens.
### 3. Loading & "Ajax-Style" Experiences
**Look for opportunities**:
- Skeleton screens with a high-quality shimmer (already partially present — refine the easing and color stops).
- Optimistic UI updates with subtle undo affordance.
- Progressive loading of heavy data (e.g., sessions list populates, then live duration starts ticking elegantly).
- View Transitions API for "page" changes inside the SPA (morphing elements between views when it makes sense).
- Inline loading states on buttons that feel premium (spinner that replaces icon cleanly, not janky).
**The goal**: The interface should feel like it's *already* fast and connected, even when the network is doing work. No hard white flashes or layout shifts.
### 4. Selection, Activation & Confirmation Moments
**Fancy opportunities**:
- When you select a row or item, a beautiful but restrained "selected" treatment (stronger than just a checkbox).
- Checkmark or success animation on confirmation that feels satisfying but not childish (subtle pop + color shift).
- "Taking control" of a session could have a very short, elegant state transition (the row "hands off" to the viewer state).
- Destructive actions: the confirmation dialog itself can feel weighty and deliberate (slightly slower enter, stronger shadow).
### 5. Empty, Error & Edge States
These are high-leverage places for quiet elegance:
- Empty state with a subtle, relevant illustration + a call-to-action that has nice hover.
- Error states that don't feel like the UI is broken, but like the system is calmly handling something.
- "No results" with a soft fade-in and a helpful next step.
### 6. Advanced / Higher Ambition (Use Sparingly)
Only when the context justifies it and performance allows:
- Subtle depth / layered shadows that respond to pointer position (very light parallax on hover for cards — easy to overdo).
- Spring-based micro-physics on certain interactions (using a small spring library or CSS `transition-timing-function` approximations).
- View Transitions API with shared element transitions (e.g., a machine card "flies" into the detail view).
- Tasteful confetti or burst on rare, genuinely celebratory moments (successful long-running operation completion, first connection, etc.). Almost never appropriate in ops tools.
- Elegant cursor trail or custom cursor for specific creative/power modes (extremely rare).
### 7. Polish & Refinement Details
- Consistent motion language across the entire app (same easings, same durations for similar actions).
- Focus rings that feel like they belong to the design system (not just browser default).
- Hover/focus states on disabled elements (they should still communicate "this is here but unavailable" elegantly).
- Micro-typography shifts (slight weight or letter-spacing change on important hover states).
- Performance: 60fps is table stakes. If it drops, the fancy element is a failure.
---
## Appropriateness Matrix (Rough Guide)
| Surface Type | Fancy Level | Recommended Tone & Approach |
|-------------------------------|----------------------|-----------------------------|
| High-density ops console | Low–Medium | Restrained luxury. Precise, confident, instrument-like. Every motion must feel like it was tuned by someone who respects the user's time and focus. "Useful decoration" is allowed only when it clearly aids scanning, feedback, or spatial understanding. |
| Admin / settings | Medium | Clean, calm, professional with moments of quiet satisfaction. |
| Onboarding / first-run | Medium–High | Warm, guiding, and a little delightful. Use motion to reduce anxiety and build confidence. "Useful decoration" shines here (e.g., elegant progress, reassuring feedback). |
| Success / celebration moments | High (but brief) | Joyful but purposeful. Celebrate the user's achievement, not the designer's cleverness. |
| Marketing / public / brand surfaces | High | Brand-appropriate exuberance and personality. Here "useful decoration" can be more expressive because emotional connection and memorability *are* part of the usefulness. |
| Data visualization / creative tools | Medium–High | Responsive, alive, and exploratory. Motion should help users understand data relationships or feel in control of the creative process. |
| Dense internal tools (general)| Low–Medium | Default to restraint. Only add panache where it measurably improves human performance or reduces friction. |
**Updated guidance**: The skill now explicitly supports surfaces that can benefit from "useful decoration." On the right side of the matrix, beauty is allowed (and encouraged) when it serves comprehension, guidance, emotional reassurance, or long-term memorability. The test is always: "Does this make the user more effective or more positively connected to the product in a way that matters?"
Even on fancier surfaces, avoid anything that feels gratuitous or that slows down the core task. Panache should feel like the natural, high-craft expression of the functionality.
---
## "Useful Decoration" — Beauty That Earns Its Keep
This is the key mindset shift for this mode:
**Don't be pretty just to be pretty. In the course of being as useful as possible, do it with panache.**
"Useful decoration" means adding elegant, delightful details *because* they improve the human experience in a functional way:
### Examples of Useful Decoration
- **Spatial transitions** (View Transitions API, shared element morphs): Help users understand "this thing on the list became this detailed view." Better mental model = more effective future use.
- **Elegant loading states & optimistic updates**: Reduce perceived wait time and anxiety. Users feel the system is responsive and in control.
- **Micro-interactions on validation & feedback**: A form field that elegantly expands or shows a checkmark on success makes users feel the system is attentive and trustworthy.
- **Hover states that reveal context**: A subtle lift + extra info on a complex data row lets users preview without committing a click. Faster decision making.
- **Delightful empty & error states**: Instead of a sad gray box, a well-crafted empty state with gentle motion can guide the user toward the productive next action and make the product feel caring.
- **Satisfying confirmation moments**: A brief, elegant animation on "session ended" or "user created" gives closure and reduces the "did that actually work?" double-check.
- **Guiding attention with motion**: A subtle pulse or highlight on the single most important next action in a complex screen.
- **Memorable "personality" moments**: On public or brand surfaces, a tasteful flourish during signup or a major milestone can increase emotional connection and long-term retention.
### The Litmus Test
For any proposed fancy element, ask:
- "If we removed this tomorrow, would users be *less effective*, *less confident*, or *less positively disposed* toward the product?"
- If the answer is yes for any of those, it's useful decoration and worth doing with high craft.
- If the only answer is "it would look less nice," leave it out or dial it way back.
This principle lets the skill be appropriately restrained on internal ops tools while still allowing (and encouraging) expressive, high-panche elegance on surfaces where beauty actively serves the user's goals.
---
## How to Evaluate in a Fancy Pass
For each interactive surface or component, ask in this order:
1. **Utility first**
- Does the current state feel *cheap*, *flat*, *mechanical*, or *disjointed* in a way that makes the interface feel less trustworthy or harder to use?
- Is there a small, high-leverage piece of elegance (motion, feedback, transition, micro-interaction) that would make users:
- Understand relationships between elements better?
- Feel more confident in their actions?
- Perceive the system as faster or more responsive?
- Build a stronger mental model of the application?
- Experience less anxiety during waiting or error states?
2. **Panache as multiplier**
- In the course of making this as useful as possible, can we do it with noticeable craft and personality ("panache")?
- Would this fancy element feel like a natural, delightful extension of the core functionality rather than decoration layered on top?
3. **Context check**
- Does the proposed elegance match the surface's frequency of use and emotional register?
- On high-density tools: Does it stay restrained and purposeful?
- On surfaces that benefit from "useful decoration": Does the beauty actively help the user (guidance, feedback, memorability, emotional connection)?
4. **Cost vs. benefit**
- Would removing or refining an existing animation make the interface feel *more* premium and professional?
- Does this fancy element respect performance budgets and `prefers-reduced-motion`?
Then propose only the highest-impact, tasteful improvements. For each, clearly articulate *how it increases usefulness* (not just "it looks nice").
Always include a "reduced motion" version and note any performance considerations. If you can't articulate a clear usefulness benefit, leave it out.
---
## Anti-Patterns in the Fancy Realm
- Gratuitous bouncy springs on everything.
- Long, slow animations on frequent actions.
- Hover effects that fight the data density (big transforms in a dense table).
- "Ajax" transitions that actually make the app feel *slower* because they're too long.
- Motion that only looks good in a marketing video and falls apart in real use.
- Accessibility afterthought (fancy must be optional).
---
This mode exists to push the interface from "perfectly functional and humane" toward "quietly excellent and a pleasure to use every day." Use it after the core human-flow friction work is solid.

41
.claude/skills/human-flow/references/human-flow-checklist.md Normal file
View File

@@ -0,0 +1,41 @@
# Human-Flow Quick Checklist (Mouse + Keyboard)
Use this as a rapid mental model when scanning or reviewing interactive UI.
## Mouse Ergonomics
- [ ] All frequent actions have a hit target of at least ~32-44px (visual + padding).
- [ ] Secondary actions are visible without hovering (or clearly discoverable with very low precision cost).
- [ ] No "precision clicking" required for common tasks (tiny X, overlapping zones, thin borders as only target).
- [ ] Hover states provide clear, immediate feedback (not just color shift on text).
- [ ] Row/card clicks have strong visual affordance on hover (background, border, cursor) so the whole area feels intentional.
## Keyboard Parity
- [ ] Every mouse-clickable thing that is not a native form control is reachable by Tab and activatable by Enter/Space.
- [ ] Focus is always visible and strong (especially on dark "terminal" themes).
- [ ] Logical tab order (generally top-to-bottom, left-to-right, grouped by task).
- [ ] Modals, drawers, and transient UI properly trap focus and provide Esc/close via keyboard.
- [ ] No mouse-only gestures (hover tooltips for critical info, drag without keyboard alternative) for primary flows.
## Workflow Friction & Discoverability
- [ ] The most common action per screen/list is the largest and most obvious target.
- [ ] Frequent actions do not hide behind menus, hover, or "..." unless they are genuinely rare.
- [ ] Destructive actions are protected (confirmation that is easy to hit with mouse or keyboard, or undo).
- [ ] State changes (loading, success, disabled, selection) are immediately visible without reading small text.
- [ ] Selection models (single row, multi, checkbox) are consistent and work with both mouse and keyboard.
- [ ] Number of clicks/keystrokes to complete a common task is minimized and obvious.
## Feedback & Forgiveness
- [ ] Every interaction gives instant visual response (active state, spinner in place, highlight).
- [ ] Disabled controls clearly explain *why* (title, adjacent text, or aria).
- [ ] Error and empty states are actionable from the keyboard/mouse position the user is already in.
- [ ] There is a low-cost way to back out of or undo the last action.
## Anti-Patterns That Almost Always Hurt Humans
- Hover-revealed actions in data tables/lists (the #1 offender in operator tools).
- Icon-only compact buttons for anything done more than occasionally.
- Entire-row click that conflicts with row-internal actions (easy misfires).
- Tiny (14-20px) icons as the only way to perform a primary task.
- "Click to activate" with no visual treatment on hover/focus and no keyboard path.
- Dense toolbars or action bars with < 8px gaps between targets.
When in doubt, ask: "If I were an operator doing this 50 times today with a mouse and keyboard, would this feel smooth and obvious, or would I be fighting the interface?"

103
.claude/skills/human-flow/references/improvement-patterns.md Normal file
View File

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

200
.claude/skills/human-flow/references/mouse-keyboard-heuristics.md Normal file
View File

@@ -0,0 +1,200 @@
# 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.

86
.claude/skills/human-flow/references/report-template.md Normal file
View File

@@ -0,0 +1,86 @@
# Human-Flow Report Template
Use this structure for all `scan`, `audit`, and `report` outputs.
---
## Human-Flow Report: <Target / Component / Page>
**Date**: YYYY-MM-DD
**Scanner**: human-flow v1 (mouse + keyboard intuition focus)
**Scope**: <files/components scanned>
**Overall Human Workflow Score**: X/10
- Mouse Ergonomics: X/10
- Keyboard Parity & Efficiency: X/10
- Workflow Discoverability & Friction: X/10
**Summary**
(2-4 sentences: the biggest sources of unintuitive behavior for a human operator using mouse and keyboard, and the net effect on daily workflow.)
### High Friction (P0 — fix before broader use)
List the most damaging issues for frequent tasks.
#### Issue 1 — Severity: high (mouse + keyboard)
- **Location**: `path/to/file.tsx:42` (or component + specific element)
- **Pattern**: Hover-revealed row actions / small icon targets / missing keyboard activation / etc.
- **Human Experience**:
When scanning the Sessions list with a mouse, the Control and End buttons are dimmed until the pointer is exactly over the row. A keyboard user tabbing through never sees them at full strength. The primary action for an operator (taking control of a machine) requires extra precision and discovery.
- **Why costly**: High-frequency task. Small miss rate + extra hover step adds up across dozens of sessions per day. Creates "hunt and hope" instead of "glance and act".
- **Recommended improvement** (better for humans):
- Make actions at least 70-80% opacity at rest (or always fully visible in a dedicated column).
- Ensure the primary action (Control/View) is the strongest visual target and also activates on row click + Enter.
- Add explicit `aria-label` + visible focus treatment.
- Example pattern: always-visible ghost buttons with generous hit area + row click as power-user shortcut.
#### Issue 2 — ...
### Medium Friction (P1)
...
### Low / Polish (P2)
...
### Strengths (things that already feel good for humans)
- ...
### Fancy / Delight Opportunities (from `fancy` pass)
This section only appears when the `fancy` command/mode is run.
**Appropriateness verdict**: [Highly appropriate / Appropriate with restraint / Better kept minimal / Not appropriate for this surface]
#### Delight Idea 1 — Category: micro-interaction / transition / loading / etc.
- **Location**: ...
- **Current state**: ...
- **Opportunity**: A tasteful [specific elegant behavior] would make this interaction feel more premium and responsive.
- **Why it fits (or doesn't)**: ...
- **Suggested implementation notes**: ...
- **Reduced-motion fallback**: ...
(Repeat for 2–5 highest-leverage ideas. Be ruthless — only suggest things that genuinely elevate without adding noise.)
### Recommended Next Steps
1. ...
2. ...
**Notes for implementation**:
- Any change here should be validated with both `frontend-design` visual checklist and this scanner afterward.
- Consider adding a small set of visible keyboard shortcuts for the top 2-3 actions and surface them in the UI (e.g. in a help footer or on hover of the main button).
- After making fancy changes, re-run `human-flow fancy` to check that the additions feel intentional rather than tacked-on.
---
## Quick Reference for Common Fixes
**Small targets** → Increase min size + padding. Use the generous wrapper pattern.
**Hover-only actions** → Raise resting opacity or move to always-visible "Actions" area. Never rely on hover for primary or frequent actions.
**Mouse-only activation** → Add `tabIndex`, `onKeyDown` for Enter/Space, strong `:focus-visible`, and `aria-*` labels.
**Weak feedback** → Add immediate `:active`/loading state, row highlight on selection, and clear disabled messaging.
**Precision-heavy workflows** → Widen hit areas, reduce number of steps, make the "obvious next thing" the biggest target.
---
*This template is intentionally human-first in language. Every finding must explain the lived experience of a person with a mouse and keyboard, not just the code smell.*

254
.claude/skills/human-flow/scripts/scan.mjs Normal file
View File

@@ -0,0 +1,254 @@
#!/usr/bin/env node
/**
* human-flow scanner
*
* Static analysis pass for mouse + keyboard workflow friction.
* Expands the spirit of frontend-design and impeccable with a narrow,
* human-motor-and-expectation focus.
*
* Usage:
* node scripts/scan.mjs --path dashboard/src --format json
* node scripts/scan.mjs --path dashboard/src/features/sessions
*
* It is intentionally lightweight (regex + heuristics) so it can run fast
* inside agent loops. The real intelligence comes from the agent combining
* these findings with full component reading and task-flow understanding.
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const args = process.argv.slice(2);
let targetPath = 'src';
let format = 'text';
let mode = 'friction'; // 'friction' | 'fancy'
for (let i = 0; i < args.length; i++) {
if (args[i] === '--path' || args[i] === '-p') targetPath = args[++i];
if (args[i] === '--format' || args[i] === '-f') format = args[++i];
if (args[i] === '--fancy' || args[i] === '--mode=fancy') mode = 'fancy';
if (args[i] === '--mode' && args[i + 1] === 'fancy') { mode = 'fancy'; i++; }
}
const absTarget = path.resolve(process.cwd(), targetPath);
if (!fs.existsSync(absTarget)) {
console.error(`Target not found: ${absTarget}`);
process.exit(1);
}
const findings = [];
function walk(dir) {
const entries = fs.readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (['node_modules', 'dist', 'build', '.git'].includes(entry.name)) continue;
walk(full);
} else if (/\.(tsx|jsx|ts|js|css)$/.test(entry.name)) {
analyzeFile(full);
}
}
}
function analyzeFile(file) {
const content = fs.readFileSync(file, 'utf8');
const rel = path.relative(process.cwd(), file).replace(/\\/g, '/');
const lines = content.split('\n');
if (mode === 'fancy') {
// Fancy / beauty & elegance pass — lighter static signals + prompts for qualitative review
let match;
// Existing transitions / animations (look for opportunities to refine)
const hasTransition = /transition:|transition-\w+:|animate-|@keyframes|ViewTransition|view-transition/i.test(content);
if (hasTransition) {
findings.push({
file: rel,
line: 1,
category: 'fancy-existing',
severity: 'info',
pattern: 'existing-motion',
message: 'This file already contains motion/transition code. Good candidate for the fancy pass to review quality, consistency, and restraint.',
humanImpact: 'Existing fancy elements can feel either premium or cheap/janky depending on execution.',
suggestion: 'In the fancy pass, evaluate easing curves, durations, performance, reduced-motion respect, and whether the motion serves the human workflow or just decorates.'
});
}
// Missing View Transitions API in SPA navigation contexts
if (/(useNavigate|navigate\(|<Link|react-router|next\/|router\.push)/i.test(content) && !/document\.startViewTransition|View Transitions|view-transition/i.test(content)) {
findings.push({
file: rel,
line: 1,
category: 'fancy-opportunity',
severity: 'low',
pattern: 'missing-view-transitions',
message: 'Navigation or view change logic detected without use of the View Transitions API.',
humanImpact: 'Page-like changes can feel abrupt or cheap. Modern "ajax-style" smooth transitions between views feel significantly more premium.',
suggestion: 'Consider wrapping key navigation with document.startViewTransition() + CSS view-transition-name for elegant morphs or fades. Only where it genuinely improves perceived quality.'
});
}
// Basic hover without fancy enhancement
if (/:hover\s*\{[^}]*background|transform|box-shadow|scale|opacity/i.test(content)) {
findings.push({
file: rel,
line: 1,
category: 'fancy-opportunity',
severity: 'low',
pattern: 'basic-hover',
message: 'Hover state exists but may be basic. Opportunity for more elegant micro-interaction.',
humanImpact: 'A merely functional hover feels flat. A refined one (subtle lift + shadow + accent) makes the interface feel alive and high-craft.',
suggestion: 'Layer tasteful depth (shadow + slight scale or translate) with excellent easing. Keep it restrained, especially in dense data views.'
});
}
return; // In fancy mode we mostly collect signals for the agent to do deep qualitative work
}
// === FRICTION MODE (original) ===
// 1. Small / sm button targets in interactive contexts (very common friction)
const smallButton = /size=["']sm["']|<button[^>]*className=.*btn--sm|height:\s*2[0-8]px|min-height:\s*2[0-8]px/g;
let match;
while ((match = smallButton.exec(content)) !== null) {
const lineNo = content.substring(0, match.index).split('\n').length;
findings.push({
file: rel,
line: lineNo,
category: 'target-size',
severity: 'high',
pattern: 'small-button',
message: 'Compact "sm" button or very small height used for an action. Frequent actions (especially in lists) become precision targets.',
humanImpact: 'Operators must slow down and aim carefully for common tasks. High error rate under time pressure.',
suggestion: 'Use default (md) size for primary/frequent actions. For true compact row actions, ensure generous invisible padding or switch to a larger always-visible treatment.'
});
}
// 2. Hover-revealed or low-opacity row actions (the classic operator console anti-pattern)
if (/\.dt__rowactions|\.rowactions|\.actions\s*\{[^}]*opacity:\s*0\.[0-6]/s.test(content) ||
/opacity:\s*0\.[0-6][^}]*hover|hover[^}]*opacity:\s*(1|0\.[7-9])/s.test(content)) {
const lineNo = 1; // best effort
findings.push({
file: rel,
line: lineNo,
category: 'discoverability',
severity: 'high',
pattern: 'hover-only-actions',
message: 'Row or list actions are dimmed or hidden until hover (or only fully visible on hover).',
humanImpact: 'A human scanning a list with eyes + mouse must "paint" every row to discover what they can do. Keyboard users often never see the controls at full strength.',
suggestion: 'Raise resting opacity to 0.7–1.0 so actions are scannable at a glance. Or move frequent actions into a dedicated, always-visible column or primary row target. Keep hover only for polish, not discovery.'
});
}
// 3. onClick without obvious keyboard support on non-native elements
const clickNoKeyboard = /onClick=\{[^}]+}\s*(?!.*(onKeyDown|tabIndex|role=))/g;
while ((match = clickNoKeyboard.exec(content)) !== null) {
const lineNo = content.substring(0, match.index).split('\n').length;
// Only flag if it looks like a custom interactive (div, span, custom component in list context)
const context = content.substring(Math.max(0, match.index - 80), match.index + 120);
if (/<\s*(div|span|tr|td|li|custom|Card|Row)[^>]*onClick|onClick[^>]*<\s*(div|span|tr|td|li|Card|Row)/.test(context)) {
findings.push({
file: rel,
line: lineNo,
category: 'keyboard-parity',
severity: 'high',
pattern: 'click-without-keyboard',
message: 'Custom element has onClick but no visible tabIndex/onKeyDown/Enter-Space handling in the immediate area.',
humanImpact: 'Keyboard (or mixed mouse+keyboard) users cannot activate the same thing the mouse can without extra workarounds.',
suggestion: 'Add tabIndex={0}, onKeyDown handler for Enter/Space, and strong :focus-visible styles. Prefer native <button> when possible.'
});
}
}
// 4. Icon-only buttons without accessible name (common with small action icons)
const iconButton = /<Button[^>]*>\s*<[^>]+Icon|<\s*button[^>]*>\s*<[^>]+Icon|<[A-Z][^>]*>\s*<[^>]+Icon/g;
while ((match = iconButton.exec(content)) !== null) {
const lineNo = content.substring(0, match.index).split('\n').length;
const nearby = content.substring(Math.max(0, match.index - 30), match.index + 180);
if (!/aria-label|title=/.test(nearby)) {
findings.push({
file: rel,
line: lineNo,
category: 'discoverability',
severity: 'medium',
pattern: 'icon-only-no-label',
message: 'Icon-only button or action with no aria-label or title.',
humanImpact: 'Screen readers and keyboard users (and anyone who forgets what the tiny icon means) have no idea what it does until they activate it.',
suggestion: 'Add aria-label (and preferably a visible label or tooltip that works on focus too).'
});
}
}
// 5. Very narrow status / action columns (precision rail)
if (/width:\s*2[0-9]px|width:\s*30px|padding-left:\s*0 !important/.test(content) && /status|actions|select/i.test(content)) {
findings.push({
file: rel,
line: 1,
category: 'target-size',
severity: 'medium',
pattern: 'narrow-rail',
message: 'Very narrow column (status, select, or actions rail) used for interactive or important visual elements.',
humanImpact: 'Mouse must be extremely precise to hit the control or even read the status comfortably.',
suggestion: 'Widen the rail or make the entire left edge a larger hit area (see dt__checkwrap pattern). Status can be visual + text on hover/focus.'
});
}
// 6. Row that is fully clickable + internal small actions (mis-click risk)
if (/onRowClick|onClick.*row|tr.*onClick/.test(content) && /dt__rowactions|rowactions/.test(content)) {
findings.push({
file: rel,
line: 1,
category: 'workflow',
severity: 'medium',
pattern: 'row-click-plus-internal-actions',
message: 'Whole row is clickable (for detail/open) while also containing small action buttons inside the row.',
humanImpact: 'Easy to accidentally trigger the row action when aiming for the small icon (or vice versa). Classic source of "I didn\'t mean to open that".',
suggestion: 'Make the primary row action very clearly the dominant target (bigger visual weight, different treatment). Or stop making the whole row clickable and use a dedicated primary button + separate secondary actions.'
});
}
}
walk(absTarget);
// Deduplicate similar findings per file
const seen = new Set();
const uniqueFindings = findings.filter(f => {
const key = `${f.file}:${f.pattern}`;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
if (format === 'json') {
console.log(JSON.stringify({ target: absTarget, mode, findings: uniqueFindings }, null, 2));
} else {
const title = mode === 'fancy'
? `Human-Flow "Fancy as Fuck" Signals for: ${absTarget}`
: `Human-Flow Scan Results for: ${absTarget}`;
console.log(`${title}\n`);
if (uniqueFindings.length === 0) {
if (mode === 'fancy') {
console.log('No obvious static fancy signals detected.\nThis is normal — the real fancy pass is qualitative. Load references/fancy-as-fuck.md and evaluate the target for beauty, elegance, and appropriate delight opportunities.');
} else {
console.log('No obvious mouse/keyboard friction patterns detected by static rules.\nRun a full agent review with the references/heuristics.md for deeper semantic issues.');
}
} else {
uniqueFindings.forEach((f, i) => {
console.log(`${i + 1}. [${f.severity.toUpperCase()}] ${f.category} — ${f.pattern}`);
console.log(` File: ${f.file}:${f.line}`);
console.log(` ${f.message}`);
console.log(` Human impact: ${f.humanImpact}`);
console.log(` Suggestion: ${f.suggestion}\n`);
});
}
}
const exitCode = mode === 'fancy' ? 0 : (uniqueFindings.length > 0 ? 2 : 0);
process.exit(exitCode);