devskill 2.0.7 → 2.0.8

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

package/skills/penpot-uiux-design/references/platform-guidelines.md

@@ -0,0 +1,367 @@
+# Platform Design Guidelines Reference
+
+## Mobile Design Fundamentals
+
+### Screen Sizes
+
+| Device | Size | Design At |
+| ------ | ---- | --------- |
+| iPhone SE | 375×667 | Small mobile |
+| iPhone 14/15 | 390×844 | Standard mobile |
+| iPhone 14 Pro Max | 430×932 | Large mobile |
+| Android small | 360×640 | Minimum target |
+| Android large | 412×915 | Large Android |
+
+### Safe Areas
+
+```text
+┌─────────────────────────────────┐
+│ ▓▓▓▓▓▓▓ Status Bar ▓▓▓▓▓▓▓▓▓▓ │ 44-47px
+├─────────────────────────────────┤
+│                                 │
+│      Safe Content Area          │
+│                                 │
+│                                 │
+├─────────────────────────────────┤
+│ ▓▓▓▓▓▓ Home Indicator ▓▓▓▓▓▓▓ │ 34px
+└─────────────────────────────────┘
+
+```
+
+### Touch Targets
+
+- **Minimum:** 44×44pt (iOS) / 48×48dp (Android)
+- **Recommended:** 48×48px for all platforms
+- **Spacing:** Minimum 8px between targets
+
+---
+
+## iOS Human Interface Guidelines (HIG)
+
+### Design Philosophy
+
+- **Clarity:** Text is legible, icons precise, adornments subtle
+- **Deference:** UI helps people understand content, never competes
+- **Depth:** Distinct visual layers convey hierarchy
+
+### Navigation Patterns
+
+| Pattern | When to Use |
+| ------- | ----------- |
+| Tab Bar | 3-5 top-level destinations |
+| Navigation Bar | Hierarchical content |
+| Sidebar | iPad, rich content apps |
+| Search | Content discovery |
+
+### Tab Bar Specifications
+
+```text
+┌─────────────────────────────────┐
+│  🏠    🔍    ➕    💬    👤    │
+│ Home  Search Add  Chat  Profile │ 49pt height
+└─────────────────────────────────┘
+
+```
+
+- Max 5 tabs
+- Icons 25×25pt with 10pt labels
+- Active tab uses fill/tint color
+- Inactive tabs use gray
+
+### Navigation Bar
+
+```text
+┌─────────────────────────────────┐
+│ ‹ Back    Page Title    Action │ 44pt minimum
+└─────────────────────────────────┘
+
+```
+
+- Left: Back button or cancel
+- Center: Title
+- Right: Primary action (text or icon)
+
+### Typography (SF Pro)
+
+| Style | Size | Weight |
+| ----- | ---- | ------ |
+| Large Title | 34pt | Bold |
+| Title 1 | 28pt | Bold |
+| Title 2 | 22pt | Bold |
+| Title 3 | 20pt | Semibold |
+| Headline | 17pt | Semibold |
+| Body | 17pt | Regular |
+| Callout | 16pt | Regular |
+| Subhead | 15pt | Regular |
+| Footnote | 13pt | Regular |
+| Caption | 12pt | Regular |
+
+### iOS Colors (System)
+
+| Color | Light | Dark |
+| ----- | ----- | ---- |
+| Label | #000000 | #FFFFFF |
+| Secondary Label | #3C3C43 @ 60% | #EBEBF5 @ 60% |
+| Tertiary Label | #3C3C43 @ 30% | #EBEBF5 @ 30% |
+| System Blue | #007AFF | #0A84FF |
+| System Green | #34C759 | #30D158 |
+| System Red | #FF3B30 | #FF453A |
+| System Orange | #FF9500 | #FF9F0A |
+
+### iOS-Specific Patterns
+
+- **Swipe gestures:** Delete, archive, actions
+- **Pull to refresh:** Standard list refresh
+- **Long press:** Context menus
+- **Haptic feedback:** Confirm actions
+- **Edge swipe:** Back navigation
+
+---
+
+## Android Material Design
+
+### Android Design Philosophy
+
+- **Material as metaphor:** Physical properties, elevation
+- **Bold, graphic, intentional:** Deliberate color, typography, space
+- **Motion provides meaning:** Feedback and continuity
+
+### Android Navigation Patterns
+
+| Pattern | When to Use |
+| ------- | ----------- |
+| Bottom Navigation | 3-5 top destinations |
+| Navigation Drawer | 5+ destinations, less frequent |
+| Navigation Rail | Tablet landscape |
+| Tabs | Related content groups |
+
+### Bottom Navigation
+
+```text
+┌─────────────────────────────────┐
+│  🏠    🔍    📷    💬    👤    │
+│ Home  Search Camera Chat Account│ 80dp height
+└─────────────────────────────────┘
+
+```
+
+- 3-5 destinations
+- Icons 24dp with 12sp labels
+- Active: filled icon + primary color
+- Inactive: outlined icon + on-surface
+
+### App Bar
+
+```text
+┌─────────────────────────────────┐
+│ ≡  App Title                🔍 │ 64dp height
+└─────────────────────────────────┘
+
+```
+
+- Left: Navigation icon (menu or back)
+- Center: Title (can be left-aligned)
+- Right: Action icons (max 3)
+
+### Floating Action Button (FAB)
+
+- **Size:** 56dp standard, 40dp mini
+- **Position:** Bottom right, 16dp from edges
+- **Purpose:** Primary action only
+- **Behavior:** Can hide on scroll
+
+### Typography (Roboto)
+
+| Style | Size | Weight | Tracking |
+| ----- | ---- | ------ | -------- |
+| Display Large | 57sp | Regular | -0.25 |
+| Display Medium | 45sp | Regular | 0 |
+| Display Small | 36sp | Regular | 0 |
+| Headline Large | 32sp | Regular | 0 |
+| Headline Medium | 28sp | Regular | 0 |
+| Headline Small | 24sp | Regular | 0 |
+| Title Large | 22sp | Regular | 0 |
+| Title Medium | 16sp | Medium | 0.15 |
+| Title Small | 14sp | Medium | 0.1 |
+| Body Large | 16sp | Regular | 0.5 |
+| Body Medium | 14sp | Regular | 0.25 |
+| Body Small | 12sp | Regular | 0.4 |
+| Label Large | 14sp | Medium | 0.1 |
+| Label Medium | 12sp | Medium | 0.5 |
+| Label Small | 11sp | Medium | 0.5 |
+
+### Material Colors
+
+| Role | Purpose |
+| ---- | ------- |
+| Primary | Main brand color |
+| On Primary | Text/icons on primary |
+| Primary Container | Filled buttons, active states |
+| Secondary | Less prominent components |
+| Tertiary | Contrast, balance |
+| Error | Error states |
+| Surface | Card backgrounds |
+| On Surface | Text on surfaces |
+| Outline | Borders, dividers |
+
+### Elevation (Shadows)
+
+| Level | Elevation | Use Case |
+| ----- | --------- | -------- |
+| 0 | 0dp | Flat surfaces |
+| 1 | 1dp | Cards, raised buttons |
+| 2 | 3dp | Elevated cards |
+| 3 | 6dp | FAB resting |
+| 4 | 8dp | Dialogs, pickers |
+| 5 | 12dp | FAB pressed |
+
+### Android-Specific Patterns
+
+- **Snackbar:** Brief feedback at bottom
+- **Bottom sheet:** Additional content/actions
+- **Chips:** Filter, input, choice, action
+- **Speed dial FAB:** Multiple related actions
+
+---
+
+## Responsive Web Design
+
+### Breakpoints
+
+| Name | Width | Typical Device |
+| ---- | ----- | -------------- |
+| xs | <576px | Mobile portrait |
+| sm | 576-767px | Mobile landscape |
+| md | 768-991px | Tablet |
+| lg | 992-1199px | Small desktop |
+| xl | 1200-1399px | Desktop |
+| xxl | ≥1400px | Large desktop |
+
+### Grid System
+
+- **Columns:** 12-column grid standard
+- **Gutters:** 16-24px between columns
+- **Margins:** 16px (mobile) to 64px (desktop)
+- **Max content width:** 1200-1440px
+
+### Responsive Typography
+
+```text
+Mobile (base):
+  Body: 16px
+  H1: 28-32px
+  H2: 22-24px
+  
+Tablet:
+  Body: 16px
+  H1: 32-40px
+  H2: 24-28px
+  
+Desktop:
+  Body: 16-18px
+  H1: 40-56px
+  H2: 28-36px
+
+```
+
+### Mobile-First Approach
+
+1. Design for smallest screen first
+2. Add complexity for larger screens
+3. Content priority: What's essential?
+4. Performance: Minimize for mobile
+5. Touch-first interactions
+
+### Responsive Patterns
+
+| Pattern | Description |
+| ------- | ----------- |
+| Stack | Columns become rows on mobile |
+| Reflow | Content reorders based on priority |
+| Reveal | More content shown at larger sizes |
+| Off-canvas | Navigation slides in on mobile |
+| Scale | Elements scale proportionally |
+
+---
+
+## Desktop Applications
+
+### Window Chrome
+
+```text
+┌─────────────────────────────────────────┐
+│ ● ● ●   App Title              ─ □ ×  │ Title bar
+├────────┬────────────────────────────────┤
+│ Sidebar│ Content Area                   │
+│        │                                │
+│        │                                │
+│        │                                │
+│        ├────────────────────────────────┤
+│        │ Status Bar                     │
+└────────┴────────────────────────────────┘
+
+```
+
+### Keyboard-First Design
+
+- All actions accessible via keyboard
+- Visible keyboard shortcuts
+- Focus management for tab order
+- Search/command palette (Cmd/Ctrl+K)
+
+### Hover States
+
+Desktop has hover (mobile doesn't):
+
+- Show additional info on hover
+- Preview actions before click
+- Tooltips for icon-only buttons
+- Dropdown menus on hover
+
+### Dense Information
+
+Desktop allows for:
+
+- Smaller touch targets (32px min)
+- More visible information
+- Complex tables and data grids
+- Multi-column layouts
+- Side-by-side comparisons
+
+---
+
+## Cross-Platform Considerations
+
+### Shared Principles
+
+- Consistent brand identity
+- Same core user flows
+- Synchronized data/state
+- Familiar information architecture
+
+### Platform-Specific Adaptations
+
+| Aspect | iOS | Android | Web |
+| ------ | --- | ------- | --- |
+| Back | Left nav | Left or gesture | Browser back |
+| Primary action | Right nav | FAB | Top right button |
+| Lists | Swipe actions | Long press | Hover actions |
+| Menus | Action sheets | Bottom sheet | Dropdown/context |
+| Alerts | Centered modal | Centered modal | Various positions |
+
+### Design Tokens Across Platforms
+
+Create platform-agnostic tokens:
+
+```text
+// Spacing
+spacing-sm: 8
+spacing-md: 16
+spacing-lg: 24
+
+// These map to platform units
+iOS: points (pt)
+Android: density-independent pixels (dp)
+Web: pixels (px) or rem
+
+```