@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/enhance-web-ux/HEURISTICS.md

@@ -0,0 +1,248 @@
+# Heuristics & Laws of UX — Quick Reference
+
+The canonical references the agent maps every pain point against. Source-of-truth links are
+at the bottom. Keep this lean — the goal is fast lookup, not a textbook.
+
+---
+
+## NN/g 10 Usability Heuristics (Nielsen, 1994; updated 2024)
+
+### #1 Visibility of System Status
+
+The system always tells the user what is happening, via appropriate feedback in reasonable
+time.
+
+**On screen:** loading spinners, progress bars, "saved" toasts, inline status chips
+("AI解析済", "連携済", "未処理"), breadcrumbs showing where you are, badges that count
+unread items, real-time validation under form fields.
+
+**Common violations:** async work runs invisibly (AI extraction, autosave, sync); state
+that affects routing decisions (linked vs. unlinked) is hidden one click deep; nav doesn't
+show selection.
+
+---
+
+### #2 Match Between System and Real World
+
+Speak the user's language. Use words, phrases, concepts familiar to them. Follow real-world
+conventions, natural ordering.
+
+**On screen:** "Empty trash" not "Purge resource"; receipt icon for receipts, plane icon
+for travel; date in the user's locale; sort orders that match how the domain actually
+thinks (newest first for messages, alphabetical for files, status-grouped for tasks).
+
+**Common violations:** engineering jargon in user-facing labels (`fileStatus=unlinked`),
+generic icons for domain-specific entities, unfamiliar mental models forced on users.
+
+---
+
+### #3 User Control & Freedom
+
+Users make mistakes — provide a clearly marked emergency exit. Support undo and redo.
+
+**On screen:** Cancel buttons on every modal, Undo toasts after destructive actions,
+breadcrumb to step out, browser-back honoured, multi-step forms remember progress on back.
+
+**Common violations:** modals with only "OK"; bulk delete with no undo; form abandonment
+loses all input; no way to back out of an irreversible workflow step.
+
+---
+
+### #4 Consistency & Standards
+
+Same things look the same, different things look different. Follow platform conventions
+(Jakob's Law: users spend most of their time on OTHER products).
+
+**On screen:** primary-action button looks the same on every page; destructive actions
+are red everywhere; date format consistent; same icon = same meaning across views;
+keyboard shortcuts (`Cmd+K`, `Esc`, `?`) match platform norms.
+
+**Common violations:** two different "Submit" buttons styled differently; the same status
+shown as "✓", "OK", and "完了" in three places; clickable items that don't look clickable.
+
+---
+
+### #5 Error Prevention
+
+Better than a good error message: a design that prevents the error.
+
+**On screen:** disabled state on submit until the form is valid; date pickers (not free
+text); type-safe enums (not free strings); confirmation step on irreversible bulk
+operations; auto-save on long forms.
+
+**Common violations:** free-text fields that should be enums; destructive actions a single
+mis-click away; forms that submit on Enter inside textarea; copy-paste of formatted text
+silently mangling input.
+
+---
+
+### #6 Recognition Rather Than Recall
+
+Make options visible. Don't make users remember information from one screen to use it on
+another.
+
+**On screen:** breadcrumbs showing the path; recent searches autocompleted; field labels
+always visible (not just placeholder); icon + text labels; keyboard shortcuts listed in
+menus next to actions; "you saw this 5 mins ago" markers.
+
+**Common violations:** placeholder-only labels that disappear on focus; cryptic icon-only
+toolbars; forms across multiple steps that don't summarise prior input; "remember which
+tab you were on" expected of the user.
+
+---
+
+### #7 Flexibility & Efficiency of Use
+
+Shortcuts speed up expert use. Allow users to tailor frequent actions.
+
+**On screen:** keyboard shortcuts; bulk actions; saved filters / views; multi-select with
+shift-click; right-click menus; quick command palette (`Cmd+K`); customisable columns;
+power-user features hidden behind a `Show advanced` toggle.
+
+**Common violations:** every action is N clicks deep; no keyboard alternative; no way to
+batch a repeated action; expert workflow forces novice flow.
+
+---
+
+### #8 Aesthetic & Minimalist Design
+
+Interfaces should not contain information that is irrelevant or rarely needed. Every extra
+unit of information competes with the relevant ones.
+
+**On screen:** empty cells removed (not just left blank); progressive disclosure (`Show
+more`); collapsing sections; default-collapsed advanced settings; no decorative noise.
+
+**Common violations:** empty `Amount` and `Size` columns for folder rows; "Tip:" boxes
+that never go away; instruction rows above every list; logo + nav + breadcrumb + tab bar
++ section header all stacked.
+
+---
+
+### #9 Help Users Recognize, Diagnose, and Recover from Errors
+
+Plain language, precise problem, constructive solution.
+
+**On screen:** "Email is required" under the field, not "Validation failed"; "File too
+large (12 MB) — max 10 MB. Compress or split it." with a Compress button; 404 pages
+with search; failure toasts that include a Retry button.
+
+**Common violations:** error codes without explanation; "Something went wrong"; errors
+that vanish before reading; field-level errors floating in a global toast.
+
+---
+
+### #10 Help and Documentation
+
+Best is no docs needed; if needed, easy to search, focused on the user's task, listing
+concrete steps.
+
+**On screen:** in-context tooltips on icon-only buttons; a `?` link near complex fields;
+empty states that explain what the section will contain and how to populate it; first-run
+checklists.
+
+**Common violations:** docs in a separate site requiring auth; tooltips that explain the
+icon's name not its action; no empty state at all.
+
+---
+
+## Laws of UX (supporting principles)
+
+### Jakob's Law
+
+> Users spend most of their time on OTHER sites. They expect yours to work the same way.
+
+**Implication:** copy patterns from category leaders. A file explorer should look like
+Drive / Dropbox / Mega. A code editor should look like VS Code / IntelliJ. Don't reinvent
+where convention exists.
+
+### Hick's Law
+
+> Time to make a decision = log₂(N+1) of options.
+
+**Implication:** group related actions; collapse rarely-used options under "More"; never
+show all 12 filters at once if 3 cover 90% of use. Applies only when options must be
+weighed; looking up a known item in an ordered list (a country, a prefecture) is search,
+so give it typeahead instead of trimming it.
+
+### Fitts's Law
+
+> Time to acquire a target ∝ distance / size.
+
+**Implication:** primary actions should be large and stable; toolbar buttons must not
+shrink to 24px on hover; click targets at least 44×44 px on touch; destructive actions
+NOT immediately adjacent to common ones.
+
+### Miller's Law
+
+> The average person can hold ~7 ± 2 items in working memory; later work puts it nearer 4
+> (Cowan, 2001).
+
+**Implication:** it is about what the user must *hold in mind*, not how many items a screen
+shows. A visible menu is read, not memorised, so this law sets no cap on menu length. Do:
+keep labels visible while fields are filled, show earlier choices instead of making users
+remember them, group long codes in 3–4s with Copy, split long forms into labelled groups of
+3–5 fields, show running totals. For a measured pass on one flow, use `enhance-ux-laws`.
+
+### Tesler's Law (Law of Conservation of Complexity)
+
+> Every system has irreducible complexity. The question is who absorbs it — designer,
+> developer, or user.
+
+**Implication:** if the user keeps asking "which folder had AI done?", the complexity is
+currently absorbed by the user. Move it to the system: show an inline AI chip. Cost the
+designer / dev time, save every user every time forever.
+
+### Doherty Threshold
+
+> Productivity skyrockets when the system responds in <400 ms.
+
+**Implication:** optimistic UI updates; skeleton loaders; pre-fetch on hover; never let
+the user wait without feedback (see #1).
+
+### Postel's Law
+
+> Be liberal in what you accept, conservative in what you produce.
+
+**Implication:** accept dates in many formats, normalise on display; trim whitespace;
+parse "1,234.56" and "1234.56" the same; case-insensitive search.
+
+### Aesthetic-Usability Effect
+
+> Users perceive aesthetically pleasing design as easier to use.
+
+**Implication:** spacing, typography, and visual rhythm are not "polish" — they are
+usability. Don't ship raw functionality without applying the design system.
+
+### Peak-End Rule
+
+> People judge an experience by its peak (best/worst moment) and its end.
+
+**Implication:** make sure the success-state of any flow (form submitted, payment done,
+file uploaded) feels good — confetti, micro-celebration, summary, clear next step. Don't
+just dump them back to the list view with no acknowledgement.
+
+---
+
+## Mapping Heuristics to Common UI Symptoms
+
+| Symptom | First check | Second check |
+|---------|-------------|--------------|
+| User asks "which one is X?" | #6 Recognition | #2 Match Real World |
+| User asks "did it work?" | #1 Visibility | Doherty Threshold |
+| User asks "how do I undo?" | #3 Control & Freedom | #5 Error Prevention |
+| Two screens look subtly different | #4 Consistency | Jakob's Law |
+| Page feels crowded / heavy | #8 Minimalist | Hick's Law, Miller's Law |
+| Buttons too small / wrap / overflow | Fitts's Law | #4 Consistency |
+| Async result hidden / discoverable | #1 Visibility | Tesler's Law |
+| Power user complains it's slow to use | #7 Flexibility | Hick's Law |
+| Error looks like a system stack trace | #9 Recover from Errors | #2 Match Real World |
+| Empty page with no explanation | #10 Help & Docs | Peak-End Rule |
+
+---
+
+## Sources
+
+- [NN/g — 10 Usability Heuristics for User Interface Design](https://www.nngroup.com/articles/ten-usability-heuristics/)
+- [NN/g — 10 Usability Heuristics Applied to Complex Applications](https://www.nngroup.com/articles/usability-heuristics-complex-applications/)
+- [Laws of UX](https://lawsofux.com/)
+- [Tognazzini — First Principles of Interaction Design](https://asktog.com/atc/principles-of-interaction-design/)

package/skills/enhance-web-ux/PATTERNS.md

@@ -0,0 +1,375 @@
+# Anti-Pattern → Replacement Library
+
+A living catalogue of "smells" found on real pages and the design-system-respecting
+replacements. Each entry links the smell to its NN/g heuristic and gives a concrete code
+shape for the fix. Add entries every time the agent runs an enhancement and discovers a new
+pattern worth remembering.
+
+---
+
+## 1. Generic Icon for Every Item Type
+
+**Smell:** every folder / row / card uses the same `<Folder>` icon. The user must read
+the title to discriminate type.
+
+**Heuristic:** #6 Recognition over Recall, #2 Match Real World, Miller's Law
+
+**Replacement:** introduce a small pure-function helper that maps an item to a
+`{ Icon, label, tone }` object. Icon comes from the icon library already in use.
+Label is a short Japanese / English domain noun. Tone references existing semantic tokens
+(`signal-warn`, `ai`, `brand`, `muted`).
+
+```tsx
+// helpers/get-folder-category.tsx
+export interface FolderCategory {
+  label: string
+  Icon: LucideIcon
+  iconColorClass: string  // text-* token
+  iconBgClass: string     // bg-*/n token
+  chipClass: string       // border + bg + text token tuple
+}
+
+export const getFolderCategory = (item: TreeItem): FolderCategory => {
+  if (item.data?.isDocumentLinked) return { label: "連携", Icon: Link2, ... }
+  if (/notice|通知|e-gov/.test(haystack)) return { label: "通知書", Icon: BellRing, ... }
+  if (/template|雛形/.test(haystack))      return { label: "雛形", Icon: LayoutTemplate, ... }
+  // … one branch per domain category, default last
+  return { label: "フォルダ", Icon: Folder, ... }
+}
+```
+
+Then in the renderer:
+
+```tsx
+const cat = getFolderCategory(item)
+<span className={cn("h-7 w-7 rounded-sm flex items-center justify-center", cat.iconBgClass)}>
+  <cat.Icon size={14} className={cat.iconColorClass} />
+</span>
+<span className={cn("text-[11px] px-1.5 py-0.5 rounded-sm border whitespace-nowrap", cat.chipClass)}>
+  {cat.label}
+</span>
+```
+
+**Why it's better than ad-hoc inline icons:** new categories are one branch in one file;
+icon + label + tone always travel together (no chance of an orange icon with a blue label);
+unit-testable.
+
+---
+
+## 2. Empty Cells in a Data Grid
+
+**Smell:** a folder row in a "Files" grid shows blank `Amount` and `Size` columns because
+folders don't have those scalars. Whole columns are wasted whitespace for half the rows.
+
+**Heuristic:** #8 Aesthetic & Minimalist Design
+
+**Replacement:** EITHER (a) compute a meaningful aggregate (sum of contained file
+amounts, sum of contained file sizes, count of contained files), OR (b) merge the column
+with another for that row type.
+
+```tsx
+// helpers/get-folder-aggregates.ts
+export interface FolderAggregates {
+  fileCount: number
+  aiAnalyzedCount: number
+  unlinkedCount: number
+  totalAmount: number
+  totalSizeBytes: number
+}
+export const getFolderAggregates = (files: UploadedFile[], folderId: string): FolderAggregates => { ... }
+```
+
+```tsx
+// renderer
+{ item.type === "folder" ? (
+  <>
+    <span className="text-right tabular-nums">{formatJpy(agg.totalAmount)}</span>
+    <span className="text-right tabular-nums">{formatBytesShort(agg.totalSizeBytes)}</span>
+  </>
+) : (
+  <>
+    <span className="text-right tabular-nums">{formatJpy(file.amount)}</span>
+    <span className="text-right tabular-nums">{formatBytesShort(file.size)}</span>
+  </>
+)}
+```
+
+**Bonus:** dim the cell to muted when the value is zero. Don't render `0` loud — render
+`—` muted. Renders empty rows visually subordinate to populated ones.
+
+---
+
+## 3. Always-On Hint / Instruction Row
+
+**Smell:** above every list there is a row that reads "☐ チェックで選択 / Shift+クリック /
+Ctrl+A: すべて". It is repeated forever and consumes a row of vertical real estate that
+never goes away.
+
+**Heuristic:** #6 Recognition over Recall, #8 Aesthetic & Minimalist Design
+
+**Replacement:** show the hint *only when the affordance is in use*. The rest of the time,
+collapse to a discreet `?` with a tooltip.
+
+```tsx
+{/* Tiny `?` glyph in column header */}
+<div title="クリックで選択・Shift+クリックで範囲選択・Ctrl+Aですべて選択"
+     className="flex items-center justify-center text-muted-foreground/60 cursor-help">
+  <span className="text-[10px] leading-none">?</span>
+</div>
+
+{/* Live hint bar — only when N rows selected */}
+{selected.size > 0 && (
+  <div className="px-3 py-1 bg-signal-in border-b border-signar-in text-xs">
+    <span className="font-medium whitespace-nowrap">{selected.size}件選択中</span>
+    <span className="whitespace-nowrap text-brand/60">Esc: 解除</span>
+  </div>
+)}
+```
+
+**Why:** affordances should be discoverable, not constantly recited. Once a user has
+selected a row, the hint about HOW to select becomes useless and the hint about WHAT to do
+NEXT becomes useful.
+
+---
+
+## 4. Toolbar Button Labels Wrap to 2 Lines
+
+**Smell:** at certain widths a button label like `通知書ZIP` or `アップロード` wraps and
+breaks the toolbar's visual rhythm. The button suddenly takes 2 lines of vertical space.
+
+**Heuristic:** #4 Consistency, Fitts's Law
+
+**Replacement:** combination of `whitespace-nowrap`, `flex-shrink-0`, and **progressive
+label visibility** based on Tailwind breakpoints — show full label only when there is room
+for it; collapse to icon-only otherwise. Always keep a tooltip with the full label.
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild>
+      <Button
+        size="sm"
+        className="h-9 flex-shrink-0 whitespace-nowrap px-2.5"
+        aria-label="通知書ZIPを取り込む"
+      >
+        <BellRing size={16} />
+        <span className="hidden lg:inline ml-1.5 whitespace-nowrap">通知書ZIP</span>
+      </Button>
+    </TooltipTrigger>
+    <TooltipContent>e-Gov・e-Tax・eLTAXの通知書ZIPを取り込む</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+Conventional breakpoints for label visibility:
+
+- `default → lg` (icon-only) for tertiary actions (`通知書ZIP`)
+- `default → md` (icon-only) for secondary actions (`フォルダ`)
+- `always` for primary CTAs (`アップロード`)
+
+**NEVER** let a label wrap. If you can't fit it, hide the text and rely on the tooltip.
+
+---
+
+## 5. Status Badge Wraps Inside a Narrow Column
+
+**Smell:** a 64px column shows a `Badge` with the label `未処理`. The badge wraps to render
+`未処` on one line and `理` on the next.
+
+**Heuristic:** #4 Consistency
+
+**Replacement:** at the **primitive** level, add `whitespace-nowrap` to the Badge variants
+so this never happens again anywhere. As a fallback (if you don't own the primitive), pass
+`className="whitespace-nowrap"` at every call site AND widen the column to fit the natural
+chip width.
+
+If you have multiple chips for one row that don't fit horizontally (e.g. AI marker + status
+badge), STACK THEM VERTICALLY (`flex-col gap-0.5`). Never let them try to fit horizontally
+in a column that doesn't have the room.
+
+```tsx
+{/* Status column — stacks vertically when both AI + status exist */}
+<div className="flex flex-col items-center justify-center gap-0.5">
+  {file.aiData && <span className="… AI chip …">AI</span>}
+  {file.status === "unlinked" && (
+    <Badge variant="destructive" size="xs" className="whitespace-nowrap px-1.5">
+      <AlertTriangle size={9} /> 未処理
+    </Badge>
+  )}
+</div>
+```
+
+---
+
+## 6. No Indicator for Async / Computed Results (AI, Link, Sync)
+
+**Smell:** the system ran AI extraction or linked a file to a journal entry, but the row
+gives no visual marker. The user has to click in to find out.
+
+**Heuristic:** #1 Visibility of System Status, Tesler's Law
+
+**Replacement:** an inline chip on the row, themed with a dedicated semantic token
+(`bg-ai-soft text-ai`, `bg-signal-in text-signal-in`). For folder rows, count and show:
+`AI×3` means "3 of the files in here have AI metadata". For file rows, just `AI`.
+
+```tsx
+{file.aiData && (
+  <span
+    className="inline-flex items-center gap-0.5 whitespace-nowrap rounded-sm
+               border border-ai/40 bg-ai-soft px-1 py-0.5 text-[10px] font-medium
+               leading-none text-ai"
+    title="AIで内容が解析されています"
+  >
+    <Sparkles size={8} />
+    AI
+  </span>
+)}
+```
+
+**Why a chip and not a dot or an icon?** Recognition: a labelled chip needs no key.
+
+---
+
+## 7. Identical Visual Weight for Empty vs. Populated Rows
+
+**Smell:** a folder with 0 files and a folder with 12 files look exactly the same.
+
+**Heuristic:** #8 Minimalist (don't fight for attention), #6 Recognition
+
+**Replacement:** apply `opacity-70` (or muted variant) to the empty row's container.
+Don't hide it — the user still needs to see the count — but stop letting it compete.
+
+```tsx
+const folderIsEmpty = item.type === "folder" && (folderData.fileCount ?? 0) === 0
+<div className={cn("…", folderIsEmpty && "opacity-70")}>…</div>
+```
+
+---
+
+## 8. Generic 3-Column Card Grid Used as Default Layout
+
+**Smell:** every "section" of a page is the same icon → title → 1-line description card,
+laid out in a uniform 3-column grid. This is the most reliable AI-tell.
+
+**Heuristic:** #4 Consistency (broken — it's the SAME consistency to a fault), Aesthetic-
+Usability Effect
+
+**Replacement:** vary layout by section purpose. Hero gets a generous full-bleed asymmetric
+layout. Stats get a compact horizontal strip with tabular numbers. Long-form content gets
+a max-width column. Action lists get a vertical stack with leading icons. The page should
+have visual rhythm, not pattern repetition.
+
+Concrete checklist:
+
+- Different `py-*` per section type (hero generous, form tight, footer minimal)
+- Different number of columns per section (1 / 2 / 3 / asymmetric)
+- Different border-radius semantics (pill for tags, rounded for cards, sharp for tables)
+
+---
+
+## 9. Date Shown in Two Places on the Same Row
+
+**Smell:** the row shows `2024/04/18` inline under the name AND in a dedicated `Date`
+column, both saying the same thing.
+
+**Heuristic:** #8 Minimalist
+
+**Replacement:** delete one. Choose the one that aligns vertically with peers (the column
+form), so the eye can scan dates top-to-bottom without re-fixating per row.
+
+---
+
+## 10. Mixed Icon Libraries in the Same View
+
+**Smell:** the same view uses some icons from `lucide-react`, some from `@heroicons`, some
+custom SVGs.
+
+**Heuristic:** #4 Consistency
+
+**Replacement:** pick one icon library per project. If you must use multiple, scope by
+context: e.g. all *navigation* uses one library, all *content* icons use another, never
+mixed within a single visual unit.
+
+---
+
+## 11. "Just an Empty State" — No Guidance, No Next Step
+
+**Smell:** an empty list shows "No items" or worse, just nothing.
+
+**Heuristic:** #10 Help & Documentation, Peak-End Rule (the first interaction is the empty
+state)
+
+**Replacement:** every empty state should answer three questions:
+
+1. **What goes here?** ("Upload your first invoice…")
+2. **Why doesn't it have anything yet?** ("Drop a PDF or…")
+3. **How do I add one?** With a CTA button matching the page's primary action.
+
+Optional: a small illustration that matches the brand voice (NOT generic stock).
+
+---
+
+## 12. Destructive Action Adjacent to Common Action
+
+**Smell:** `Save` and `Delete` are next to each other in the same toolbar, same size, same
+colour family.
+
+**Heuristic:** #5 Error Prevention, Fitts's Law
+
+**Replacement:** physical separation (move destructive into an overflow menu), visual
+separation (destructive uses `signal-out` colour), confirmation step (a typed
+"DELETE" or a double-click for irreversibles).
+
+---
+
+## 13. Free-Text Field That Should Be an Enum / Picker
+
+**Smell:** a date or category field is a free `<input>`, accepting anything the user types.
+
+**Heuristic:** #5 Error Prevention, Postel's Law
+
+**Replacement:** a `<DatePicker>` or `<Combobox>` that constrains values. If you must
+accept free text (e.g. tags), normalize on blur and offer an autocomplete based on
+existing values.
+
+---
+
+## 14. No Keyboard Shortcuts on a Power-User Surface
+
+**Smell:** a list view that an operator uses 100 times a day requires mouse for everything.
+
+**Heuristic:** #7 Flexibility & Efficiency, Hick's Law
+
+**Replacement:** add at minimum:
+
+- `j/k` or arrow keys to move selection
+- `Enter` to open
+- `Esc` to close / deselect
+- `Cmd+A` to select all
+- `Cmd+K` for command palette / search
+- `?` to show a shortcut overlay
+
+Document them in a `?` overlay (recognition over recall).
+
+---
+
+## 15. "Stacked" Status Indicators That Don't Compose
+
+**Smell:** the row has icons / dots / chips for AI, link, error, processing — and they're
+all rendered inline, fighting for the same horizontal slot, no clear semantic ordering.
+
+**Heuristic:** #8 Minimalist, #4 Consistency
+
+**Replacement:** define a status priority and render *one primary chip per row* (the most
+urgent state) plus a small cluster of *micro-chips* for orthogonal facts (AI marker, lock,
+favourite). Group like with like; don't randomly intersperse.
+
+---
+
+## How to Use This File
+
+1. When the agent finds a smell on a page, search this file for the closest match.
+2. Apply the replacement pattern, adapting tokens to the project's design system.
+3. If the smell is *new* (no match), document it here as a new entry once the fix lands.
+4. Reference the entry number in the enhancement write-up so future readers can trace the
+   reasoning.