From 37ccc5f35c4f39feaa456522c71b76affef4609e Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Wed, 3 Jun 2026 20:07:28 -0700 Subject: [PATCH] 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/README.md | 52 ++++ .claude/skills/human-flow/SKILL.md | 152 +++++++++++ .claude/skills/human-flow/package.json | 10 + .../human-flow/references/fancy-as-fuck.md | 215 +++++++++++++++ .../references/human-flow-checklist.md | 41 +++ .../references/improvement-patterns.md | 103 +++++++ .../references/mouse-keyboard-heuristics.md | 200 ++++++++++++++ .../human-flow/references/report-template.md | 86 ++++++ .claude/skills/human-flow/scripts/scan.mjs | 254 ++++++++++++++++++ .grok/skills/human-flow/README.md | 20 ++ .grok/skills/human-flow/SKILL.md | 19 ++ session-logs/2026-06-03-session.md | 89 ++++++ 12 files changed, 1241 insertions(+) create mode 100644 .claude/skills/human-flow/README.md create mode 100644 .claude/skills/human-flow/SKILL.md create mode 100644 .claude/skills/human-flow/package.json create mode 100644 .claude/skills/human-flow/references/fancy-as-fuck.md create mode 100644 .claude/skills/human-flow/references/human-flow-checklist.md create mode 100644 .claude/skills/human-flow/references/improvement-patterns.md create mode 100644 .claude/skills/human-flow/references/mouse-keyboard-heuristics.md create mode 100644 .claude/skills/human-flow/references/report-template.md create mode 100644 .claude/skills/human-flow/scripts/scan.mjs create mode 100644 .grok/skills/human-flow/README.md create mode 100644 .grok/skills/human-flow/SKILL.md create mode 100644 session-logs/2026-06-03-session.md diff --git a/.claude/skills/human-flow/README.md b/.claude/skills/human-flow/README.md new file mode 100644 index 0000000..aa27a4d --- /dev/null +++ b/.claude/skills/human-flow/README.md @@ -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. \ No newline at end of file diff --git a/.claude/skills/human-flow/SKILL.md b/.claude/skills/human-flow/SKILL.md new file mode 100644 index 0000000..5241439 --- /dev/null +++ b/.claude/skills/human-flow/SKILL.md @@ -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 ` → friction mode (default) + - `node scripts/scan.mjs --path --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: + +**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. diff --git a/.claude/skills/human-flow/package.json b/.claude/skills/human-flow/package.json new file mode 100644 index 0000000..6392946 --- /dev/null +++ b/.claude/skills/human-flow/package.json @@ -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" + } +} \ No newline at end of file diff --git a/.claude/skills/human-flow/references/fancy-as-fuck.md b/.claude/skills/human-flow/references/fancy-as-fuck.md new file mode 100644 index 0000000..34780d9 --- /dev/null +++ b/.claude/skills/human-flow/references/fancy-as-fuck.md @@ -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. \ No newline at end of file diff --git a/.claude/skills/human-flow/references/human-flow-checklist.md b/.claude/skills/human-flow/references/human-flow-checklist.md new file mode 100644 index 0000000..3c8eadc --- /dev/null +++ b/.claude/skills/human-flow/references/human-flow-checklist.md @@ -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?" \ No newline at end of file diff --git a/.claude/skills/human-flow/references/improvement-patterns.md b/.claude/skills/human-flow/references/improvement-patterns.md new file mode 100644 index 0000000..7c6af61 --- /dev/null +++ b/.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 + {/* opacity 0.5 until hover */} + + + +``` + +**Better for humans**: +```tsx +// Option A: Dedicated actions column, always visible, slightly dimmed but scannable + +
+ + +
+ + +// Option B: Primary action is the row itself + one very obvious secondary + + ... + + + + +``` + +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 + +``` + +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 + +``` + +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. \ No newline at end of file diff --git a/.claude/skills/human-flow/references/mouse-keyboard-heuristics.md b/.claude/skills/human-flow/references/mouse-keyboard-heuristics.md new file mode 100644 index 0000000..dd2c5d5 --- /dev/null +++ b/.claude/skills/human-flow/references/mouse-keyboard-heuristics.md @@ -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 `
`, ``, 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 `