skills/maddiedreese_figma
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit with translated description

Browse Source
This commit is contained in:
zlei9
2026-03-29 13:02:21 +08:00
commit 8efab1561a
12 changed files with 3787 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

352
references/accessibility-guidelines.md Normal file
View File

@@ -0,0 +1,352 @@
# Accessibility Guidelines for Figma Design
Comprehensive WCAG compliance guide and accessibility best practices for inclusive design.
## WCAG 2.1 Compliance Levels
### Level A (Minimum)
Basic web accessibility features that should be present in all designs.
### Level AA (Standard)
Recommended level for most websites and applications. Removes major barriers to accessing content.
### Level AAA (Enhanced)
Highest level, required for specialized contexts but not recommended as general policy.
**Focus on AA compliance** - this covers the vast majority of accessibility needs without excessive constraints.
## Color and Visual Accessibility
### Color Contrast Requirements
#### WCAG AA Standards
- **Normal text**: 4.5:1 contrast ratio minimum
- **Large text** (18pt+ or 14pt+ bold): 3:1 contrast ratio minimum
- **UI components**: 3:1 contrast ratio for borders, icons, form controls
- **Graphics**: 3:1 contrast ratio for meaningful graphics
#### WCAG AAA Standards (Enhanced)
- **Normal text**: 7:1 contrast ratio
- **Large text**: 4.5:1 contrast ratio
#### Testing Tools in Figma
- **Stark plugin**: Real-time contrast checking
- **Color Oracle**: Color blindness simulation
- **WebAIM contrast checker**: External validation
### Color Usage Guidelines
#### Don't Rely on Color Alone
```
❌ Bad: "Click the green button to continue"
✅ Good: "Click the 'Continue' button (green) to proceed"
```
- Use icons, text labels, or patterns alongside color
- Ensure information is conveyed through multiple visual cues
- Test designs in grayscale to verify information accessibility
#### Color Blindness Considerations
- **Red-green color blindness** affects ~8% of men, ~0.5% of women
- **Blue-yellow color blindness** is less common but still significant
- Use tools like Colorblinding or Stark to test your designs
- Consider using shapes, patterns, or positions as additional indicators
### Typography Accessibility
#### Font Size Guidelines
- **Minimum body text**: 16px (12pt) for web
- **Minimum mobile text**: 16px (prevents zoom on iOS)
- **Large text threshold**: 18pt (24px) regular, 14pt (18.7px) bold
- **Line height**: 1.5x font size minimum for body text
- **Paragraph spacing**: At least 1.5x line height
#### Font Choice
- **Sans-serif fonts** generally more readable on screens
- **Avoid decorative fonts** for body text
- **System fonts** ensure consistency and performance
- **Web-safe fonts** for broader compatibility
#### Text Layout
- **Line length**: 45-75 characters for optimal readability
- **Left alignment** for left-to-right languages
- **Adequate spacing** between letters, words, lines, paragraphs
- **Avoid justified text** which can create awkward spacing
## Interactive Element Accessibility
### Touch and Click Targets
#### Size Requirements
- **Minimum size**: 44x44px (iOS/Material Design standard)
- **Recommended size**: 48x48px for better usability
- **Spacing**: At least 8px between adjacent targets
- **Mobile considerations**: Thumb-friendly zones, easy reach
#### Visual Feedback
- **Hover states**: Clear indication of interactive elements
- **Active states**: Immediate feedback on interaction
- **Disabled states**: Clearly distinguish non-functional elements
- **Loading states**: Show progress for time-consuming actions
### Focus Management
#### Focus Indicators
- **Visible focus**: Clear outline or background change
- **High contrast**: Focus indicator must have 3:1 contrast ratio
- **Consistent style**: Same focus treatment across the interface
- **Never remove focus indicators** without providing alternative
#### Focus Order
- **Logical sequence**: Follow visual layout and reading order
- **Tab navigation**: All interactive elements reachable via keyboard
- **Skip links**: Allow bypassing repetitive navigation
- **Focus traps**: Keep focus within modals/dialogs when open
### Form Accessibility
#### Label Requirements
- **All inputs must have labels**: Use explicit labels, not just placeholders
- **Required field indicators**: Clear marking of mandatory fields
- **Group related fields**: Use fieldsets and legends for grouped inputs
- **Help text**: Provide guidance when needed
#### Error Handling
```
❌ Bad: Red border with no explanation
✅ Good: "Email address is required" with clear visual indicator
```
- **Specific error messages**: Explain what's wrong and how to fix it
- **Error summaries**: List all errors at top of form for screen readers
- **Inline validation**: Real-time feedback where helpful
- **Success confirmation**: Confirm successful form submissions
#### Form Layout
- **Single column layouts**: Easier to navigate and complete
- **Logical grouping**: Related fields grouped together
- **Progress indicators**: Show steps in multi-step forms
- **Clear submission**: Make it obvious how to submit the form
## Content Structure and Navigation
### Heading Hierarchy
#### Proper Heading Structure
```html
H1 - Page title (one per page)
├── H2 - Main sections
│ ├── H3 - Subsections
│ │ └── H4 - Sub-subsections
│ └── H3 - Another subsection
└── H2 - Another main section
```
- **Don't skip levels**: H1 → H2 → H3, never H1 → H3
- **Use headings for structure**: Not just for visual styling
- **One H1 per page**: Primary page title only
### Link Accessibility
#### Link Text Guidelines
```
❌ Bad: "Click here for more information"
✅ Good: "Read our complete accessibility guide"
```
- **Descriptive link text**: Explains where the link leads
- **Context independence**: Should make sense when read alone
- **Unique link text**: Different destinations need different text
- **External link indicators**: Show when links lead off-site
### Navigation Patterns
#### Skip Links
- **Skip to main content**: Bypass repetitive navigation
- **Skip to search**: Quick access to search functionality
- **Keyboard users**: Essential for efficient navigation
- **Hidden until focused**: Don't clutter visual design
#### Breadcrumbs
- **Show location**: Help users understand where they are
- **Provide navigation**: Easy way to move up the hierarchy
- **Current page**: Don't make current page a link
- **Separator clarity**: Use > or / with proper ARIA labels
## Images and Media
### Image Accessibility
#### Alt Text Guidelines
- **Decorative images**: Use empty alt attribute (alt="")
- **Informative images**: Describe the information conveyed
- **Functional images**: Describe the action/function
- **Complex images**: Provide detailed description nearby
#### Alt Text Examples
```
❌ Bad: alt="image"
❌ Bad: alt="photo.jpg"
✅ Good: alt="Bar chart showing 40% increase in sales"
✅ Good: alt="Submit form" (for submit button image)
✅ Good: alt="" (for purely decorative images)
```
### Video and Audio
#### Video Accessibility
- **Captions**: For all spoken content
- **Audio descriptions**: For visual content not described in audio
- **Transcript**: Full text version of audio content
- **Player controls**: Accessible play/pause/volume controls
#### Audio Accessibility
- **Transcripts**: For all audio content
- **Auto-play restrictions**: Avoid auto-playing audio
- **Volume controls**: User control over audio levels
- **Visual indicators**: Show when audio is playing
## Mobile Accessibility
### Touch Interface Guidelines
#### Gesture Support
- **Single-tap primary**: Main interaction method
- **Alternative access**: Provide alternatives to complex gestures
- **Gesture hints**: Teach users about available gestures
- **Gesture conflicts**: Avoid conflicts with system gestures
#### Mobile-Specific Considerations
- **Orientation support**: Work in both portrait and landscape
- **Zoom support**: Allow pinch-to-zoom for text content
- **Motion sensitivity**: Respect reduced motion preferences
- **One-handed use**: Design for thumb navigation
### Screen Reader Support
#### iOS VoiceOver
- **Element labeling**: Provide clear, descriptive labels
- **Navigation order**: Logical focus sequence
- **Custom actions**: Define available actions for elements
- **Notifications**: Use announcements for dynamic changes
#### Android TalkBack
- **Content descriptions**: Equivalent to alt text for UI elements
- **Clickable indicators**: Mark interactive elements properly
- **Live regions**: Announce dynamic content changes
- **Semantic markup**: Use proper HTML/accessibility semantics
## Testing and Validation
### Automated Testing Tools
#### Figma Plugins
- **Stark**: Comprehensive accessibility checker
- **Color Blind Web Page Filter**: Color blindness simulation
- **Able**: Color contrast and font size checker
- **A11y - Color Contrast Checker**: Quick contrast validation
#### External Tools
- **WebAIM WAVE**: Web accessibility evaluation
- **axe DevTools**: Automated accessibility testing
- **Lighthouse**: Google's accessibility auditing
- **Pa11y**: Command-line accessibility testing
### Manual Testing Methods
#### Keyboard Testing
1. **Tab navigation**: Can you reach all interactive elements?
2. **Enter/Space activation**: Do buttons and links work?
3. **Arrow key navigation**: Works in menus and lists?
4. **Escape key**: Closes modals and menus?
#### Screen Reader Testing
1. **VoiceOver** (Mac): System Preferences → Accessibility → VoiceOver
2. **NVDA** (Windows): Free screen reader for testing
3. **JAWS** (Windows): Professional screen reader
4. **TalkBack** (Android): Built-in Android screen reader
#### Visual Testing
1. **Zoom to 200%**: Content should remain usable
2. **Grayscale mode**: Information still accessible?
3. **High contrast mode**: Text and UI still visible?
4. **Color blindness simulation**: Information still clear?
### User Testing
#### Include Users with Disabilities
- **Recruit diverse participants**: Different disabilities and assistive technologies
- **Test with real users**: Automated tools can't catch everything
- **Observe natural usage**: Don't guide too much during testing
- **Iterate based on feedback**: Accessibility is an ongoing process
#### Testing Scenarios
- **First-time usage**: Can new users complete key tasks?
- **Error recovery**: What happens when things go wrong?
- **Complex workflows**: Multi-step processes accessible?
- **Different contexts**: Various devices, environments, capabilities
## Implementation Guidelines
### Designer Handoff
#### Accessibility Annotations
- **Alt text specifications**: Document all image alt text
- **Focus order notes**: Specify tab sequence where non-obvious
- **Heading levels**: Mark proper heading hierarchy
- **Color contrast values**: Include specific contrast ratios
- **Interactive states**: Document all hover/focus/active states
#### Component Documentation
- **Accessibility features**: Built-in accessibility considerations
- **Usage guidelines**: When and how to use accessibly
- **ARIA patterns**: Required ARIA attributes and roles
- **Keyboard interactions**: Expected keyboard behavior
### Design System Integration
#### Accessible Components
- **Design once, use everywhere**: Build accessibility into components
- **Default accessibility**: Make accessible the easy choice
- **Clear documentation**: Accessibility requirements in design system
- **Regular audits**: Review and update component accessibility
#### Style Guidelines
- **Color palettes**: Pre-tested for contrast ratios
- **Typography scales**: Meet minimum size requirements
- **Spacing systems**: Ensure adequate touch targets
- **Icon libraries**: Include alt text recommendations
## Legal and Compliance
### Relevant Laws and Standards
#### United States
- **ADA** (Americans with Disabilities Act): Civil rights law
- **Section 508**: Federal agency accessibility requirements
- **WCAG 2.1**: Technical standard referenced by many laws
#### International
- **EN 301 549** (European Union): European accessibility standard
- **AODA** (Ontario): Accessibility for Ontarians with Disabilities Act
- **DDA** (Australia): Disability Discrimination Act
### Risk Mitigation
- **Legal compliance**: Following WCAG AA reduces legal risk
- **Documentation**: Keep records of accessibility efforts
- **Regular audits**: Ongoing compliance checking
- **User feedback**: Channels for reporting accessibility issues
## Resources and Tools
### Essential Resources
- **WCAG 2.1 Guidelines**: Official W3C accessibility standard
- **WebAIM**: Practical accessibility guidance and tools
- **A11y Project**: Community-driven accessibility resources
- **Inclusive Design Principles**: Microsoft's inclusive design guide
### Figma-Specific Resources
- **Figma Accessibility Guide**: Official Figma accessibility documentation
- **Accessible Design Systems**: Examples of accessible component libraries
- **Plugin Directory**: Accessibility-focused Figma plugins
- **Community Resources**: Accessibility templates and examples

294
references/design-patterns.md Normal file
View File

@@ -0,0 +1,294 @@
# Design Patterns & Component Best Practices
Comprehensive guide to UI patterns, component design, and design system best practices for Figma.
## Component Architecture
### Atomic Design Principles
#### Atoms (Basic Elements)
- **Buttons**: Primary, secondary, ghost, icon buttons
- **Form inputs**: Text fields, selectors, checkboxes, radio buttons
- **Typography**: Headings, body text, captions, labels
- **Icons**: Consistent icon library with standardized sizing
- **Avatars**: User profile images with fallback states
**Best Practices:**
- Use auto-layout for flexible resizing
- Create consistent hover/focus/disabled states
- Establish clear naming conventions
- Include component documentation
#### Molecules (Simple Combinations)
- **Form groups**: Label + input + validation message
- **Navigation items**: Icon + text + badge
- **Card headers**: Title + subtitle + actions
- **Search bars**: Input + search icon + clear button
**Best Practices:**
- Combine atoms logically and purposefully
- Maintain single responsibility principle
- Use component properties for variations
- Test across different content lengths
#### Organisms (Complex Combinations)
- **Navigation bars**: Logo + menu + user profile + search
- **Data tables**: Headers + rows + pagination + actions
- **Product cards**: Image + title + price + actions
- **Forms**: Multiple form groups + buttons + validation
**Best Practices:**
- Design for responsive behavior
- Consider loading and error states
- Plan for empty states and edge cases
- Optimize for accessibility
### Component Naming Conventions
#### Hierarchical Structure
```
Component Name / Variant / State
Examples:
- Button / Primary / Default
- Button / Primary / Hover
- Button / Secondary / Disabled
- Input / Text / Error
- Card / Product / Loading
```
#### Descriptive Naming
- Use descriptive, action-oriented names
- Avoid technical jargon in user-facing names
- Be consistent across similar components
- Include size/type indicators when helpful
## Layout Patterns
### Grid Systems
#### Standard Grid Configurations
- **12-column grid**: Most versatile, works for web and mobile
- **8-column grid**: Good for tablet layouts
- **4-column grid**: Mobile-friendly, simple layouts
- **Custom grids**: Match specific brand requirements
**Grid Properties:**
- Consistent gutters (16px, 20px, 24px common)
- Responsive breakpoints (320px, 768px, 1024px, 1440px)
- Maximum content width (1200px-1440px typical)
#### Auto-Layout Best Practices
- Use auto-layout for all flexible components
- Set appropriate resizing constraints
- Consider padding vs margin usage
- Test with varying content lengths
### Common Layout Patterns
#### Header Patterns
1. **Simple header**: Logo + navigation + CTA
2. **Mega menu**: Logo + dropdown navigation + search + account
3. **Mobile header**: Hamburger + logo + account/cart
4. **Dashboard header**: Breadcrumbs + title + actions
#### Content Layouts
1. **Single column**: Simple, focused content flow
2. **Two column**: Main content + sidebar
3. **Three column**: Sidebar + main + secondary sidebar
4. **Card grid**: Responsive card layouts
5. **Masonry**: Pinterest-style irregular grid
#### Footer Patterns
1. **Simple footer**: Copyright + key links
2. **Rich footer**: Multiple link columns + social + newsletter
3. **Sticky footer**: Always at bottom of viewport
4. **Fat footer**: Extensive links + contact info + sitemap
## Interface Patterns
### Navigation Patterns
#### Primary Navigation
- **Horizontal nav**: Works well for 3-7 main sections
- **Vertical sidebar**: Good for 8+ items or complex hierarchies
- **Tab navigation**: For equal-importance sections
- **Breadcrumbs**: Show hierarchy and allow backtracking
#### Secondary Navigation
- **Dropdown menus**: Organize related sub-items
- **Contextual sidebars**: Show relevant options for current content
- **Floating action buttons**: Promote primary actions
- **Bottom navigation**: Mobile-friendly for core functions
### Form Patterns
#### Form Layout
- **Single column**: Easier to scan and complete
- **Label placement**: Above fields for better readability
- **Required indicators**: Use asterisks or "(required)" text
- **Help text**: Provide when needed, but don't overdo
#### Input Patterns
- **Progressive disclosure**: Show additional fields as needed
- **Smart defaults**: Pre-fill when possible
- **Inline validation**: Real-time feedback on field completion
- **Clear error states**: Specific, actionable error messages
#### Form Actions
- **Primary/secondary buttons**: Clear visual hierarchy
- **Save states**: Show progress and confirmation
- **Cancel behavior**: Ask about unsaved changes
- **Multi-step forms**: Show progress and allow navigation
### Data Display Patterns
#### Tables
- **Sortable headers**: Allow data organization
- **Pagination**: Handle large datasets
- **Row actions**: Edit, delete, view details
- **Selection**: Bulk operations capability
- **Responsive behavior**: Stack or hide columns on mobile
#### Cards
- **Consistent structure**: Image + title + metadata + actions
- **Hover states**: Show additional information or actions
- **Loading states**: Skeleton screens or progress indicators
- **Empty states**: Helpful guidance when no content exists
#### Lists
- **Simple lists**: Basic text with optional icons
- **Rich lists**: Multiple lines of information
- **Interactive lists**: Drag-and-drop, selection
- **Infinite scroll**: Load more content seamlessly
## Responsive Design Patterns
### Breakpoint Strategy
#### Common Breakpoints
- **Mobile**: 320px - 767px
- **Tablet**: 768px - 1023px
- **Desktop**: 1024px - 1439px
- **Large desktop**: 1440px+
#### Content Strategy
- **Mobile first**: Design for constraints, enhance for larger screens
- **Progressive enhancement**: Add features as screen size allows
- **Content parity**: Ensure feature availability across devices
- **Touch targets**: Minimum 44px for mobile interactions
### Adaptive Techniques
#### Navigation Adaptation
- **Collapsible menu**: Hamburger pattern for mobile
- **Priority navigation**: Show most important items first
- **Overflow menus**: "More" option for secondary items
- **Tab bar**: Bottom navigation for mobile apps
#### Content Adaptation
- **Stacking**: Single column on mobile, multiple on desktop
- **Content reduction**: Progressive disclosure on smaller screens
- **Image scaling**: Responsive images with appropriate crops
- **Typography scaling**: Larger text on mobile for readability
## Accessibility Patterns
### Color and Contrast
- **4.5:1 contrast ratio**: Minimum for normal text (WCAG AA)
- **3:1 contrast ratio**: Minimum for large text and UI components
- **Don't rely on color alone**: Use icons, text, or patterns too
- **Color blind considerations**: Test with color vision simulators
### Interaction Patterns
- **Focus indicators**: Clear visual focus for keyboard navigation
- **Touch targets**: Minimum 44x44px for touch interfaces
- **Click/tap areas**: Generous padding around interactive elements
- **Hover states**: Clear feedback for interactive elements
### Content Patterns
- **Alt text**: Descriptive text for images and icons
- **Heading hierarchy**: Proper H1-H6 structure
- **Link text**: Descriptive, avoid "click here"
- **Form labels**: Clear, descriptive labels for all inputs
## Animation and Microinteractions
### Animation Principles
- **Purposeful motion**: Animation should serve a function
- **Consistent timing**: Use consistent easing and duration
- **Respect preferences**: Honor reduced motion preferences
- **Performance**: Smooth 60fps animations
### Common Microinteractions
- **Button feedback**: Subtle scale or color change on press
- **Loading indicators**: Skeleton screens or spinners
- **Success confirmations**: Checkmarks or brief messaging
- **Error handling**: Gentle shake or color change for errors
- **Page transitions**: Smooth movement between states
### Transition Patterns
- **Slide transitions**: Natural for sequential content
- **Fade transitions**: Good for overlays and modals
- **Scale transitions**: Effective for showing/hiding elements
- **Morphing transitions**: Transform one element into another
## Design System Organization
### File Structure
```
Design System/
├── Foundation/
│ ├── Colors
│ ├── Typography
│ ├── Spacing
│ ├── Grid
│ └── Iconography
├── Components/
│ ├── Atoms/
│ ├── Molecules/
│ └── Organisms/
├── Patterns/
│ ├── Navigation
│ ├── Forms
│ ├── Data Display
│ └── Feedback
└── Templates/
├── Landing Pages
├── Dashboard
└── Content Pages
```
### Documentation Standards
- **Component purpose**: What problem does it solve?
- **Usage guidelines**: When and how to use
- **Do's and don'ts**: Clear examples of proper usage
- **Accessibility notes**: ARIA patterns, keyboard behavior
- **Implementation notes**: Technical considerations
### Maintenance Practices
- **Regular audits**: Review and update components quarterly
- **Usage tracking**: Monitor which components are actually used
- **Feedback loops**: Collect input from designers and developers
- **Version control**: Clear versioning and change logs
- **Testing**: Validate components across different contexts
## Mobile-Specific Patterns
### Touch Interactions
- **Tap**: Primary interaction method
- **Long press**: Secondary actions, context menus
- **Swipe**: Navigation, dismissal actions
- **Pinch**: Zoom functionality
- **Pull to refresh**: Common mobile pattern
### Mobile Navigation
- **Tab bar**: 3-5 primary sections
- **Hamburger menu**: Secondary navigation
- **Segmented control**: Filter or view switching
- **Bottom sheet**: Contextual actions and options
### Mobile Content
- **Card-based layouts**: Easy to scan and interact with
- **Thumb-friendly zones**: Important actions in easy reach
- **Generous whitespace**: Improve readability and touch accuracy
- **Clear hierarchy**: Bold typography and visual separation

412
references/export-formats.md Normal file
View File

@@ -0,0 +1,412 @@
# Export Formats and Specifications
Complete guide to Figma export options, formats, and optimization strategies for different use cases.
## Supported Export Formats
### Raster Formats
#### PNG (Portable Network Graphics)
**Best for:** UI elements, icons with transparency, screenshots
**Characteristics:**
- Lossless compression
- Supports transparency
- Larger file sizes than JPG
- Perfect for designs with sharp edges
**Use cases:**
- App icons and UI elements
- Logos with transparency
- Screenshots and mockups
- Print materials requiring transparency
**Export settings:**
- Scale: 1x, 2x, 3x, 4x
- Recommended: 2x for web, 3x for mobile apps
- Transparent backgrounds supported
#### JPG (Joint Photographic Experts Group)
**Best for:** Photographs, complex images, web optimization
**Characteristics:**
- Lossy compression
- Smaller file sizes
- No transparency support
- Good for photographic content
**Use cases:**
- Hero images and photography
- Marketing materials
- Email templates
- Web banners where file size matters
**Export settings:**
- Quality levels available in some tools
- Automatic white background fill
- Scale options: 1x, 2x, 4x
#### WEBP
**Best for:** Web optimization, modern browsers
**Characteristics:**
- Superior compression to PNG/JPG
- Supports transparency and animation
- Smaller file sizes
- Not supported in all browsers
**Use cases:**
- Web assets for modern browsers
- Progressive web apps
- Performance-critical applications
### Vector Formats
#### SVG (Scalable Vector Graphics)
**Best for:** Icons, simple illustrations, scalable graphics
**Characteristics:**
- Infinitely scalable
- Small file sizes for simple graphics
- Editable code
- Supports interactive elements
**Use cases:**
- Icon libraries
- Simple illustrations
- Logos for web use
- Scalable graphics
**Export options:**
- `svg_include_id`: Include node IDs for manipulation
- `svg_simplify_stroke`: Optimize stroke paths
- Text handling: Convert to paths vs keep as text
#### PDF (Portable Document Format)
**Best for:** Print materials, presentations, documentation
**Characteristics:**
- Vector-based when possible
- High quality for print
- Preserves text and formatting
- Universal compatibility
**Use cases:**
- Print marketing materials
- Presentations
- Documentation handoff
- High-quality mockups
**Export settings:**
- Vector elements preserved when possible
- Raster elements included at appropriate resolution
- Text can remain selectable
## Export Scales and Resolutions
### Device Pixel Ratios
#### 1x (Standard Resolution)
- **Use for:** Web designs, standard monitors
- **Pixel density:** 96 DPI
- **File size:** Smallest
- **Quality:** Standard
#### 2x (High-DPI)
- **Use for:** Retina displays, high-DPI web
- **Pixel density:** 192 DPI
- **File size:** 4x larger than 1x
- **Quality:** Sharp on high-DPI screens
#### 3x (Mobile High-DPI)
- **Use for:** iPhone Plus, Android high-end devices
- **Pixel density:** 288 DPI
- **File size:** 9x larger than 1x
- **Quality:** Extremely sharp mobile displays
#### 4x (Maximum Resolution)
- **Use for:** Future-proofing, print materials
- **Pixel density:** 384 DPI
- **File size:** 16x larger than 1x
- **Quality:** Maximum detail
### Platform-Specific Recommendations
#### iOS Apps
- **1x:** iPhone 3GS and older (rarely needed)
- **2x:** iPhone 4-8, iPad non-Retina
- **3x:** iPhone 6 Plus and newer large iPhones
- **Required:** All three scales for App Store submission
#### Android Apps
- **ldpi (0.75x):** Low-density screens (rarely used)
- **mdpi (1x):** Medium-density baseline
- **hdpi (1.5x):** High-density screens
- **xhdpi (2x):** Extra high-density
- **xxhdpi (3x):** Extra extra high-density
- **xxxhdpi (4x):** Highest density screens
#### Web Development
- **1x:** Base resolution for all browsers
- **2x:** For `@2x` media queries and Retina displays
- **Consider WEBP:** For modern browsers with fallback
## Asset Organization Strategies
### Folder Structure
#### By Platform
```
assets/
├── web/
│ ├── 1x/
│ ├── 2x/
│ └── icons/
├── ios/
│ ├── 1x/
│ ├── 2x/
│ └── 3x/
└── android/
├── ldpi/
├── mdpi/
├── hdpi/
├── xhdpi/
├── xxhdpi/
└── xxxhdpi/
```
#### By Component Type
```
assets/
├── icons/
│ ├── navigation/
│ ├── actions/
│ └── status/
├── images/
│ ├── heroes/
│ ├── thumbnails/
│ └── placeholders/
└── logos/
├── full-color/
├── monochrome/
└── reversed/
```
### Naming Conventions
#### Descriptive Naming
```
✅ Good:
- icon-search-24px.svg
- button-primary-large@2x.png
- hero-homepage-1200w.jpg
❌ Bad:
- icon1.svg
- button.png
- image.jpg
```
#### Platform Conventions
**iOS:**
```
icon-name.png (1x)
icon-name@2x.png (2x)
icon-name@3x.png (3x)
```
**Android:**
```
ic_name.png (mdpi)
ic_name_hdpi.png (hdpi)
ic_name_xhdpi.png (xhdpi)
ic_name_xxhdpi.png (xxhdpi)
```
**Web:**
```
icon-name.svg (vector)
icon-name.png (1x fallback)
icon-name@2x.png (2x for Retina)
```
## Optimization Techniques
### File Size Optimization
#### PNG Optimization
- **Reduce colors:** Use 8-bit when possible instead of 24-bit
- **Remove metadata:** Strip EXIF data and comments
- **Optimize palettes:** Use indexed color for simple graphics
- **Tools:** TinyPNG, ImageOptim, OptiPNG
#### JPG Optimization
- **Quality settings:** 80-90% for most use cases
- **Progressive JPEG:** Better perceived loading
- **Appropriate dimensions:** Don't export larger than needed
- **Tools:** JPEGmini, ImageOptim, MozJPEG
#### SVG Optimization
- **Simplify paths:** Remove unnecessary points
- **Group similar elements:** Reduce code duplication
- **Remove unused definitions:** Clean up gradients, styles
- **Tools:** SVGO, SVGOMG, Figma's built-in optimization
### Performance Considerations
#### Image Dimensions
- **Web images:** No larger than container size
- **2x images:** Exactly 2x the display size
- **Responsive images:** Multiple sizes for different breakpoints
- **Lazy loading:** Consider loading strategies
#### Format Selection Decision Tree
```
Is it a photograph or complex image?
├── Yes → JPG (or WEBP for modern browsers)
└── No → Does it need transparency?
├── Yes → PNG (or SVG if simple)
└── No → JPG for web, PNG for UI elements
```
## Design Handoff Specifications
### Developer Handoff Assets
#### Complete Asset Package
1. **All required scales:** Platform-specific requirements
2. **Multiple formats:** SVG + PNG fallbacks for icons
3. **Organized structure:** Clear folder organization
4. **Naming documentation:** Explain naming conventions
5. **Usage guidelines:** When to use each asset
#### Asset Specifications Document
```
Asset Name: primary-button-large
Formats Available: PNG (1x, 2x, 3x), SVG
Dimensions:
- 1x: 120x44px
- 2x: 240x88px
- 3x: 360x132px
Usage: Primary call-to-action buttons
States: Default, Hover, Active, Disabled
```
### Design System Documentation
#### Component Assets
- **Multiple states:** Default, hover, active, disabled, loading
- **Size variations:** Small, medium, large
- **Theme variations:** Light mode, dark mode
- **Context usage:** When and where to use each variation
#### Icon Libraries
- **Consistent sizing:** 16px, 24px, 32px standard sizes
- **Stroke weights:** Consistent line thickness across set
- **Style coherence:** Same visual style for entire set
- **Semantic grouping:** Organize by function or category
## Batch Export Strategies
### Figma Export Tips
#### Selection-Based Export
1. Select multiple frames/components
2. Use export panel for batch settings
3. Apply same settings to all selected items
4. Export to organized folder structure
#### Component-Based Workflow
1. Create export-ready components
2. Use consistent naming for automatic organization
3. Set up export settings as part of component definition
4. Use plugins for advanced batch operations
### Automation Opportunities
#### Script-Based Export
- **Figma API:** Programmatic export control
- **Custom tools:** Build specific export workflows
- **Batch processing:** Handle hundreds of assets efficiently
- **Quality assurance:** Automated optimization and validation
#### CI/CD Integration
- **Automated exports:** Trigger on design updates
- **Asset deployment:** Push directly to CDN or asset pipeline
- **Version control:** Track asset changes alongside code
- **Optimization pipeline:** Automatic image optimization
## Special Use Cases
### App Store Assets
#### iOS App Store
- **App icons:** 1024x1024px for store, various sizes for app
- **Screenshots:** Device-specific dimensions
- **Requirements:** No transparency, specific format requirements
- **Validation:** App Store Connect validation rules
#### Google Play Store
- **Feature graphic:** 1024x500px
- **Screenshots:** Various device categories
- **App icons:** 512x512px high-res icon
- **Requirements:** Specific aspect ratios and content guidelines
### Print Materials
#### Print Specifications
- **Resolution:** 300 DPI minimum for professional printing
- **Color mode:** CMYK for print, RGB for digital
- **Bleed areas:** Extra space beyond trim line
- **Safe areas:** Keep important content away from edges
#### Export Settings
- **PDF format:** Preferred for print handoff
- **High resolution:** Use 4x scale or higher
- **Color profiles:** Include ICC profiles when possible
- **Vector preservation:** Maintain vector elements where possible
### Email Templates
#### Email Constraints
- **Image blocking:** Many clients block images by default
- **File size limits:** Keep images under 100KB when possible
- **Fallback text:** ALT text for accessibility
- **Dimensions:** Consider mobile email clients
#### Optimization Strategy
- **JPG for photos:** Smaller file sizes
- **PNG for UI elements:** Crisp edges and transparency
- **Inline critical images:** Small logos and icons
- **CDN hosting:** Fast loading from reliable servers
## Quality Assurance
### Export Validation
#### Visual Inspection
- **Compare to original:** Side-by-side comparison
- **Different scales:** Verify all export scales look correct
- **Multiple devices:** Test on target devices/browsers
- **Print proofs:** Physical proofs for print materials
#### Technical Validation
- **File sizes:** Reasonable for intended use
- **Dimensions:** Correct pixel dimensions
- **Format compatibility:** Works in target environments
- **Color accuracy:** Colors match design intent
### Testing Workflows
#### Cross-Platform Testing
- **Multiple browsers:** Chrome, Firefox, Safari, Edge
- **Different devices:** iOS, Android, various screen sizes
- **Operating systems:** macOS, Windows, Linux
- **Assistive technology:** Screen readers, high contrast modes
#### Performance Testing
- **Load times:** Measure actual loading performance
- **Bandwidth testing:** Test on slow connections
- **Caching behavior:** Verify proper caching headers
- **CDN performance:** Test global delivery speeds

263
references/figma-api-reference.md Normal file
View File

@@ -0,0 +1,263 @@
# Figma API Reference
Complete reference for Figma REST API endpoints and Plugin API capabilities.
## Authentication
### Access Token Setup
1. Generate personal access token: Figma → Settings → Account → Personal Access Tokens
2. For team/organization usage: Create OAuth app for broader access
3. Set environment variable: `FIGMA_ACCESS_TOKEN=your_token_here`
### API Headers
```http
X-Figma-Token: your_access_token_here
Content-Type: application/json
```
## REST API Endpoints
### File Operations
#### GET /v1/files/:key
Get complete file data including document tree, components, and styles.
**Parameters:**
- `version` (optional): Specific version ID
- `ids` (optional): Comma-separated node IDs to limit scope
- `depth` (optional): How deep to traverse document tree
- `geometry` (optional): Set to "paths" for vector data
- `plugin_data` (optional): Plugin IDs to include plugin data
**Response includes:**
- Document tree with all nodes
- Components map with metadata
- Styles map with style definitions
- Version and file metadata
#### GET /v1/files/:key/nodes
Get specific nodes from a file.
**Parameters:**
- `ids` (required): Comma-separated node IDs
- `version`, `depth`, `geometry`, `plugin_data` (same as above)
#### GET /v1/images/:key
Export nodes as images.
**Parameters:**
- `ids` (required): Node IDs to export
- `scale` (optional): 1, 2, or 4 (default: 1)
- `format` (optional): jpg, png, svg, or pdf (default: png)
- `svg_include_id` (optional): Include node IDs in SVG
- `svg_simplify_stroke` (optional): Simplify strokes in SVG
- `use_absolute_bounds` (optional): Use absolute coordinates
- `version` (optional): Specific version to export
**Returns:** Map of node IDs to image URLs (URLs expire after 30 days)
#### GET /v1/files/:key/images
Get image fill metadata from a file.
### Component Operations
#### GET /v1/files/:key/components
Get all components in a file.
#### GET /v1/components/:key
Get component metadata by component key.
#### GET /v1/teams/:team_id/components
Get team component library.
**Parameters:**
- `page_size` (optional): Results per page (max 1000)
- `after` (optional): Pagination cursor
### Style Operations
#### GET /v1/files/:key/styles
Get all styles in a file.
#### GET /v1/styles/:key
Get style metadata by style key.
#### GET /v1/teams/:team_id/styles
Get team style library.
### Project Operations
#### GET /v1/teams/:team_id/projects
Get projects for a team.
#### GET /v1/projects/:project_id/files
Get files in a project.
### User Operations
#### GET /v1/me
Get current user information.
## Rate Limits
- 1000 requests per minute per access token
- Image exports: 100 requests per minute
- Use exponential backoff for 429 responses
- Monitor `X-RateLimit-*` headers
## Error Handling
### Common HTTP Status Codes
- `400 Bad Request`: Invalid parameters
- `401 Unauthorized`: Invalid or missing access token
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: File or resource doesn't exist
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Figma server error
### Error Response Format
```json
{
"status": 400,
"err": "Bad request: Invalid file key"
}
```
## Node Types
### Document Structure
- `DOCUMENT` - Root document node
- `CANVAS` - Page/canvas node
- `FRAME` - Frame container
- `GROUP` - Group container
- `SECTION` - Section container
### Shape Nodes
- `RECTANGLE` - Rectangle shape
- `LINE` - Line shape
- `ELLIPSE` - Ellipse shape
- `POLYGON` - Polygon shape
- `STAR` - Star shape
- `VECTOR` - Vector shape
### Text and Components
- `TEXT` - Text node
- `COMPONENT` - Master component
- `COMPONENT_SET` - Component set (variants)
- `INSTANCE` - Component instance
### Special Nodes
- `BOOLEAN_OPERATION` - Boolean operation result
- `SLICE` - Export slice
- `STICKY` - Sticky note (FigJam)
- `CONNECTOR` - Connector line (FigJam)
## Plugin API Overview
The Plugin API allows creating, modifying, and analyzing design files through plugins.
### Key Capabilities
- **Create nodes**: Generate frames, shapes, text, components
- **Modify properties**: Update fills, strokes, effects, layout
- **Component management**: Create/update components and instances
- **Style operations**: Create and apply text/fill/effect styles
- **File operations**: Navigate pages, selection, document structure
### Plugin API Limitations
- Runs in browser sandbox environment
- Cannot directly access external APIs (use UI for HTTP requests)
- Limited file system access
- Must be installed/authorized by users
### Common Plugin Patterns
#### Creating Basic Shapes
```javascript
// Create rectangle
const rect = figma.createRectangle();
rect.resize(100, 100);
rect.fills = [{type: 'SOLID', color: {r: 1, g: 0, b: 0}}];
// Create text
const text = figma.createText();
await figma.loadFontAsync(text.fontName);
text.characters = "Hello World";
```
#### Working with Components
```javascript
// Create component
const component = figma.createComponent();
component.name = "Button";
// Create instance
const instance = component.createInstance();
```
#### Traversing Document Tree
```javascript
function traverse(node) {
console.log(node.name, node.type);
if ("children" in node) {
for (const child of node.children) {
traverse(child);
}
}
}
traverse(figma.root);
```
## Best Practices
### API Usage
1. **Batch operations**: Group multiple API calls when possible
2. **Cache results**: Store file data to minimize repeat requests
3. **Use specific node IDs**: Limit data transfer with `ids` parameter
4. **Handle rate limits**: Implement exponential backoff
5. **Version awareness**: Use version parameter for consistency
### Image Exports
1. **Choose appropriate format**: PNG for complex images, SVG for icons
2. **Optimize scale**: Use scale=1 unless high-DPI needed
3. **Batch exports**: Export multiple nodes in single request
4. **Cache URLs**: Store image URLs but remember 30-day expiration
### Plugin Development
1. **Minimize processing**: Keep operations fast to avoid timeouts
2. **Progress feedback**: Show progress for long operations
3. **Error handling**: Gracefully handle missing fonts, permissions
4. **Memory management**: Clean up large data structures
5. **User consent**: Request permissions appropriately
### Security
1. **Token protection**: Never expose access tokens in client-side code
2. **Scope principle**: Use minimal required permissions
3. **Input validation**: Validate all user inputs and API responses
4. **Audit logs**: Track API usage for compliance
## Common Use Cases
### Design System Automation
- Extract design tokens (colors, typography, spacing)
- Generate code from components
- Sync design systems across files
- Audit design consistency
### Asset Generation
- Export marketing assets in multiple formats
- Generate app icons and favicons
- Create social media templates
- Produce print-ready assets
### Workflow Integration
- Connect designs to development tools
- Automate handoff documentation
- Version control for design files
- Collaborative review processes
### Quality Assurance
- Accessibility compliance checking
- Brand guideline validation
- Consistency auditing across projects
- Performance optimization recommendations