npm - @kood/claude-code - Versions diffs - 0.4.1 → 0.5.0 - Mend

@kood/claude-code 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

package/templates/.claude/skills/global-uiux-design/references/accessibility.md ADDED Viewed

@@ -0,0 +1,401 @@
+# Accessibility (WCAG 2.2 AA)
+## Core Requirements
+### 1. Perceivable
+**Information must be presentable to users in ways they can perceive.**
+#### Text Alternatives (1.1)
+```tsx
+{/* Images */}
+<img src="chart.png" alt="Sales increased 25% in Q4" />
+{/* Decorative images */}
+<img src="decoration.png" alt="" role="presentation" />
+{/* Icon buttons */}
+<button aria-label="Close dialog">
+  <svg className="w-5 h-5" aria-hidden="true" />
+</button>
+```
+#### Color Contrast (1.4.3)
+- **Normal text:** 4.5:1 minimum
+- **Large text (18pt+):** 3:1 minimum
+- **UI components:** 3:1 minimum (borders, form controls)
+#### Resize Text (1.4.4)
+```tsx
+{/* Support up to 200% zoom */}
+<p className="text-base leading-relaxed">
+  Use relative units (rem, em) not px
+</p>
+```
+### 2. Operable
+**UI components must be operable.**
+#### Keyboard Accessible (2.1)
+```tsx
+{/* All interactive elements keyboard accessible */}
+<button onClick={handleClick}>Submit</button>  {/* ✓ */}
+<div onClick={handleClick}>Submit</div>  {/* ✗ Not keyboard accessible */}
+{/* Custom interactive elements need tabIndex and keyboard handlers */}
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      handleClick();
+    }
+  }}
+>
+  Custom button
+</div>
+```
+#### Focus Visible (2.4.7)
+```tsx
+{/* Ensure visible focus indicator */}
+<button className="
+  focus:outline-none
+  focus:ring-2
+  focus:ring-primary-500
+  focus:ring-offset-2
+">
+  Save
+</button>
+```
+#### Skip Links (2.4.1)
+```tsx
+{/* Allow keyboard users to skip navigation */}
+<a
+  href="#main-content"
+  className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4"
+>
+  Skip to main content
+</a>
+<main id="main-content">
+  {/* Page content */}
+</main>
+```
+### 3. Understandable
+**Information and operation must be understandable.**
+#### Language (3.1.1)
+```html
+<html lang="en">
+  <body>
+    <p>This is English text.</p>
+    <p lang="es">Este es texto en español.</p>
+  </body>
+</html>
+```
+#### Error Identification (3.3.1)
+```tsx
+{/* Clear error messages */}
+<div>
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={hasError}
+    aria-describedby={hasError ? "email-error" : undefined}
+  />
+  {hasError && (
+    <p id="email-error" className="text-red-600 text-sm mt-1">
+      Please enter a valid email address (e.g., name@example.com)
+    </p>
+  )}
+</div>
+```
+#### Labels (3.3.2)
+```tsx
+{/* Every form input needs a label */}
+<label htmlFor="username" className="block text-sm font-medium">
+  Username
+</label>
+<input id="username" type="text" />
+{/* Or use aria-label */}
+<input type="search" aria-label="Search products" />
+```
+### 4. Robust
+**Content must be robust enough for assistive technologies.**
+#### Valid HTML (4.1.1)
+- Proper nesting (no `<div>` inside `<p>`)
+- Unique IDs
+- Closing tags
+- Valid ARIA attributes
+#### Name, Role, Value (4.1.2)
+```tsx
+{/* Use semantic HTML when possible */}
+<button>Click me</button>  {/* ✓ Role implicit */}
+{/* Custom components need explicit roles */}
+<div role="button" aria-pressed={isPressed}>
+  Toggle
+</div>
+```
+## ARIA (Accessible Rich Internet Applications)
+### ARIA Roles
+```tsx
+{/* Landmark roles */}
+<header role="banner">
+<nav role="navigation">
+<main role="main">
+<aside role="complementary">
+<footer role="contentinfo">
+{/* Widget roles */}
+<div role="dialog" aria-modal="true">
+<div role="alertdialog">
+<div role="tooltip">
+<div role="tablist">
+  <button role="tab" aria-selected={true}>Tab 1</button>
+</div>
+```
+### ARIA States & Properties
+```tsx
+{/* aria-expanded (dropdowns, accordions) */}
+<button aria-expanded={isOpen} onClick={toggle}>
+  Menu
+</button>
+{/* aria-hidden (decorative elements) */}
+<svg aria-hidden="true" />
+{/* aria-live (dynamic content) */}
+<div role="status" aria-live="polite">
+  {notification}
+</div>
+{/* aria-describedby (additional descriptions) */}
+<input
+  type="password"
+  aria-describedby="password-requirements"
+/>
+<p id="password-requirements">
+  Must be at least 8 characters
+</p>
+```
+### ARIA Best Practices
+**First Rule of ARIA:**
+> If you can use native HTML, do it.
+❌ **Bad:**
+```tsx
+<div role="button" tabIndex={0} onClick={click}>Submit</div>
+```
+✅ **Good:**
+```tsx
+<button onClick={click}>Submit</button>
+```
+## Common Patterns
+### Modal Dialog
+```tsx
+<div
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-description"
+>
+  <h2 id="dialog-title">Confirm deletion</h2>
+  <p id="dialog-description">
+    Are you sure you want to delete this item? This action cannot be undone.
+  </p>
+  <button onClick={confirm}>Delete</button>
+  <button onClick={cancel}>Cancel</button>
+</div>
+```
+**Requirements:**
+- Focus trap (Tab cycles within dialog)
+- Close on Escape key
+- Return focus to trigger element on close
+- Prevent body scroll
+### Accordion
+```tsx
+<div>
+  <button
+    aria-expanded={isOpen}
+    aria-controls="panel-1"
+    onClick={toggle}
+  >
+    Section 1
+  </button>
+  <div id="panel-1" hidden={!isOpen}>
+    Panel content
+  </div>
+</div>
+```
+### Tabs
+```tsx
+<div role="tablist" aria-label="Settings">
+  <button
+    role="tab"
+    aria-selected={activeTab === 'general'}
+    aria-controls="panel-general"
+  >
+    General
+  </button>
+  <button
+    role="tab"
+    aria-selected={activeTab === 'privacy'}
+    aria-controls="panel-privacy"
+  >
+    Privacy
+  </button>
+</div>
+<div role="tabpanel" id="panel-general" hidden={activeTab !== 'general'}>
+  General settings
+</div>
+```
+**Keyboard:**
+- Arrow keys navigate between tabs
+- Tab key moves to panel content
+- Home/End jump to first/last tab
+### Toast Notifications
+```tsx
+{/* Non-interruptive notifications */}
+<div
+  role="status"
+  aria-live="polite"
+  className="fixed bottom-4 right-4"
+>
+  <div className="bg-green-50 border border-green-200 p-4 rounded-lg">
+    <p>Changes saved successfully</p>
+  </div>
+</div>
+{/* Urgent alerts */}
+<div
+  role="alert"
+  aria-live="assertive"
+>
+  <p>Error: Payment failed</p>
+</div>
+```
+## Screen Reader Testing
+### macOS VoiceOver
+1. Enable: System Settings → Accessibility → VoiceOver
+2. Toggle: Cmd + F5
+3. Navigate: VO + Arrow keys (VO = Ctrl + Option)
+4. Interact: VO + Shift + Down
+5. Rotor: VO + U (lists headings, links, form controls)
+### Windows NVDA (Free)
+1. Download: nvaccess.org
+2. Toggle: Ctrl + Alt + N
+3. Navigate: Arrow keys
+4. Elements list: Insert + F7
+### Mobile
+- **iOS VoiceOver:** Settings → Accessibility → VoiceOver
+- **Android TalkBack:** Settings → Accessibility → TalkBack
+## Testing Tools
+### Automated
+- **axe DevTools** (Chrome/Firefox extension)
+- **Lighthouse** (Chrome DevTools → Lighthouse)
+- **WAVE** (wave.webaim.org)
+- **Pa11y** (CLI tool)
+### Manual
+- **Keyboard only:** Unplug mouse, navigate entire app
+- **Screen reader:** VoiceOver (Mac), NVDA (Windows), TalkBack (Android)
+- **Zoom:** Test at 200% browser zoom
+- **Color blind:** Chrome DevTools → Rendering → Emulate vision deficiencies
+## Legal Requirements
+### Regions with Accessibility Laws
+- **US:** ADA, Section 508 (government sites)
+- **EU:** European Accessibility Act (June 2025)
+- **UK:** Equality Act 2010
+- **Canada:** AODA (Ontario)
+- **Australia:** Disability Discrimination Act
+### Compliance Level
+- **A:** Minimum (many gaps)
+- **AA:** Target for most (legal requirement in many regions)
+- **AAA:** Gold standard (difficult to achieve fully)
+**Recommendation:** WCAG 2.2 AA minimum for all public-facing sites.
+## Quick Accessibility Checklist
+- [ ] All images have alt text (or alt="" if decorative)
+- [ ] Color contrast meets 4.5:1 (normal text) or 3:1 (large text, UI)
+- [ ] All interactive elements keyboard accessible
+- [ ] Focus indicators visible (not outline: none without replacement)
+- [ ] Form inputs have labels
+- [ ] Headings in logical order (h1 → h2 → h3, no skipping)
+- [ ] Link text descriptive (not "click here")
+- [ ] Videos have captions
+- [ ] Page has valid lang attribute
+- [ ] Zoom to 200% doesn't break layout
+- [ ] Screen reader announces page changes
+- [ ] Error messages clear and actionable
+## Resources
+- **WCAG 2.2:** w3.org/WAI/WCAG22/quickref
+- **WAI-ARIA Authoring Practices:** w3.org/WAI/ARIA/apg
+- **WebAIM:** webaim.org (articles, checklists)
+- **A11y Project:** a11yproject.com (beginner-friendly)
+- **Inclusive Components:** inclusive-components.design

package/templates/.claude/skills/global-uiux-design/references/color-system.md ADDED Viewed

@@ -0,0 +1,275 @@
+# Color System
+## Palette Structure
+### Base Palette (9-shade scale)
+```tsx
+// Example: Primary color
+const primary = {
+  50:  '#EFF6FF',  // Lightest background
+  100: '#DBEAFE',
+  200: '#BFDBFE',
+  300: '#93C5FD',
+  400: '#60A5FA',
+  500: '#3B82F6',  // Base
+  600: '#2563EB',  // Default button
+  700: '#1D4ED8',  // Hover state
+  800: '#1E40AF',
+  900: '#1E3A8A',  // Darkest text
+}
+```
+### Semantic Colors
+| Color | Usage | Example |
+|-------|-------|---------|
+| **Success** | Completed actions, positive feedback | green-600 |
+| **Error** | Failed actions, validation errors | red-600 |
+| **Warning** | Caution, reversible actions | amber-600 |
+| **Info** | Neutral information, tips | blue-600 |
+```tsx
+{/* Semantic usage */}
+<div className="text-green-600">Payment successful</div>
+<div className="text-red-600">Invalid email address</div>
+<div className="text-amber-600">Unsaved changes</div>
+<div className="text-blue-600">Tip: Press Cmd+K to search</div>
+```
+## Contrast Requirements (WCAG 2.2 AA)
+### Text Contrast
+| Type | Minimum | Recommended |
+|------|---------|-------------|
+| Normal text (<18pt) | 4.5:1 | 7:1 (AAA) |
+| Large text (≥18pt) | 3:1 | 4.5:1 (AAA) |
+| UI components | 3:1 | 4.5:1 |
+### Testing Tools
+- Chrome DevTools (Lighthouse)
+- WebAIM Contrast Checker
+- Stark (Figma plugin)
+- Contrast Ratio (leaverou.github.io/contrast-ratio)
+### Common Mistakes
+❌ **Gray text on white**
+```tsx
+{/* Bad: Only 2.5:1 contrast */}
+<p className="text-gray-400">Secondary text</p>
+```
+✅ **Darker gray**
+```tsx
+{/* Good: 7:1 contrast */}
+<p className="text-gray-600">Secondary text</p>
+```
+## Dark Mode
+### Approach
+**System preference:**
+```tsx
+// Tailwind config
+module.exports = {
+  darkMode: 'media', // or 'class' for manual toggle
+}
+```
+**Usage:**
+```tsx
+<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
+  Content
+</div>
+```
+### Dark Mode Palette Adjustments
+**Don't just invert:**
+- Pure black (#000) is too harsh → Use gray-900 (#111827)
+- Pure white (#FFF) is too bright → Use gray-100 (#F3F4F6)
+- Reduce saturation of colors in dark mode
+- Increase contrast slightly (dark mode often viewed in dim lighting)
+**Example:**
+```tsx
+const primary = {
+  // Light mode: vibrant
+  light: '#2563EB', // blue-600
+  // Dark mode: slightly desaturated
+  dark: '#60A5FA',  // blue-400 (lighter shade, less saturated)
+}
+```
+### Elevation in Dark Mode
+**Light mode:** Use shadows
+**Dark mode:** Use lighter backgrounds
+```tsx
+<div className="
+  bg-white shadow-lg
+  dark:bg-gray-800 dark:shadow-none dark:ring-1 dark:ring-gray-700
+">
+  Card content
+</div>
+```
+## Color Harmony
+### 60-30-10 Rule
+- **60%** Dominant (background, neutral)
+- **30%** Secondary (supporting elements)
+- **10%** Accent (CTA, highlights)
+```tsx
+{/* Example: Dashboard */}
+<div className="bg-gray-50">  {/* 60% - neutral background */}
+  <aside className="bg-white">  {/* 30% - secondary surface */}
+    <button className="bg-blue-600">  {/* 10% - accent CTA */}
+      Create
+    </button>
+  </aside>
+</div>
+```
+### Analogous Colors
+Use adjacent colors on color wheel for harmony:
+- Blue (600) + Cyan (600) + Teal (600)
+### Complementary Colors
+Use opposite colors for high contrast:
+- Blue (600) + Orange (600)
+- Use sparingly for important CTAs
+## Brand Color Integration
+### Extract brand color palette
+```tsx
+// Brand primary: #FF6B35 (custom orange)
+// Generate shades using tools:
+// - uicolors.app
+// - tailwindshades.com
+// - palettte.app
+const brand = {
+  50:  '#FFF4F0',
+  100: '#FFE8DF',
+  200: '#FFCFBF',
+  300: '#FFB49F',
+  400: '#FF9A7F',
+  500: '#FF6B35',  // Brand color
+  600: '#E64D1A',
+  700: '#B33A13',
+  800: '#80290D',
+  900: '#4D1808',
+}
+```
+### Usage in Components
+```tsx
+// Replace default blue with brand color
+<button className="bg-brand-500 hover:bg-brand-600 text-white">
+  Brand CTA
+</button>
+// Keep semantic colors standard
+<div className="text-green-600">Success message</div>
+<div className="text-red-600">Error message</div>
+```
+## Design System Color Approaches
+### Material Design 3 - Dynamic Color
+- Generate palette from single source color
+- Adapts to user's wallpaper (Android 12+)
+- Tools: Material Theme Builder
+### Apple HIG - System Colors
+- Semantic colors (systemBlue, systemRed)
+- Automatically adapt to light/dark mode
+- Respect accessibility settings (increase contrast)
+### IBM Carbon - Color Tokens
+- Descriptive tokens (interactive-01, ui-background)
+- Theme-agnostic (same token works across themes)
+- Design → Dev handoff uses token names
+## Color Blindness Considerations
+### Types
+- **Deuteranopia** (most common, 5% of males): Red-green
+- **Protanopia**: Red-green
+- **Tritanopia** (rare): Blue-yellow
+### Design Strategies
+✅ **Use patterns + color**
+```tsx
+{/* Good: Icon + color differentiates */}
+<div className="text-green-600">✓ Success</div>
+<div className="text-red-600">✗ Error</div>
+```
+✅ **Use high contrast**
+- Avoid red-green combinations
+- Use blue-orange instead
+✅ **Test with simulators**
+- Figma: Color Blind plugin
+- Chrome: DevTools → Rendering → Emulate vision deficiencies
+## Performance Considerations
+### CSS Custom Properties
+```css
+:root {
+  --color-primary: #3B82F6;
+  --color-primary-hover: #2563EB;
+}
+.dark {
+  --color-primary: #60A5FA;
+  --color-primary-hover: #3B82F6;
+}
+```
+**Benefits:**
+- Runtime theme switching
+- No CSS recompilation
+- Smaller bundle (one color token, multiple values)
+### Avoid Inline Styles
+❌ **Bad:** (each instance is unique CSS)
+```tsx
+<div style={{color: '#3B82F6'}}>Text</div>
+```
+✅ **Good:** (reusable class)
+```tsx
+<div className="text-primary-500">Text</div>
+```
+## Accessibility Tools
+- **WebAIM Contrast Checker**: webaim.org/resources/contrastchecker
+- **Colorable**: colorable.jxnblk.com
+- **Who Can Use**: whocanuse.com
+- **Contrast Triangle**: contrast-triangle.com