mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-24 04:15:14 +00:00
Add penpot-uiux-design skill
Adds a comprehensive UI/UX design skill for the Penpot MCP server. Features: - MCP tool reference (execute_code, export_shape, import_image, penpot_api_info) - Design system discovery and handling - Board positioning to avoid overlap - Default design tokens (spacing, typography, colors) - Component checklists (buttons, forms, navigation) - Accessibility guidelines (WCAG compliance) - Platform specifications (iOS, Android, responsive web)
This commit is contained in:
Jcardif
329
skills/penpot-uiux-design/references/accessibility.md
Normal file
329
skills/penpot-uiux-design/references/accessibility.md
Normal file
@@ -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>
|
||||
|
||||
```
|
||||
339
skills/penpot-uiux-design/references/component-patterns.md
Normal file
339
skills/penpot-uiux-design/references/component-patterns.md
Normal file
@@ -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
|
||||
367
skills/penpot-uiux-design/references/platform-guidelines.md
Normal file
367
skills/penpot-uiux-design/references/platform-guidelines.md
Normal file
@@ -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
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user