devskill 2.0.6 → 2.0.8

package/skills/penpot-uiux-design/references/accessibility.md

@@ -0,0 +1,329 @@
+# Accessibility Guidelines Reference (WCAG)
+
+## Quick Compliance Checklist
+
+### Level AA Requirements (Minimum Standard)
+
+- [ ] Color contrast 4.5:1 for normal text
+- [ ] Color contrast 3:1 for large text (18px+ or 14px bold)
+- [ ] Touch targets minimum 44×44px
+- [ ] All functionality available via keyboard
+- [ ] Visible focus indicators
+- [ ] No content flashes more than 3 times/second
+- [ ] Page has descriptive title
+- [ ] Link purpose clear from text
+- [ ] Form inputs have labels
+- [ ] Error messages are descriptive
+
+---
+
+## Color and Contrast
+
+### Contrast Ratios
+
+| Element | Minimum Ratio | Enhanced (AAA) |
+| ------- | ------------- | -------------- |
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+) | 3:1 | 4.5:1 |
+| UI components | 3:1 | - |
+| Graphical objects | 3:1 | - |
+
+### Color Independence
+
+Never use color as the only means of conveying information:
+
+```text
+✗ Error fields shown only in red
+✓ Error fields with red border + error icon + text message
+
+✗ Required fields marked only with red asterisk
+✓ Required fields labeled "(required)" or with icon + tooltip
+
+✗ Status shown only by color dots
+✓ Status with color + icon + label text
+
+```
+
+### Accessible Color Combinations
+
+**Safe text colors on backgrounds:**
+
+| Background | Text Color | Contrast |
+| ---------- | ---------- | -------- |
+| White (#FFFFFF) | Dark gray (#1F2937) | 15.5:1 ✓ |
+| Light gray (#F3F4F6) | Dark gray (#374151) | 10.9:1 ✓ |
+| Primary blue (#2563EB) | White (#FFFFFF) | 4.6:1 ✓ |
+| Dark (#111827) | White (#FFFFFF) | 18.1:1 ✓ |
+
+**Colors to avoid for text:**
+
+- Yellow on white (insufficient contrast)
+- Light gray on white
+- Orange on white (marginal at best)
+
+---
+
+## Keyboard Navigation
+
+### Requirements
+
+1. **All interactive elements** must be reachable via Tab key
+2. **Logical tab order** following visual layout
+3. **No keyboard traps** (user can always Tab away)
+4. **Focus visible** at all times during keyboard navigation
+5. **Skip links** to bypass repetitive navigation
+
+### Focus Indicators
+
+```css
+/* Example focus styles */
+:focus {
+  outline: 2px solid #2563EB;
+  outline-offset: 2px;
+}
+
+:focus:not(:focus-visible) {
+  outline: none; /* Hide for mouse users */
+}
+
+:focus-visible {
+  outline: 2px solid #2563EB;
+  outline-offset: 2px;
+}
+
+```
+
+### Keyboard Shortcuts
+
+| Key | Expected Behavior |
+| --- | ----------------- |
+| Tab | Move to next interactive element |
+| Shift+Tab | Move to previous element |
+| Enter | Activate button/link |
+| Space | Activate button, toggle checkbox |
+| Escape | Close modal/dropdown |
+| Arrow keys | Navigate within components |
+
+---
+
+## Screen Reader Support
+
+### Semantic HTML Elements
+
+Use appropriate elements for their purpose:
+
+| Purpose | Element | Not This |
+| ------- | ------- | -------- |
+| Navigation | `<nav>` | `<div class="nav">` |
+| Main content | `<main>` | `<div id="main">` |
+| Header | `<header>` | `<div class="header">` |
+| Footer | `<footer>` | `<div class="footer">` |
+| Button | `<button>` | `<div onclick>` |
+| Link | `<a href>` | `<span onclick>` |
+
+### Heading Hierarchy
+
+```text
+h1 - Page Title (one per page)
+  h2 - Major Section
+    h3 - Subsection
+      h4 - Sub-subsection
+    h3 - Another Subsection
+  h2 - Another Major Section
+
+```
+
+**Never skip levels** (h1 → h3 without h2)
+
+### Image Alt Text
+
+```text
+Decorative: alt="" (empty, not omitted)
+Informative: alt="Description of what image shows"
+Functional: alt="Action the image performs"
+Complex: alt="Brief description" + detailed description nearby
+
+```
+
+**Alt text examples:**
+
+```text
+✓ alt="Bar chart showing sales growth from $10M to $15M in Q4"
+✓ alt="Company logo"
+✓ alt="" (for decorative background pattern)
+
+✗ alt="image" or alt="photo"
+✗ alt="img_12345.jpg"
+✗ Missing alt attribute entirely
+
+```
+
+---
+
+## Touch and Pointer
+
+### Touch Target Sizes
+
+| Platform | Minimum | Recommended |
+| -------- | ------- | ----------- |
+| WCAG 2.1 | 44×44px | 48×48px |
+| iOS (Apple) | 44×44pt | - |
+| Android | 48×48dp | - |
+
+### Touch Target Spacing
+
+- Minimum 8px between adjacent targets
+- Prefer 16px+ for comfort
+- Larger targets for primary actions
+
+### Pointer Gestures
+
+- Complex gestures must have single-pointer alternatives
+- Drag operations need equivalent click actions
+- Avoid hover-only functionality on touch devices
+
+---
+
+## Forms Accessibility
+
+### Labels
+
+Every input must have an associated label:
+
+```text
+<label for="email">Email Address</label>
+<input type="email" id="email" name="email">
+
+```
+
+### Required Fields
+
+```text
+<!-- Announce to screen readers -->
+<label for="name">
+  Name <span aria-label="required">*</span>
+</label>
+<input type="text" id="name" required aria-required="true">
+
+```
+
+### Error Handling
+
+```text
+<label for="email">Email</label>
+<input type="email" id="email" aria-invalid="true" aria-describedby="email-error">
+<span id="email-error" role="alert">
+  Please enter a valid email address
+</span>
+
+```
+
+### Form Instructions
+
+- Provide format hints before input
+- Show password requirements before errors
+- Group related fields with fieldset/legend
+
+---
+
+## Dynamic Content
+
+### Live Regions
+
+For content that updates dynamically:
+
+```text
+aria-live="polite" - Announce when convenient
+aria-live="assertive" - Announce immediately (interrupts)
+role="alert" - Urgent messages (like assertive)
+role="status" - Status updates (like polite)
+
+```
+
+### Loading States
+
+```text
+<button aria-busy="true" aria-live="polite">
+  <span class="spinner"></span>
+  Loading...
+</button>
+
+```
+
+### Modal Dialogs
+
+- Focus moves into modal when opened
+- Focus trapped within modal
+- Escape key closes modal
+- Focus returns to trigger element when closed
+
+---
+
+## Testing Accessibility
+
+### Manual Testing Checklist
+
+1. **Keyboard only:** Navigate entire page with Tab/Enter
+2. **Screen reader:** Test with VoiceOver (Mac) or NVDA (Windows)
+3. **Zoom 200%:** Content remains readable and usable
+4. **High contrast:** Test with system high contrast mode
+5. **No mouse:** Complete all tasks without pointing device
+
+### Automated Tools
+
+- axe DevTools (browser extension)
+- WAVE (WebAIM browser extension)
+- Lighthouse (Chrome DevTools)
+- Color contrast checkers (WebAIM, Contrast Ratio)
+
+### Common Issues to Check
+
+- [ ] Missing or empty alt text
+- [ ] Empty links or buttons
+- [ ] Missing form labels
+- [ ] Insufficient color contrast
+- [ ] Missing language attribute
+- [ ] Incorrect heading structure
+- [ ] Missing skip navigation link
+- [ ] Inaccessible custom widgets
+
+---
+
+## ARIA Quick Reference
+
+### Roles
+
+| Role | Purpose |
+| ---- | ------- |
+| `button` | Clickable button |
+| `link` | Navigation link |
+| `dialog` | Modal dialog |
+| `alert` | Important message |
+| `navigation` | Navigation region |
+| `main` | Main content |
+| `search` | Search functionality |
+| `tab/tablist/tabpanel` | Tab interface |
+
+### Properties
+
+| Property | Purpose |
+| -------- | ------- |
+| `aria-label` | Accessible name |
+| `aria-labelledby` | Reference to labeling element |
+| `aria-describedby` | Reference to description |
+| `aria-hidden` | Hide from assistive tech |
+| `aria-expanded` | Expandable state |
+| `aria-selected` | Selection state |
+| `aria-disabled` | Disabled state |
+| `aria-required` | Required field |
+| `aria-invalid` | Invalid input |
+
+### Golden Rule
+
+**First rule of ARIA:** Don't use ARIA if native HTML works.
+
+```text
+✗ <div role="button" tabindex="0">Click</div>
+✓ <button>Click</button>
+
+```

package/skills/penpot-uiux-design/references/component-patterns.md

@@ -0,0 +1,339 @@
+# UI Component Patterns Reference
+
+## Buttons
+
+### Button Types
+
+| Type | Purpose | Visual Treatment |
+| ---- | ------- | ---------------- |
+| Primary | Main action on page | Solid fill, brand color |
+| Secondary | Supporting actions | Outline or muted fill |
+| Tertiary | Low-emphasis actions | Text-only, underline optional |
+| Destructive | Delete/remove actions | Red color, confirmation required |
+| Ghost | Minimal UI, icon buttons | Transparent, subtle hover |
+
+### Button States
+
+```text
+Default    → Resting state, clearly interactive
+Hover      → Cursor over (desktop): darken 10%, subtle shadow
+Active     → Being pressed: darken 20%, slight scale down
+Focus      → Keyboard selected: visible outline ring
+Disabled   → Not available: 50% opacity, cursor: not-allowed
+Loading    → Processing: spinner replaces or accompanies label
+
+```
+
+### Button Specifications
+
+- **Minimum size:** 44×44px (touch target)
+- **Padding:** 12-16px horizontal, 8-12px vertical
+- **Border radius:** 4-8px (consistent across app)
+- **Font weight:** Medium or Semibold (600-700)
+- **Text:** Sentence case, 2-4 words max
+
+### Button Label Patterns
+
+```text
+✓ Save Changes        ✗ Submit
+✓ Add to Cart         ✗ Click Here
+✓ Create Account      ✗ OK
+✓ Download PDF        ✗ Go
+✓ Start Free Trial    ✗ Continue
+
+```
+
+---
+
+## Forms
+
+### Form Layout Guidelines
+
+- **Single column preferred:** Reduces cognitive load
+- **Top-aligned labels:** Fastest completion times
+- **Logical grouping:** Related fields together
+- **Smart defaults:** Pre-fill when possible
+
+### Input Field Anatomy
+
+```text
+┌─ Label (required) ─────────────────────────┐
+│                                            │
+│  ┌────────────────────────────────────┐   │
+│  │ Placeholder text...                 │   │
+│  └────────────────────────────────────┘   │
+│  Helper text or error message              │
+└────────────────────────────────────────────┘
+
+```
+
+### Input States
+
+| State | Border | Background | Additional |
+| ----- | ------ | ---------- | ---------- |
+| Default | Gray (#D1D5DB) | White | - |
+| Focus | Primary color | White | Shadow/glow |
+| Filled | Gray | White | Checkmark optional |
+| Error | Red (#EF4444) | Light red tint | Error icon + message |
+| Disabled | Light gray | Gray (#F3F4F6) | 50% opacity text |
+
+### Validation Timing
+
+- **On blur:** Validate when user leaves field
+- **On change (after error):** Clear error as user types correct input
+- **On submit:** Final validation before processing
+- **Never on focus:** Don't show errors before user types
+
+### Error Message Guidelines
+
+```text
+✓ "Email address is required"
+✓ "Password must be at least 8 characters"
+✓ "Please enter a valid phone number (e.g., 555-123-4567)"
+
+✗ "Invalid input"
+✗ "Error"
+✗ "This field is required" (generic)
+
+```
+
+### Form Best Practices
+
+- Mark optional fields, not required (fewer asterisks)
+- Show password requirements before errors occur
+- Use input masks for formatted data (phone, date)
+- Preserve data on errors (don't clear the form)
+- Provide clear success confirmation
+
+---
+
+## Navigation
+
+### Navigation Patterns
+
+#### Top Navigation Bar
+
+```text
+┌─────────────────────────────────────────────────────┐
+│ Logo    Nav Item  Nav Item  Nav Item    [Search] [User] │
+└─────────────────────────────────────────────────────┘
+
+```
+
+- **Best for:** Marketing sites, simple apps
+- **Max items:** 5-7 top-level links
+- **Mobile:** Collapse to hamburger menu
+
+#### Sidebar Navigation
+
+```text
+┌────────┬────────────────────────────────┐
+│ Logo   │ Content Area                   │
+├────────┤                                │
+│ Nav 1  │                                │
+│ Nav 2  │                                │
+│ Nav 3  │                                │
+│        │                                │
+│ ────── │                                │
+│ Nav 4  │                                │
+│ Nav 5  │                                │
+└────────┴────────────────────────────────┘
+
+```
+
+- **Best for:** Dashboards, complex apps
+- **Width:** 200-280px expanded, 64px collapsed
+- **Mobile:** Overlay drawer
+
+#### Bottom Navigation (Mobile)
+
+```text
+┌─────────────────────────────────────┐
+│           Content Area              │
+│                                     │
+├─────────────────────────────────────┤
+│  🏠    🔍    ➕    💬    👤        │
+│ Home  Search Add  Chat  Profile     │
+└─────────────────────────────────────┘
+
+```
+
+- **Max items:** 3-5 destinations
+- **Best for:** Primary app sections
+- **Always visible:** Persistent navigation
+
+#### Breadcrumbs
+
+```text
+Home > Products > Electronics > Headphones
+
+```
+
+- **Use for:** Deep hierarchies (3+ levels)
+- **Current page:** Not clickable, different style
+- **Separator:** > or / or chevron icon
+
+### Tab Navigation
+
+```text
+┌─────────┬─────────┬─────────┬─────────┐
+│ Tab 1   │ Tab 2   │ Tab 3   │ Tab 4   │
+└─────────┴─────────┴─────────┴─────────┘
+│                                       │
+│        Tab Content Area               │
+│                                       │
+└───────────────────────────────────────┘
+
+```
+
+- **Max tabs:** 3-5 for clarity
+- **Active indicator:** Underline or background
+- **Use for:** Related content within same page
+
+---
+
+## Cards
+
+### Card Anatomy
+
+```text
+┌─────────────────────────────────┐
+│ ░░░░░░░ Image/Media ░░░░░░░░░░ │
+├─────────────────────────────────┤
+│ Category Label                  │
+│ Card Title                      │
+│ Description text that may       │
+│ span multiple lines...          │
+│                                 │
+│ [Action Button]  [Secondary]    │
+└─────────────────────────────────┘
+
+```
+
+### Card Guidelines
+
+- **Consistent sizing:** Use grid, equal heights
+- **Content hierarchy:** Image → Title → Description → Actions
+- **Padding:** 16-24px internal spacing
+- **Border radius:** 8-12px (matching buttons)
+- **Shadow:** Subtle elevation (0 2px 4px rgba(0,0,0,0.1))
+
+---
+
+## Modals and Dialogs
+
+### Modal Structure
+
+```text
+┌─────────────────────────────────────┐
+│ Modal Title                    [×]  │
+├─────────────────────────────────────┤
+│                                     │
+│ Modal content goes here.            │
+│ Keep it focused on one task.        │
+│                                     │
+├─────────────────────────────────────┤
+│           [Cancel]  [Confirm]       │
+└─────────────────────────────────────┘
+
+```
+
+### Modal Guidelines
+
+- **Size:** 400-600px width (desktop), full-width minus margins (mobile)
+- **Overlay:** Semi-transparent dark background (rgba(0,0,0,0.5))
+- **Close options:** X button, overlay click, Escape key
+- **Focus trap:** Keep keyboard focus within modal
+- **Primary action:** Right-aligned, visually prominent
+
+---
+
+## Dashboards
+
+### Dashboard Layout Principles
+
+1. **Most important metrics at top:** KPIs, summary cards
+2. **Progressive detail:** Overview → Drill-down capability
+3. **Consistent card sizes:** Use grid system
+4. **Minimal chartjunk:** Only data-serving visuals
+5. **Actionable insights:** Highlight anomalies
+
+### Data Visualization Selection
+
+| Data Type | Chart Type |
+| --------- | ---------- |
+| Comparison across categories | Bar chart |
+| Trend over time | Line chart |
+| Part of whole | Pie (≤5 slices) or Donut |
+| Distribution | Histogram |
+| Correlation | Scatter plot |
+| Geographic | Map |
+| Single metric | Big number + sparkline |
+
+### Dashboard Best Practices
+
+- **Limit to 5-9 widgets** per view
+- **Align to grid:** Consistent gutters and sizing
+- **Filter controls:** Top or sidebar, always visible
+- **Date range selector:** Common need, make prominent
+- **Export options:** PDF, CSV for data tables
+- **Responsive:** Stack cards on smaller screens
+
+---
+
+## Empty States
+
+### Empty State Components
+
+```text
+┌─────────────────────────────────────┐
+│                                     │
+│         [Illustration/Icon]         │
+│                                     │
+│      No projects yet                │
+│                                     │
+│   Create your first project to      │
+│   start organizing your work.       │
+│                                     │
+│       [Create Project]              │
+│                                     │
+└─────────────────────────────────────┘
+
+```
+
+### Empty State Guidelines
+
+- **Friendly illustration:** Not just "No data"
+- **Explain value:** Why create something?
+- **Clear CTA:** Primary action to fix empty state
+- **Keep it brief:** 1-2 sentences max
+
+---
+
+## Loading States
+
+### Loading Patterns
+
+| Duration | Pattern |
+| -------- | ------- |
+| <1 second | No indicator (feels instant) |
+| 1-3 seconds | Spinner or progress indicator |
+| 3-10 seconds | Skeleton screens + progress |
+| >10 seconds | Progress bar + explanation |
+
+### Skeleton Screen
+
+```text
+┌─────────────────────────────────────┐
+│ ░░░░░░░░░░░░ ░░░░░░░░░░           │
+├─────────────────────────────────────┤
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░         │
+│ ░░░░░░░░░░░░░░░░░░░               │
+│ ░░░░░░░░░░░░░░░░░░░░░░░           │
+└─────────────────────────────────────┘
+
+```
+
+- Match layout of loaded content
+- Use subtle animation (shimmer/pulse)
+- Show actual content structure