@musashishao/agent-kit 1.7.0 → 1.8.1

package/.agent/skills/web-interface-guidelines/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: web-interface-guidelines
+description: Web Interface Guidelines audit for accessibility, forms, touch, animation, and anti-patterns. Use when reviewing UI code, checking accessibility, or auditing design. Based on Vercel's 100+ rules.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Web Interface Guidelines
+
+> Audit UI code for compliance with modern web interface best practices.
+> Based on [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines).
+
+---
+
+## 🎯 When to Apply
+
+| Trigger Phrase | Action |
+|----------------|--------|
+| "Review my UI" | Full audit |
+| "Check accessibility" | Focus, forms, aria |
+| "Audit design" | All categories |
+| "Check my site" | Anti-patterns scan |
+
+---
+
+## 📚 Modular Files
+
+Read ONLY the sections relevant to your task:
+
+| File | Categories |
+|------|-----------|
+| [forms.md](forms.md) | Input, autocomplete, validation |
+| [focus-states.md](focus-states.md) | Focus, keyboard navigation |
+| [touch-interaction.md](touch-interaction.md) | Mobile, touch, safe areas |
+| [animation.md](animation.md) | Motion, transitions |
+| [anti-patterns.md](anti-patterns.md) | ❌ What NOT to do |
+
+---
+
+## Quick Reference
+
+### Accessibility (A11y)
+
+| Rule | Check |
+|------|-------|
+| Visible focus | `focus-visible:ring-*` present |
+| No outline:none | Unless replacement exists |
+| Button for actions | Not `<div onClick>` |
+| Labels on inputs | `<label>` or `aria-label` |
+| Icon buttons | Has `aria-label` |
+
+### Forms
+
+| Rule | Check |
+|------|-------|
+| autocomplete | Present on inputs |
+| Correct type | `email`, `tel`, `url` |
+| No paste block | Never `onPaste preventDefault` |
+| Error placement | Inline next to field |
+
+### Animation
+
+| Rule | Check |
+|------|-------|
+| Reduced motion | `prefers-reduced-motion` honored |
+| Compositor only | `transform`, `opacity` only |
+| No `transition: all` | List properties explicitly |
+
+### Touch & Mobile
+
+| Rule | Check |
+|------|-------|
+| Touch action | `touch-action: manipulation` |
+| Safe areas | `env(safe-area-inset-*)` |
+| Scroll contain | `overscroll-behavior: contain` in modals |
+
+---
+
+## Output Format
+
+When auditing, output findings in this format:
+
+```
+filename:line - [CATEGORY] Description of issue
+```
+
+Example:
+```
+components/Button.tsx:15 - [FOCUS] Missing focus-visible ring
+pages/login.tsx:42 - [FORMS] Input missing autocomplete attribute
+```
+
+---
+
+> **Remember:** Run anti-patterns check first for quick wins.

package/.agent/skills/web-interface-guidelines/animation.md

@@ -0,0 +1,153 @@
+# Animation Guidelines
+
+> Respect user preferences. Animate only what's necessary.
+
+---
+
+## Reduced Motion
+
+**Honor `prefers-reduced-motion`.**
+
+```css
+/* ✅ Default animation */
+.card {
+  transition: transform 200ms ease;
+}
+
+/* ✅ Reduce or disable for preference */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+}
+```
+
+In Tailwind:
+```html
+<div class="motion-safe:animate-bounce motion-reduce:animate-none">
+```
+
+---
+
+## Compositor-Friendly Properties
+
+**Animate only `transform` and `opacity`.**
+
+| ✅ Animate | ❌ Avoid |
+|-----------|---------|
+| `transform` | `width`, `height` |
+| `opacity` | `top`, `left` |
+| `filter` | `margin`, `padding` |
+| | `border-width` |
+
+```css
+/* ✅ GOOD: GPU-accelerated */
+.card:hover {
+  transform: translateY(-4px);
+  opacity: 0.9;
+}
+
+/* ❌ BAD: Triggers layout */
+.card:hover {
+  margin-top: -4px;
+  height: 104px;
+}
+```
+
+---
+
+## Explicit Transitions
+
+**Never use `transition: all`.**
+
+```css
+/* ❌ BAD: Animates everything */
+button {
+  transition: all 200ms;
+}
+
+/* ✅ GOOD: Explicit properties */
+button {
+  transition: background-color 200ms, transform 150ms;
+}
+```
+
+---
+
+## Transform Origin
+
+**Set correct origin for expected behavior.**
+
+```css
+/* ✅ Scale from center (default) */
+.modal {
+  transform-origin: center;
+}
+
+/* ✅ Dropdown from top */
+.dropdown {
+  transform-origin: top;
+}
+
+/* ✅ Menu from corner */
+.context-menu {
+  transform-origin: top left;
+}
+```
+
+---
+
+## SVG Animation
+
+**Animate wrapper div, not SVG element.**
+
+```tsx
+// ✅ GOOD: Animate wrapper
+<div className="animate-spin">
+  <SpinnerSVG />
+</div>
+
+// ❌ BAD: Animate SVG directly (inconsistent behavior)
+<SpinnerSVG className="animate-spin" />
+```
+
+For SVG transforms:
+```css
+.svg-icon {
+  transform-box: fill-box;
+  transform-origin: center;
+}
+```
+
+---
+
+## Interruptible Animations
+
+**Animations should respond to user input.**
+
+```css
+/* ✅ Allow interruption */
+.drawer {
+  transition: transform 300ms ease-out;
+  will-change: transform;
+}
+
+/* User can swipe to close mid-animation */
+```
+
+Avoid:
+- Long animations (>500ms) without skip
+- Animations that block interaction
+- Auto-play that can't be paused
+
+---
+
+## Quick Checklist
+
+| Check | Pass |
+|-------|------|
+| `prefers-reduced-motion` respected? | |
+| Only `transform`/`opacity` animated? | |
+| No `transition: all`? | |
+| Correct `transform-origin`? | |
+| SVG wrapped for animation? | |

package/.agent/skills/web-interface-guidelines/anti-patterns.md

@@ -0,0 +1,204 @@
+# Anti-Patterns (FLAG THESE)
+
+> Explicit list of violations to flag during UI audits.
+
+---
+
+## ❌ Accessibility Violations
+
+### Zoom Blocking
+```html
+<!-- ❌ FLAG: Disables zoom -->
+<meta name="viewport" content="user-scalable=no">
+<meta name="viewport" content="maximum-scale=1">
+
+<!-- ✅ CORRECT -->
+<meta name="viewport" content="width=device-width, initial-scale=1">
+```
+
+### Outline Removal Without Replacement
+```css
+/* ❌ FLAG */
+button:focus {
+  outline: none;
+}
+
+/* ✅ CORRECT */
+button:focus-visible {
+  outline: 2px solid var(--focus);
+}
+```
+
+### Missing Labels
+```tsx
+// ❌ FLAG: Input without label
+<input type="email" />
+
+// ❌ FLAG: Icon button without aria-label
+<button><IconMenu /></button>
+
+// ✅ CORRECT
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+<button aria-label="Open menu"><IconMenu /></button>
+```
+
+---
+
+## ❌ Semantic Violations
+
+### Wrong Element for Interaction
+```tsx
+// ❌ FLAG: Div with click handler
+<div onClick={handleClick}>Click me</div>
+<span onClick={handleClick}>Action</span>
+
+// ✅ CORRECT
+<button onClick={handleClick}>Click me</button>
+```
+
+### Inline Navigation Without Link
+```tsx
+// ❌ FLAG: onClick navigation
+<button onClick={() => router.push('/dashboard')}>
+  Dashboard
+</button>
+
+// ✅ CORRECT
+<Link href="/dashboard">Dashboard</Link>
+```
+
+---
+
+## ❌ Form Violations
+
+### Paste Blocking
+```tsx
+// ❌ FLAG: Blocks paste
+<input onPaste={e => e.preventDefault()} />
+<input onPaste={() => false} />
+
+// ✅ CORRECT: Allow paste always
+<input type="password" />
+```
+
+### Missing Autocomplete
+```tsx
+// ❌ FLAG: No autocomplete on auth fields
+<input type="email" name="email" />
+
+// ✅ CORRECT
+<input type="email" name="email" autoComplete="email" />
+```
+
+---
+
+## ❌ Animation Violations
+
+### Transition All
+```css
+/* ❌ FLAG */
+.button {
+  transition: all 200ms;
+}
+
+/* ✅ CORRECT */
+.button {
+  transition: background-color 200ms, transform 150ms;
+}
+```
+
+### Layout Property Animation
+```css
+/* ❌ FLAG: Animates layout properties */
+.card {
+  transition: width 200ms, height 200ms, margin 200ms;
+}
+
+/* ✅ CORRECT: Transform only */
+.card {
+  transition: transform 200ms;
+}
+```
+
+---
+
+## ❌ Performance Violations
+
+### Large List Without Virtualization
+```tsx
+// ❌ FLAG: 50+ items without virtualization
+{items.map(item => <Item key={item.id} {...item} />)}
+// items.length > 50
+
+// ✅ CORRECT: Use virtualization
+import { Virtualizer } from '@tanstack/virtual-core';
+```
+
+### Images Without Dimensions
+```tsx
+// ❌ FLAG: No width/height
+<img src="/photo.jpg" />
+
+// ✅ CORRECT
+<img src="/photo.jpg" width={800} height={600} alt="Description" />
+```
+
+### Hardcoded Date/Number Formats
+```tsx
+// ❌ FLAG
+const date = `${d.getMonth()}/${d.getDate()}/${d.getFullYear()}`;
+const price = `$${amount.toFixed(2)}`;
+
+// ✅ CORRECT
+const date = new Intl.DateTimeFormat('en-US').format(d);
+const price = new Intl.NumberFormat('en-US', { 
+  style: 'currency', 
+  currency: 'USD' 
+}).format(amount);
+```
+
+---
+
+## ❌ Mobile Violations
+
+### AutoFocus on Mobile
+```tsx
+// ❌ FLAG: AutoFocus without mobile check
+<input autoFocus />
+
+// ✅ CORRECT
+<input autoFocus={!isMobile} />
+```
+
+### Missing Safe Areas
+```css
+/* ❌ FLAG: Full-bleed without safe areas */
+.full-width {
+  padding: 0;
+}
+
+/* ✅ CORRECT */
+.full-width {
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+```
+
+---
+
+## Audit Checklist
+
+| Category | Check | Severity |
+|----------|-------|----------|
+| Zoom | No `user-scalable=no` | 🔴 Critical |
+| Focus | Visible focus states | 🔴 Critical |
+| Labels | All inputs labeled | 🔴 Critical |
+| Semantics | `<button>` for actions | 🟠 High |
+| Links | `<Link>` for navigation | 🟠 High |
+| Paste | Never blocked | 🟠 High |
+| Transition | No `transition: all` | 🟡 Medium |
+| Images | Has dimensions | 🟡 Medium |
+| Lists | Virtualized if 50+ | 🟡 Medium |
+| Dates | Uses `Intl.*` | 🟢 Low |

package/.agent/skills/web-interface-guidelines/focus-states.md

@@ -0,0 +1,104 @@
+# Focus States Guidelines
+
+> Keyboard users rely on visible focus. Never hide it without replacement.
+
+---
+
+## Visible Focus
+
+**Interactive elements need visible focus.**
+
+```css
+/* ✅ Focus-visible (keyboard only) */
+button:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+
+/* ❌ Never do this without replacement */
+button:focus {
+  outline: none;
+}
+```
+
+| Tailwind | CSS |
+|----------|-----|
+| `focus-visible:ring-2` | `outline: 2px solid` |
+| `focus-visible:ring-offset-2` | `outline-offset: 2px` |
+| `focus-visible:ring-blue-500` | Custom color |
+
+---
+
+## Focus-Visible vs Focus
+
+**Use `:focus-visible` over `:focus`.**
+
+| Selector | When Applied |
+|----------|--------------|
+| `:focus` | Always on focus (keyboard + click) |
+| `:focus-visible` | Only on keyboard focus |
+
+```css
+/* ✅ Only shows ring on keyboard navigation */
+button:focus-visible {
+  ring: 2px;
+}
+
+/* ❌ Shows ring on every click too */
+button:focus {
+  ring: 2px;
+}
+```
+
+---
+
+## Focus-Within
+
+**Group focus with `:focus-within` for compound controls.**
+
+```css
+/* ✅ Highlight container when any child is focused */
+.search-box:focus-within {
+  border-color: var(--focus);
+  box-shadow: 0 0 0 3px var(--focus-ring);
+}
+```
+
+Use cases:
+- Search box with button
+- Input groups
+- Custom selects
+- Dropdown menus
+
+---
+
+## Tab Order
+
+| Rule | Check |
+|------|-------|
+| Logical order | Tab follows visual layout |
+| No positive tabindex | Use `tabindex="0"` or `-1` only |
+| Skip links | Provide "Skip to content" |
+| Focus trapping | Modal keeps focus inside |
+
+```tsx
+// ✅ Focusable div (rare cases)
+<div tabIndex={0} role="button" onKeyDown={handleKey}>
+  Custom control
+</div>
+
+// ❌ Avoid
+<div tabIndex={5}> // Breaks natural order
+```
+
+---
+
+## Quick Audit
+
+| Check | Pass/Fail |
+|-------|-----------|
+| Can tab through all interactive elements? | |
+| Focus ring visible on each? | |
+| No orphaned focus (hidden elements)? | |
+| Modal traps focus? | |
+| Escape closes modal? | |

package/.agent/skills/web-interface-guidelines/forms.md

@@ -0,0 +1,154 @@
+# Forms Guidelines
+
+> Form inputs are critical for user experience and security.
+
+---
+
+## Autocomplete
+
+**Inputs need `autocomplete` and meaningful `name`.**
+
+```tsx
+// ✅ GOOD
+<input 
+  type="email"
+  name="email"
+  autoComplete="email"
+/>
+
+// ❌ BAD
+<input type="text" /> // No type, no autocomplete
+```
+
+| Field | autocomplete Value |
+|-------|-------------------|
+| Email | `email` |
+| Password | `current-password` or `new-password` |
+| Name | `name` |
+| Phone | `tel` |
+| Address | `street-address` |
+| Credit Card | `cc-number` |
+
+---
+
+## Input Types
+
+**Use correct `type` and `inputmode`.**
+
+| Data | type | inputmode |
+|------|------|-----------|
+| Email | `email` | `email` |
+| Phone | `tel` | `tel` |
+| URL | `url` | `url` |
+| Number | `number` | `numeric` |
+| Search | `search` | `search` |
+| OTP/Code | `text` | `numeric` |
+
+---
+
+## Never Block Paste
+
+```tsx
+// ❌ NEVER DO THIS
+<input 
+  onPaste={e => e.preventDefault()} // Blocks password managers!
+/>
+
+// ✅ Always allow paste
+<input type="password" />
+```
+
+---
+
+## Labels
+
+**Labels must be clickable.**
+
+```tsx
+// ✅ Using htmlFor
+<label htmlFor="email">Email</label>
+<input id="email" />
+
+// ✅ Wrapping
+<label>
+  Email
+  <input />
+</label>
+
+// ❌ No association
+<span>Email</span>
+<input />
+```
+
+---
+
+## Error Handling
+
+| Rule | Implementation |
+|------|----------------|
+| Inline errors | Next to field, not just top of form |
+| Focus first error | On submit, focus the first invalid field |
+| Clear on fix | Remove error when user starts typing |
+| Specific messages | "Email is invalid" not "Error" |
+
+```tsx
+// ✅ Inline error
+<input aria-invalid={!!error} aria-describedby="email-error" />
+{error && <span id="email-error">{error}</span>}
+```
+
+---
+
+## Submit Button
+
+| State | Button |
+|-------|--------|
+| Idle | Enabled, shows action |
+| Submitting | Shows spinner, may disable |
+| Error | Returns to idle |
+| Success | Shows confirmation |
+
+```tsx
+<button disabled={isSubmitting}>
+  {isSubmitting ? <Spinner /> : 'Submit'}
+</button>
+```
+
+---
+
+## Spellcheck
+
+**Disable on non-prose fields.**
+
+```tsx
+<input 
+  type="email"
+  spellCheck={false}  // ✅ No squiggly lines on emails
+  autoComplete="off"   // ✅ No password manager on non-auth
+/>
+```
+
+| Disable spellcheck | Keep spellcheck |
+|-------------------|-----------------|
+| Email, username | Comments, bio |
+| Codes, tokens | Messages |
+| URLs | Search queries |
+
+---
+
+## Unsaved Changes Warning
+
+**Warn before navigation with unsaved changes.**
+
+```tsx
+useEffect(() => {
+  const handleBeforeUnload = (e: BeforeUnloadEvent) => {
+    if (isDirty) {
+      e.preventDefault();
+      e.returnValue = '';
+    }
+  };
+  window.addEventListener('beforeunload', handleBeforeUnload);
+  return () => window.removeEventListener('beforeunload', handleBeforeUnload);
+}, [isDirty]);
+```