App Ui Design

Mobile App UI Design

Expert guidance for designing beautiful, accessible, and platform-native mobile app interfaces following 2025 best practices.

Core Philosophy

• User-First Design — Prioritize user needs, behaviors, and mental models over aesthetics
• Platform Consistency — Follow iOS HIG and Android Material Design guidelines
• Accessibility as Foundation — Design for all users from the start, not as an afterthought
• Emotional Intelligence — Create interfaces that users emotionally connect with
• Performance-Conscious — Beautiful design that doesn't sacrifice app performance

---

Hard Rules (Must Follow)

These rules are mandatory. Violating them means the skill is not working correctly.

Accessibility First

All designs must meet WCAG 2.2 AA standards. Accessibility is not optional.

❌ FORBIDDEN:
- Color contrast below 4.5:1 for text
- Touch targets smaller than 44×44pt (iOS) or 48×48dp (Android)
- Information conveyed by color alone
- Missing alternative text for images
- Non-keyboard-navigable interfaces

✅ REQUIRED:
- Minimum 4.5:1 contrast ratio for normal text
- Minimum 3:1 contrast ratio for large text (18pt+)
- Touch targets: 44×44pt (iOS) / 48×48dp (Android)
- Support for Dynamic Type / Font Scaling
- VoiceOver (iOS) / TalkBack (Android) compatibility
- Clear focus indicators for keyboard navigation

Platform Guidelines Adherence

Follow platform-specific design guidelines. Do not mix iOS and Android patterns.

❌ FORBIDDEN:
- Using Android-style FAB on iOS
- Using iOS-style bottom sheets on Android without adaptation
- Mixing platform navigation patterns
- Ignoring platform typography (SF Pro vs Roboto)

✅ REQUIRED:
iOS (Human Interface Guidelines):
- Use SF Pro font family
- Tab bar at bottom for primary navigation
- Push navigation with back chevron
- Standard iOS controls (UIKit/SwiftUI)

Android (Material Design 3):
- Use Roboto font family
- Bottom navigation bar or navigation drawer
- Material components with ripple effects
- Follow Material You dynamic theming

Consistent Design System

Every app must have a documented design system with tokens.

❌ FORBIDDEN:
- Ad-hoc colors and spacing values
- Inconsistent button styles across screens
- Multiple unnamed font sizes
- Components without defined states

✅ REQUIRED:
Design System Must Include:
├── Color Tokens (primary, secondary, surface, error, etc.)
├── Typography Scale (heading1-6, body, caption, etc.)
├── Spacing Scale (4, 8, 12, 16, 24, 32, 48px)
├── Border Radius Tokens (none, sm, md, lg, full)
├── Shadow/Elevation Tokens (elevation1-5)
└── Component Library (button, input, card, etc.)

Touch-Friendly Design

All interactive elements must be optimized for touch interaction.

❌ FORBIDDEN:
- Touch targets smaller than minimum size
- Interactive elements too close together (<8px gap)
- Important actions outside thumb reach zone
- Hover-dependent interactions

✅ REQUIRED:
- Minimum touch target: 44×44pt (iOS) / 48×48dp (Android)
- Minimum spacing between targets: 8px
- Primary actions in thumb-friendly zone (bottom 2/3)
- Clear tap feedback (ripple, highlight, scale)

---

Quick Reference

When to Use What

---

Design System Fundamentals

Color System

## Color Token Structure

### Semantic Colors
primary          → Main brand color, CTAs
primary-variant  → Darker/lighter primary for states
secondary        → Secondary actions, accents
background       → App background
surface          → Card backgrounds, elevated surfaces
error            → Error states, destructive actions
on-primary       → Text/icons on primary color
on-background    → Text/icons on background
on-surface       → Text/icons on surface

### Color Palette (60-30-10 Rule)
60% → Neutral/background colors
30% → Secondary/supporting colors
10% → Accent/primary colors

### Dark Mode Considerations
- Don't just invert colors
- Use desaturated colors for dark surfaces
- Reduce contrast slightly (avoid pure white on black)
- Maintain color meaning across modes

Typography Scale

## Mobile Typography Guidelines

### iOS Typography (SF Pro)
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 1     → 12pt, Regular
Caption 2     → 11pt, Regular

### Android Typography (Roboto / Material 3)
Display Large  → 57sp
Display Medium → 45sp
Display Small  → 36sp
Headline Large → 32sp
Headline Medium→ 28sp
Headline Small → 24sp
Title Large    → 22sp
Title Medium   → 16sp, Medium
Title Small    → 14sp, Medium
Body Large     → 16sp
Body Medium    → 14sp
Body Small     → 12sp
Label Large    → 14sp, Medium
Label Medium   → 12sp, Medium
Label Small    → 11sp, Medium

### Best Practices
- Maximum 2-3 font families per app
- Minimum body text: 16px (14px absolute minimum)
- Line height: 1.4-1.6× font size for body text
- Support Dynamic Type (iOS) / Font Scaling (Android)

Spacing System

## 8-Point Grid System

Base Unit: 8px

### Spacing Scale
spacing-0    → 0px
spacing-1    → 4px   (half unit)
spacing-2    → 8px   (1 unit)
spacing-3    → 12px  (1.5 units)
spacing-4    → 16px  (2 units)
spacing-5    → 24px  (3 units)
spacing-6    → 32px  (4 units)
spacing-7    → 48px  (6 units)
spacing-8    → 64px  (8 units)

### Component Spacing
Button padding      → 12px vertical, 24px horizontal
Card padding        → 16px
List item padding   → 16px horizontal, 12px vertical
Section spacing     → 24px-32px
Screen edge margin  → 16px (phones), 24px (tablets)

### Touch Target Spacing
Minimum gap between interactive elements: 8px
Recommended gap: 12-16px

---

Platform Guidelines

iOS Human Interface Guidelines

## iOS Design Principles

### Core Principles
1. Clarity    → Text legible, icons precise, purpose obvious
2. Deference  → UI helps understanding, not competing with content
3. Depth      → Visual layers and realistic motion convey hierarchy

### Navigation Patterns
- Tab Bar (bottom) → 3-5 primary destinations
- Navigation Bar (top) → Title, back button, actions
- Modal sheets → Temporary focused tasks
- Popovers (iPad) → Contextual options

### 2025 Updates: Liquid Glass
- Translucent materials for controls
- Floating navigation elements
- Dynamic depth and hierarchy
- Background blur effects

### Safe Areas
- Top: Status bar + Dynamic Island/Notch
- Bottom: Home indicator (34pt on Face ID devices)
- Use safeAreaInsets for proper content placement

### Standard Dimensions
- Navigation bar height: 44pt (96pt with large title)
- Tab bar height: 49pt (83pt on Face ID devices)
- Toolbar height: 44pt

Android Material Design 3

## Material Design 3 Principles

### Core Concepts
1. Material You    → Personal, adaptive, dynamic color
2. Expressiveness  → Emotional connection through design
3. Accessibility   → Inclusive design for all users

### Navigation Patterns
- Bottom Navigation → 3-5 primary destinations
- Navigation Drawer → 5+ destinations or secondary nav
- Navigation Rail → Tablets and large screens
- Top App Bar → Title, navigation, actions

### Material 3 Expressive (2025)
- Dynamic color from user wallpaper
- Springy, physics-based motion
- Bolder, more expressive typography
- Rounded, approachable shapes

### Component Shapes
- Extra Small: 4dp
- Small: 8dp
- Medium: 12dp
- Large: 16dp
- Extra Large: 28dp
- Full: 50% (pills/circles)

### Standard Dimensions
- App bar height: 64dp
- Bottom navigation height: 80dp
- FAB size: 56dp (standard), 40dp (small), 96dp (large)

---

2025 Design Trends

AI-Driven Personalization

## Adaptive UI Patterns

### Personalization Strategies
- Content recommendations based on behavior
- Adaptive UI layouts based on usage patterns
- Smart defaults and predictive actions
- Contextual feature suggestions

### Implementation Guidelines
- Always provide manual override options
- Explain why content is recommended
- Respect user privacy preferences
- Gradual personalization (don't overwhelm new users)

Dark Mode Excellence

## Dark Mode Best Practices

### Color Adaptation
Light Mode          →    Dark Mode
White (#FFFFFF)     →    Dark gray (#121212)
Black (#000000)     →    White (#FFFFFF)
Primary (vibrant)   →    Primary (desaturated)
Shadows             →    Subtle shadows or none

### Surface Elevation (Material 3)
Elevation 0  → #121212
Elevation 1  → #1E1E1E (+ 5% white overlay)
Elevation 2  → #232323 (+ 7% white overlay)
Elevation 3  → #272727 (+ 8% white overlay)
Elevation 4  → #2C2C2C (+ 9% white overlay)
Elevation 5  → #323232 (+ 11% white overlay)

### Recommendations
- Auto-switch based on system setting
- Separate color tokens for light/dark
- Test contrast in both modes
- Consider OLED optimization (true blacks)

Microinteractions

## Meaningful Motion

### Types of Microinteractions
- Feedback → Button press, form submission
- State → Loading, success, error
- Guidance → Onboarding hints, tooltips
- Delight → Celebration animations, easter eggs

### Motion Principles
- Duration: 200-500ms for most interactions
- Easing: Use natural easing curves
- Purpose: Every animation should have a reason
- Performance: Use hardware-accelerated properties

### 2025 Trends
- Springy, physics-based animations
- Morphing transitions between states
- Gesture-driven interactions
- Reduced motion support for accessibility

Glassmorphism & Neumorphism

## Modern Visual Styles

### Glassmorphism
Properties:
- Background blur (backdrop-filter: blur)
- Transparency (10-40% opacity)
- Subtle border (1px white at 20% opacity)
- Soft shadow

Use Cases:
- Overlays and modals
- Cards on image backgrounds
- Navigation bars (iOS Liquid Glass)

Caution:
- Ensure text readability
- Consider performance impact
- Provide fallback for older devices

### Neumorphism (Soft UI)
Properties:
- Soft shadows (light and dark)
- Subtle elevation effect
- Muted color palette

Use Cases:
- Toggle switches
- Input fields
- Cards

Caution:
- Often fails accessibility contrast tests
- Use sparingly, not as primary style
- Always test with actual content

---

Extended Reference

Detailed material starting at ## Accessibility Checklist has been moved to `reference/extended.md` to keep this skill concise. Load that reference when the task requires the moved examples, command catalogs, checklists, platform details, or implementation templates.

Mobile Accessibility Guidelines

WCAG 2.2 AA compliance checklist for mobile app design.

POUR Principles

Perceivable

Content must be presentable in ways users can perceive.

Operable

Interface must be operable by all users.

Understandable

Information and UI must be understandable.

Robust

Content must work with assistive technologies.

---

Visual Accessibility

Color Contrast

## Contrast Examples

Good ✓
├── Black (#000000) on White (#FFFFFF) = 21:1
├── Dark Gray (#333333) on White (#FFFFFF) = 12.6:1
└── Blue (#0066CC) on White (#FFFFFF) = 5.3:1

Bad ✗
├── Light Gray (#999999) on White (#FFFFFF) = 2.8:1
├── Yellow (#FFFF00) on White (#FFFFFF) = 1.07:1
└── Green (#00FF00) on White (#FFFFFF) = 1.37:1

Color Independence

Never use color as the only means of conveying information.

❌ Bad:
"Fields marked in red are required"
(Users with colorblindness can't identify)

✅ Good:
"Required fields are marked with *"
+ Red color for additional emphasis
+ Error icon next to invalid fields

Text Sizing

## Font Scaling Support

Must support:
├── 100% (default)
├── 150% (medium scaling)
├── 200% (large scaling)
└── 250%+ (extra large, if possible)

All content must remain readable and usable at 200% scaling.

Focus Indicators

Requirements:
- Visible focus ring on all interactive elements
- Minimum 2px width
- 3:1 contrast against adjacent colors
- Consistent across app

Example CSS-like styling:
focus: {
  outline: 2px solid #0066CC
  outlineOffset: 2px
}

---

Motor Accessibility

Touch Targets

## Target Spacing

Minimum gap between targets: 8px
Recommended gap: 12-16px

┌────────────────────────────────────────┐
│                                        │
│  ┌─────────┐   8px+   ┌─────────┐     │
│  │  44pt   │   gap    │  44pt   │     │
│  │ Button  │ ←─────→ │ Button  │     │
│  └─────────┘          └─────────┘     │
│                                        │
└────────────────────────────────────────┘

Gesture Alternatives (WCAG 2.2)

For every gesture-based action, provide an alternative:

Gesture → Alternative
─────────────────────────────────────────
Swipe to delete → Tap to reveal delete button
Pinch to zoom → Zoom +/- buttons
Drag to reorder → Tap to move up/down
Long press → Tap for options button
Two-finger scroll → Single finger scroll
Drawing gesture → Button to perform action

Timing

Requirements:
- No time limits on actions (or extendable)
- Auto-advancing content can be paused
- Session timeouts warn user with extension option

❌ Bad: Form submits automatically after 30 seconds
✅ Good: User controls when to submit

---

Cognitive Accessibility

Clear Labels

Every form input needs:
1. Visible label (not placeholder only)
2. Associated label (for screen readers)
3. Clear instructions if needed
4. Error messages that explain the fix

❌ Bad:
┌─────────────────────────┐
│ Email                   │  ← Placeholder disappears
└─────────────────────────┘

✅ Good:
Email *
┌─────────────────────────┐
│ example@email.com       │  ← Placeholder as hint
└─────────────────────────┘
Enter your work email address

Error Messages

Error messages must:
1. Identify the field with error
2. Explain what went wrong
3. Suggest how to fix it

❌ Bad: "Invalid input"
✅ Good: "Email address must include @"

❌ Bad: "Error"
✅ Good: "Password must be at least 8 characters"

Consistent Navigation

Navigation must be:
- Consistent across all screens
- Predictable in behavior
- Clear in current location

┌──────────────────────────────────┐
│  ← Back     Profile    ⚙️       │  Consistent header
├──────────────────────────────────┤
│                                  │
│         Page Content             │
│                                  │
├──────────────────────────────────┤
│  🏠    🔍    ➕    👤           │  Consistent footer
│        Active indicator          │
└──────────────────────────────────┘

---

Screen Reader Support

Required Labels

## iOS (VoiceOver)

Every interactive element needs:
├── accessibilityLabel → What it is
├── accessibilityHint → What happens when activated
├── accessibilityTraits → Type (button, link, etc.)
└── accessibilityValue → Current value (if applicable)

SwiftUI Example:
Button("Add to cart") { }
  .accessibilityLabel("Add to cart")
  .accessibilityHint("Adds this item to your shopping cart")

## Android (TalkBack)

contentDescription → What it is
stateDescription → Current state
roleDescription → Type override
accessibilityLiveRegion → For dynamic content

Compose Example:
Button(
  onClick = { },
  modifier = Modifier.semantics {
    contentDescription = "Add to cart"
  }
) { Text("Add") }

Heading Structure

Use proper heading hierarchy for navigation:

Screen Title (Heading 1)
├── Section A (Heading 2)
│   ├── Subsection A.1 (Heading 3)
│   └── Subsection A.2 (Heading 3)
└── Section B (Heading 2)
    └── Content

iOS: accessibilityTraits = .header
Android: heading = true

Reading Order

Ensure logical reading order matches visual order:

1. Top to bottom
2. Left to right (or right to left for RTL)
3. Group related elements

Test by:
- Using screen reader
- Checking tab order
- Verifying announcements make sense

Dynamic Content

Announce changes to screen:

iOS:
UIAccessibility.post(notification: .announcement, argument: "Item added")

Android:
View.announceForAccessibility("Item added")

Use for:
├── Loading states
├── Error messages
├── Success confirmations
├── Content updates
└── Navigation changes

---

Platform Features

iOS Accessibility Features

Support these system features:
├── Dynamic Type → Scalable text
├── Bold Text → Heavier font weights
├── Increase Contrast → Higher contrast UI
├── Reduce Motion → Minimize animations
├── Reduce Transparency → Solid backgrounds
├── VoiceOver → Screen reader
├── Switch Control → Physical switch navigation
├── Voice Control → Voice commands
└── AssistiveTouch → Custom gestures

Android Accessibility Features

Support these system features:
├── Font size → Text scaling
├── Display size → UI scaling
├── High contrast text → Enhanced contrast
├── Color correction → Colorblind modes
├── Color inversion → Dark mode alternative
├── TalkBack → Screen reader
├── Switch Access → Physical switch navigation
├── Voice Access → Voice commands
└── BrailleBack → Braille display support

---

Testing Checklist

Automated Testing

□ Run accessibility scanner
  - iOS: Accessibility Inspector
  - Android: Accessibility Scanner app

□ Check contrast ratios
  - WebAIM Contrast Checker
  - Stark plugin

□ Validate focus order
  - Use keyboard navigation
  - Check logical sequence

Manual Testing

## Screen Reader Testing

□ VoiceOver (iOS)
  - Enable: Settings > Accessibility > VoiceOver
  - Navigate entire app
  - Verify all elements announced
  - Check announcement clarity

□ TalkBack (Android)
  - Enable: Settings > Accessibility > TalkBack
  - Navigate entire app
  - Verify all elements announced
  - Check announcement clarity

## Motor Testing

□ Keyboard navigation (external keyboard)
  - Tab through all elements
  - Activate with Enter/Space
  - Use arrow keys where appropriate

□ Switch Control
  - Navigate and activate all features
  - No time-dependent actions

User Testing

Include users with disabilities:
├── Vision impairments
├── Motor impairments
├── Cognitive differences
├── Hearing impairments (for audio content)
└── Temporary impairments (arm in cast, etc.)

---

Common Mistakes

❌ Placeholder-only labels
   Fix: Add visible label above input

❌ Color-only indicators
   Fix: Add icons, text, or patterns

❌ Small touch targets
   Fix: Minimum 44pt/48dp size

❌ Missing alt text
   Fix: Add descriptive labels to all images

❌ Auto-playing media
   Fix: Require user action to play

❌ Motion without control
   Fix: Respect "Reduce Motion" setting

❌ Time limits
   Fix: Allow extension or removal

❌ Keyboard traps
   Fix: Allow tab navigation in and out

❌ Unclear focus
   Fix: Visible focus indicator on all elements

❌ Non-semantic structure
   Fix: Use proper headings and landmarks

---

Quick Reference Card

┌─────────────────────────────────────────────────────────┐
│              ACCESSIBILITY QUICK REFERENCE               │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  CONTRAST                                                │
│  • Text: 4.5:1 (normal), 3:1 (large)                    │
│  • UI components: 3:1                                    │
│                                                          │
│  TOUCH TARGETS                                           │
│  • iOS: 44×44pt minimum                                  │
│  • Android: 48×48dp minimum                              │
│  • Spacing: 8px minimum gap                              │
│                                                          │
│  TEXT                                                    │
│  • Support Dynamic Type / Font Scaling                   │
│  • Must work at 200% zoom                                │
│  • Visible labels, not placeholder-only                  │
│                                                          │
│  SCREEN READERS                                          │
│  • Label all interactive elements                        │
│  • Announce dynamic changes                              │
│  • Logical reading order                                 │
│                                                          │
│  MOTION                                                  │
│  • Respect Reduce Motion setting                         │
│  • Provide alternatives to gestures                      │
│  • No auto-playing content                               │
│                                                          │
└─────────────────────────────────────────────────────────┘

---

Resources

• WCAG 2.2 Guidelines
• Apple Accessibility
• Android Accessibility
• WebAIM Contrast Checker
• A11y Project Checklist

Color Theory for Mobile Apps

Essential color selection and usage guidelines for mobile app design.

Color Fundamentals

Color Properties

HUE        → The color itself (red, blue, green)
             Measured in degrees (0-360°)

SATURATION → Color intensity/purity
             0% = gray, 100% = pure color

LIGHTNESS  → How light or dark
             0% = black, 100% = white

BRIGHTNESS → Perceived luminance
             How much light appears to emit

Color Wheel

              Yellow (60°)
                  ●
            /           \
     Yellow-Green      Orange
          /               \
    Green ●               ● Red (0°/360°)
          \               /
       Cyan           Magenta
            \         /
                ●
              Blue (240°)

---

Color Relationships

Monochromatic

Single hue with varying saturation/lightness.

████████████████████████████████
Light ←──────────────────→ Dark

Use: Clean, professional, minimalist apps
Example: Different shades of blue

Complementary

Colors opposite on the wheel (high contrast).

    ●──────────────●
   Red            Cyan

Use: CTAs, important elements, contrast
Caution: Can be jarring if overused

Analogous

Adjacent colors on the wheel (harmonious).

        ● ● ●
    Blue Cyan Green

Use: Cohesive, calming palettes
Example: Nature apps, wellness apps

Triadic

Three colors equally spaced (balanced variety).

          ●
         /  \
        /    \
       ●──────●

Use: Vibrant, balanced palettes
Example: Red, Yellow, Blue (primary)

Split-Complementary

One color + two adjacent to its complement.

          ●
         /|\
        / | \
       ●     ●

Use: Contrast with less tension
Example: Blue + Yellow-Orange + Red-Orange

---

The 60-30-10 Rule

60% → Primary/Neutral color (backgrounds, large areas)
30% → Secondary color (cards, sections, supporting)
10% → Accent color (CTAs, icons, highlights)

Example:
┌────────────────────────────────────────────┐
│                                            │
│  ████████████████████████████████████████  │ 60% Light Gray
│  ████████████████████████████████████████  │ (Background)
│  ████████████████████████████████████████  │
│                                            │
│     ┌────────────────────────────────┐     │
│     │  ████████████████████████████  │     │ 30% White
│     │  ████████████████████████████  │     │ (Cards)
│     │          ┌──────────┐          │     │
│     │          │  Submit  │          │     │ 10% Blue
│     │          └──────────┘          │     │ (CTA Button)
│     └────────────────────────────────┘     │
│                                            │
└────────────────────────────────────────────┘

---

Semantic Colors

Standard Meanings

Semantic Token Structure

## Color Token Naming

Semantic (Recommended):
├── color-primary
├── color-primary-variant
├── color-secondary
├── color-background
├── color-surface
├── color-error
├── color-success
├── color-warning
├── color-on-primary
├── color-on-background
└── color-on-surface

Avoid Literal Names:
├── color-blue ← Don't use
├── color-red ← Don't use
└── color-green ← Don't use

---

Dark Mode Colors

Adaptation Principles

DON'T just invert colors. Instead:

1. Reduce saturation for dark surfaces
2. Use elevation with lighter overlays
3. Keep brand colors recognizable
4. Test contrast in both modes

Light Mode → Dark Mode
───────────────────────────────────────
White background → Dark gray (#121212), not pure black
Black text → Light gray (#E0E0E0), not pure white
Vibrant primary → Slightly desaturated primary
White on colored → Dark on lighter colored

Surface Elevation (Material 3)

Dark Mode Surface Colors:

Level 0: #121212 (base surface)
Level 1: #1E1E1E (+ 5% white overlay)
Level 2: #232323 (+ 7% white overlay)
Level 3: #272727 (+ 8% white overlay)
Level 4: #2C2C2C (+ 9% white overlay)
Level 5: #323232 (+ 11% white overlay)

Cards and elevated elements use higher levels
to create visual hierarchy without shadows.

OLED Optimization

For OLED screens:
- True black (#000000) saves battery
- Use for backgrounds where appropriate
- Avoid large areas of pure white
- Test for "smearing" effect on scrolling

Recommendation:
Use near-black (#0A0A0A) instead of pure black
for main backgrounds to reduce contrast issues.

---

Accessibility & Contrast

WCAG Contrast Requirements

Minimum Contrast Ratios:

Text (< 18pt / 14pt bold):     4.5:1  [AA]
Large Text (≥ 18pt / 14pt bold): 3:1  [AA]
UI Components:                   3:1  [AA]

Enhanced (AAA):
Text:       7:1
Large Text: 4.5:1

Color Contrast Examples

Good Contrast ✓
─────────────────────────────────────────
#000000 on #FFFFFF → 21:1 (Excellent)
#333333 on #FFFFFF → 12.6:1 (Excellent)
#0066CC on #FFFFFF → 5.3:1 (Good for AA)
#1A73E8 on #FFFFFF → 4.5:1 (Minimum AA)

Poor Contrast ✗
─────────────────────────────────────────
#777777 on #FFFFFF → 4.5:1 (Borderline)
#999999 on #FFFFFF → 2.8:1 (Fail)
#AAAAAA on #FFFFFF → 2.3:1 (Fail)

Colorblind Considerations

Types of Color Blindness:
├── Deuteranopia (red-green, most common)
├── Protanopia (red-green)
├── Tritanopia (blue-yellow, rare)
└── Achromatopsia (complete, very rare)

Guidelines:
1. Don't rely on color alone
2. Add icons, patterns, or text
3. Test with color blindness simulators
4. Avoid red/green combinations for distinctions

Tools:
- Color Oracle (desktop simulator)
- Figma A11y plugin
- Chrome DevTools → Rendering → Emulate

---

Brand Color Guidelines

Choosing Primary Color

Considerations:
1. Industry conventions
2. Target audience expectations
3. Cultural meanings
4. Competitor differentiation
5. Accessibility requirements

Industry Trends:
├── Finance: Blue (trust, security)
├── Health: Green, Blue (calm, growth)
├── Food: Red, Orange (appetite, energy)
├── Luxury: Black, Gold, Purple (premium)
├── Tech: Blue, Purple (innovation)
└── Children: Bright, varied (fun)

Creating a Palette

Step 1: Choose primary color
        ████████████
        Brand Blue #1A73E8

Step 2: Generate tonal variations
        100 ██████████ Lightest
        200 ██████████
        300 ██████████
        400 ██████████
        500 ██████████ ← Primary
        600 ██████████
        700 ██████████
        800 ██████████
        900 ██████████ Darkest

Step 3: Select secondary color
        (Complementary or analogous)

Step 4: Add semantic colors
        (Error, warning, success)

Step 5: Define neutrals
        (Gray scale for text, borders)

Palette Sizes

Minimal Palette (Simple Apps):
├── Primary (1 shade)
├── Secondary (1 shade)
├── Neutrals (3-5 grays)
├── Error (red)
└── Success (green)

Standard Palette (Most Apps):
├── Primary (5 tonal variations)
├── Secondary (5 tonal variations)
├── Tertiary (3 tonal variations)
├── Neutrals (7-10 grays)
├── Semantic (error, warning, success, info)
└── Surfaces (light/dark backgrounds)

Extended Palette (Complex Apps):
├── Primary family (10 variations)
├── Secondary family (10 variations)
├── Tertiary family (10 variations)
├── Extended neutrals
├── Extended semantics
└── Special purpose colors

---

2025 Color Trends

Popular Palettes

1. Muted & Desaturated
   Soft, gentle colors with reduced saturation
   ██████ #8B9A7D (Sage)
   ██████ #B8A9C9 (Lavender)
   ██████ #F2E8DC (Cream)

2. Bold Gradients
   Vibrant color transitions
   ██████ → ██████ (Sunset: Orange to Pink)
   ██████ → ██████ (Ocean: Blue to Teal)

3. Neo-Brutalism
   High contrast, bold primaries
   ██████ #FF5733 (Bold Orange)
   ██████ #000000 (Black)
   ██████ #FFFFFF (White)

4. Digital Nature
   Tech meets organic
   ██████ #0A6847 (Forest)
   ██████ #7ABA78 (Leaf)
   ██████ #F6E9B2 (Sand)

Material You Dynamic Color

Android 12+ extracts colors from wallpaper:

User Wallpaper
      ↓
Color Extraction Algorithm
      ↓
├── Primary color
├── Secondary color
├── Tertiary color
├── Neutral color
└── Neutral variant

App automatically adapts to user's palette.

---

Quick Reference

Color Token Template

{
  "colors": {
    "primary": {
      "main": "#1A73E8",
      "light": "#4285F4",
      "dark": "#1557B0",
      "contrast": "#FFFFFF"
    },
    "secondary": {
      "main": "#34A853",
      "light": "#5BB974",
      "dark": "#1E8E3E",
      "contrast": "#FFFFFF"
    },
    "background": {
      "default": "#FFFFFF",
      "paper": "#F5F5F5"
    },
    "text": {
      "primary": "#202124",
      "secondary": "#5F6368",
      "disabled": "#9AA0A6"
    },
    "error": "#D93025",
    "warning": "#F9AB00",
    "success": "#1E8E3E",
    "info": "#1A73E8"
  }
}

Contrast Checker Tools

Online Tools:
- WebAIM Contrast Checker
- Coolors Contrast Checker
- Color Review

Design Tool Plugins:
- Stark (Figma, Sketch)
- A11y Color Contrast
- Contrast (Figma)

Browser DevTools:
- Chrome: Inspect → Color picker
- Firefox: Accessibility Inspector

---

Resources

• Coolors - Palette generator
• Adobe Color - Color wheel
• Realtime Colors - Preview on mock UI
• Material Theme Builder - Material 3
• Paletton - Color scheme designer
• Color Hunt - Curated palettes

app-ui-design Extended Reference

This file preserves detailed material moved out of SKILL.md for progressive disclosure. Load it only when the current task needs the specific examples, commands, templates, or checklists below.

Moved content starts at: ## Accessibility Checklist.

Accessibility Checklist

Visual Accessibility

## Vision Accessibility Checklist

### Color & Contrast
- [ ] Text contrast ≥ 4.5:1 (normal), ≥ 3:1 (large)
- [ ] UI component contrast ≥ 3:1
- [ ] Color is not the only indicator (use icons, text)
- [ ] Works for colorblind users (test with simulators)

### Text & Typography
- [ ] Base font size ≥ 16px
- [ ] Supports Dynamic Type (iOS) / Font Scaling (Android)
- [ ] Line height ≥ 1.4× for body text
- [ ] Text can scale to 200% without loss of content

### Focus & Navigation
- [ ] Visible focus indicators
- [ ] Logical tab order
- [ ] Skip links for repetitive content
- [ ] Keyboard-accessible (external keyboards)

Motor Accessibility

## Motor Accessibility Checklist

### Touch Targets
- [ ] Minimum size: 44×44pt (iOS) / 48×48dp (Android)
- [ ] Spacing between targets ≥ 8px
- [ ] No time-limited interactions (or extendable)
- [ ] Alternative to drag gestures (WCAG 2.2)

### Interaction
- [ ] Single-tap for all actions (no double-tap required)
- [ ] Undo available for destructive actions
- [ ] No precision requirements (fine motor)
- [ ] Support for Switch Control / Voice Access

Screen Reader

## Screen Reader Checklist

### Content
- [ ] All images have descriptive alt text
- [ ] Decorative images have empty alt (alt="")
- [ ] Buttons/links have descriptive labels
- [ ] Form inputs have associated labels
- [ ] Headings used for structure (not styling)

### Navigation
- [ ] Logical reading order
- [ ] Meaningful link text (not "click here")
- [ ] State changes announced
- [ ] Modal focus properly trapped
- [ ] Custom components have ARIA roles

---

Component Patterns

Button Design

## Button Hierarchy

### Primary Button
- Most important action on screen
- Filled/solid style
- High contrast
- Only ONE per view section

### Secondary Button
- Alternative actions
- Outlined or tonal style
- Medium contrast

### Tertiary Button
- Low-priority actions
- Text-only or ghost style
- Subtle appearance

### Destructive Button
- Delete, remove, cancel
- Red/error color
- Requires confirmation for important data

### Button States
- Default → Normal appearance
- Pressed → Scale down, darker
- Disabled → 50% opacity, no interaction
- Loading → Spinner, disabled

Form Design

## Form Best Practices

### Input Fields
- Clear labels (above input, not placeholder-only)
- Helpful placeholder text
- Error states with specific messages
- Success validation feedback
- Appropriate keyboard types

### Layout
- Single column for mobile
- Group related fields
- Logical tab order
- Primary action at bottom
- Sticky submit button if long form

### Validation
- Inline validation (on blur or after input)
- Clear error messages with fix suggestions
- Don't clear fields on error
- Mark required fields clearly

Navigation Patterns

## Mobile Navigation

### Bottom Navigation (Primary)
- 3-5 destinations
- Icons + labels
- Active state indicator
- Consistent across app

### Tab Bar (Content Switching)
- Horizontal tabs for related content
- Swipe between tabs
- Indicator for active tab

### Navigation Stack
- Clear back navigation
- Meaningful titles
- Breadcrumbs for deep hierarchies

### Gestures
- Swipe back (iOS standard)
- Pull to refresh
- Swipe actions on list items
- Long press for context menus

---

Design Process

Workflow

## App Design Workflow

1. Research & Discovery
   ├── User research and personas
   ├── Competitor analysis
   ├── Platform guidelines review
   └── Technical constraints

2. Information Architecture
   ├── User flows
   ├── Navigation structure
   ├── Content hierarchy
   └── Sitemap

3. Design System Setup
   ├── Color tokens
   ├── Typography scale
   ├── Spacing system
   ├── Component library
   └── Icon set

4. Wireframing
   ├── Low-fidelity layouts
   ├── Flow validation
   ├── Stakeholder review
   └── Iteration

5. Visual Design
   ├── High-fidelity mockups
   ├── Interaction design
   ├── Prototype creation
   └── Accessibility audit

6. Handoff & Implementation
   ├── Design specs documentation
   ├── Asset export
   ├── Developer collaboration
   └── QA review

---

Anti-Patterns to Avoid

## Common Mistakes

### Visual Design
❌ Using more than 3 fonts
❌ Inconsistent spacing values
❌ Low contrast text
❌ Overly complex gradients/effects
❌ Ignoring safe areas

### Interaction Design
❌ Hidden navigation
❌ Gesture-only actions without alternatives
❌ Tiny touch targets
❌ No loading states
❌ Confusing back navigation

### Accessibility
❌ Placeholder-only labels
❌ Color-only information
❌ Auto-playing media
❌ Timed interactions without extension
❌ Missing screen reader labels

### Platform
❌ iOS patterns on Android (or vice versa)
❌ Custom controls when standard works
❌ Ignoring platform conventions
❌ Not supporting dark mode

---

Checklist

Before Design

• [ ] Reviewed platform guidelines (iOS HIG / Material Design 3)
• [ ] Defined target users and their needs
• [ ] Analyzed competitor apps
• [ ] Identified accessibility requirements
• [ ] Set up design system tokens

During Design

• [ ] Following 8-point grid
• [ ] Using defined color tokens
• [ ] Typography from scale only
• [ ] Touch targets meet minimum size
• [ ] Contrast ratios verified
• [ ] All states designed (default, pressed, disabled, error)
• [ ] Dark mode variant created

Before Handoff

• [ ] Accessibility audit completed
• [ ] Tested with screen reader
• [ ] Verified on multiple screen sizes
• [ ] Motion/animation documented
• [ ] Design specs annotated
• [ ] Assets exported correctly

---

Tools & Resources

Design Tools

• Figma → Industry standard, collaboration
• Sketch → Mac-native, established ecosystem
• Adobe XD → Adobe integration

Prototyping

• Figma Prototyping → Built-in, quick
• ProtoPie → Advanced interactions
• Principle → Mac, detailed animations

Accessibility Testing

• Stark → Contrast checker (Figma plugin)
• Color Oracle → Colorblind simulator
• VoiceOver (iOS) / TalkBack (Android)

Platform Resources

• Apple Human Interface Guidelines
• Google Material Design
• WCAG 2.2 Guidelines

---

See Also

• reference/ios-guidelines.md — iOS Human Interface Guidelines summary
• reference/material-design.md — Material Design 3 summary
• reference/accessibility.md — WCAG 2.2 mobile checklist
• reference/color-theory.md — Color selection and contrast
• templates/design-system-template.md — Design system starter

---

Sources

Research based on 2025 best practices from:

• Mobile App UI Design Best Practices 2025
• UI/UX Design Trends 2025
• Mobile App Design Trends 2025
• Accessibility in UI/UX Design 2025
• iOS Design Guidelines 2025
• Mobile App Design Guidelines iOS/Android

iOS Human Interface Guidelines

Quick reference for iOS app design following Apple's Human Interface Guidelines (2025).

Design Principles

Clarity

• Text must be legible at every size
• Icons must be precise and understandable
• Adornments must be subtle and appropriate
• Focus on functionality drives design

Deference

• Fluid motion and crisp interface help understanding
• Content fills the screen
• Translucency and blur hint at more content
• Minimal use of bezels, gradients, and shadows

Depth

• Distinct visual layers convey hierarchy
• Transitions provide sense of depth
• Touch and discoverability enhance delight

Typography

SF Pro Font Family

Dynamic Type Support

Always support Dynamic Type for accessibility:

// SwiftUI
Text("Hello")
    .font(.body) // Automatically scales

// UIKit
label.font = UIFont.preferredFont(forTextStyle: .body)
label.adjustsFontForContentSizeCategory = true

Layout & Spacing

Safe Areas

┌──────────────────────────────────┐
│         Status Bar (47pt)        │  ← Top safe area
├──────────────────────────────────┤
│                                  │
│                                  │
│         Content Area             │
│                                  │
│                                  │
├──────────────────────────────────┤
│     Home Indicator (34pt)        │  ← Bottom safe area
└──────────────────────────────────┘

Standard Margins

Touch Targets

• Minimum size: 44×44pt
• Recommended size: 48×48pt for primary actions
• Spacing between targets: 8pt minimum

Navigation

Tab Bar

┌──────────────────────────────────┐
│         Content Area             │
├──────────────────────────────────┤
│  🏠    🔍    ➕    ❤️    👤  │
│ Home Search  Add  Favs Profile  │
└──────────────────────────────────┘
Height: 49pt (83pt on Face ID devices)

• 3-5 tabs maximum
• Always show labels
• Use SF Symbols for icons
• Highlight active tab with fill or tint

Navigation Bar

┌──────────────────────────────────┐
│  ‹ Back       Title        Edit  │
│  (or Menu)                       │
└──────────────────────────────────┘
Height: 44pt (96pt with large title)

• Large title: Use for primary screens
• Standard title: Use for secondary screens
• Back button shows previous screen title (truncated)

Sheets & Modals

Types:
- Sheet (.sheet) → Partial screen, swipe to dismiss
- Full Screen (.fullScreenCover) → Complete takeover
- Popover (iPad) → Contextual floating panel
- Alert → Critical information, requires action

Components

Buttons

Lists

List {
    Section("Section Header") {
        ForEach(items) { item in
            HStack {
                Image(systemName: item.icon)
                VStack(alignment: .leading) {
                    Text(item.title)
                    Text(item.subtitle)
                        .foregroundStyle(.secondary)
                }
            }
        }
    }
}

• Use standard row height (44pt minimum)
• Group related items in sections
• Provide swipe actions for common tasks
• Support pull-to-refresh when appropriate

Text Fields

┌──────────────────────────────────┐
│  Label                           │
│  ┌────────────────────────────┐  │
│  │ Placeholder text           │  │
│  └────────────────────────────┘  │
│  Helper text or error message    │
└──────────────────────────────────┘

• Clear button on right
• Show appropriate keyboard type
• Support password autofill
• Indicate required fields

Colors

System Colors

// Semantic colors (adapt to light/dark mode)
Color.primary      // Primary text
Color.secondary    // Secondary text
Color.accentColor  // App tint color

// System colors
Color.red          // #FF3B30
Color.orange       // #FF9500
Color.yellow       // #FFCC00
Color.green        // #34C759
Color.mint         // #00C7BE
Color.teal         // #30B0C7
Color.cyan         // #32ADE6
Color.blue         // #007AFF
Color.indigo       // #5856D6
Color.purple       // #AF52DE
Color.pink         // #FF2D55
Color.brown        // #A2845E

Dark Mode

// Backgrounds
Color(.systemBackground)       // White / Black
Color(.secondarySystemBackground)  // Light gray / Dark gray
Color(.tertiarySystemBackground)   // Darker variations

// Always use semantic colors for automatic adaptation

2025: Liquid Glass

Apple's new design language introduces:

Characteristics

• Translucency: Background content visible through controls
• Depth: Floating elements with subtle shadows
• Dynamic materials: Responsive to underlying content
• Vibrancy: Text and icons adjust based on background

Usage

// Apply glass effect
.background(.ultraThinMaterial)
.background(.regularMaterial)
.background(.thickMaterial)

Icons

SF Symbols

• Use SF Symbols for consistency
• Match symbol weight to text weight
• Use rendering modes appropriately:
• Monochrome: Single color
• Hierarchical: Primary/secondary emphasis
• Palette: Custom colors
• Multicolor: Original colors

Image(systemName: "heart.fill")
    .symbolRenderingMode(.hierarchical)
    .foregroundStyle(.red)

Gestures

Standard Gestures

Best Practices

• Always provide alternative for gestures
• Don't override system gestures
• Provide haptic feedback for actions

Accessibility

Requirements

• [ ] VoiceOver labels for all interactive elements
• [ ] Dynamic Type support (up to xxxLarge)
• [ ] Sufficient color contrast (4.5:1 minimum)
• [ ] Reduce Motion support
• [ ] High Contrast mode support
• [ ] Button Shapes support

Button("Submit") {
    submit()
}
.accessibilityLabel("Submit form")
.accessibilityHint("Double tap to submit your information")

Device Considerations

Screen Sizes (Points)

Design Recommendations

• Start with iPhone 14 (390×844)
• Use Auto Layout / SwiftUI for adaptivity
• Test on smallest and largest devices
• Consider landscape orientation

Material Design 3 Guidelines

Quick reference for Android app design following Google's Material Design 3 (2025).

Design Principles

Material You

• Personal: Adapts to user preferences
• Adaptive: Responds to device and context
• Expressive: Communicates brand and emotion

Core Concepts

• Surfaces over layers
• Motion with meaning
• Color from user wallpaper
• Accessibility built-in

Typography

Roboto Font Family

Font Scaling

// Support system font scaling
Text(
    text = "Hello",
    style = MaterialTheme.typography.bodyLarge
)

Color System

Dynamic Color (Material You)

Material You extracts colors from user's wallpaper:

┌─────────────────────────────────────────┐
│            User Wallpaper                │
│               🖼️                         │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Primary    Secondary   Tertiary        │
│  ████████   ████████   ████████         │
│                                         │
│  Neutral    NeutralVar  Error           │
│  ████████   ████████   ████████         │
└─────────────────────────────────────────┘

Color Roles

Tonal Palette

Tonal values: 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100

0   = Black
100 = White

Light mode typically uses: 40 (primary), 90 (container)
Dark mode typically uses: 80 (primary), 30 (container)

Elevation

Surface Tones

Material 3 uses tonal elevation instead of shadows:

┌────────────────────────────────────────────┐
│ Level  │ Elevation │ Tonal Offset          │
├────────────────────────────────────────────┤
│ 0      │ 0dp       │ Surface color         │
│ 1      │ 1dp       │ +5% primary           │
│ 2      │ 3dp       │ +8% primary           │
│ 3      │ 6dp       │ +11% primary          │
│ 4      │ 8dp       │ +12% primary          │
│ 5      │ 12dp      │ +14% primary          │
└────────────────────────────────────────────┘

When to Use Elevation

• Level 0: Page backgrounds
• Level 1: Cards, sheets
• Level 2: Navigation bars
• Level 3: FABs, dialogs
• Level 4: Search bars
• Level 5: Snackbars, tooltips

Shape

Shape Scale

Shape Family

// Define shapes
val shapes = Shapes(
    extraSmall = RoundedCornerShape(4.dp),
    small = RoundedCornerShape(8.dp),
    medium = RoundedCornerShape(12.dp),
    large = RoundedCornerShape(16.dp),
    extraLarge = RoundedCornerShape(28.dp)
)

Components

Buttons

// Compose examples
Button(onClick = {}) { Text("Filled") }
FilledTonalButton(onClick = {}) { Text("Tonal") }
OutlinedButton(onClick = {}) { Text("Outlined") }
TextButton(onClick = {}) { Text("Text") }
ElevatedButton(onClick = {}) { Text("Elevated") }

FAB (Floating Action Button)

┌─────────────────────────────────┐
│ Size    │ Diameter │ Icon Size │
├─────────────────────────────────┤
│ Small   │ 40dp     │ 24dp      │
│ Regular │ 56dp     │ 24dp      │
│ Large   │ 96dp     │ 36dp      │
│ Extended│ 56dp h   │ 24dp      │
└─────────────────────────────────┘

Position: Bottom right, 16dp from edges

Text Fields

┌──────────────────────────────────────────┐
│  Filled (default)                        │
│  ┌────────────────────────────────────┐  │
│  │ Label                              │  │
│  │ Input text                         │  │
│  │ ─────────────────────────────────  │  │
│  │ Supporting text                    │  │
│  └────────────────────────────────────┘  │
│                                          │
│  Outlined                                │
│  ┌────────────────────────────────────┐  │
│  │ Label ─────────────────────────────│  │
│  │ Input text                         │  │
│  │ ─────────────────────────────────  │  │
│  │ Supporting text                    │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

Cards

Chips

Navigation

Bottom Navigation

┌──────────────────────────────────────────┐
│              Content                      │
├──────────────────────────────────────────┤
│   🏠        🔍        ❤️        👤      │
│  Home    Search   Favorites  Profile     │
└──────────────────────────────────────────┘
Height: 80dp

• 3-5 destinations
• Icon + label always visible
• Active indicator pill around icon

Navigation Rail (Tablets)

┌─────┬───────────────────────────────────┐
│ ≡   │                                   │
│     │                                   │
│ 🏠  │                                   │
│Home │          Content                  │
│     │                                   │
│ 🔍  │                                   │
│Srch │                                   │
│     │                                   │
│ ❤️  │                                   │
│Favs │                                   │
└─────┴───────────────────────────────────┘
Width: 80dp

Navigation Drawer

┌──────────────────────────┬──────────────┐
│                          │              │
│  App Name                │              │
│  ─────────────────────   │              │
│                          │              │
│  🏠  Home                │    Content   │
│  ●══════════════●        │              │
│                          │              │
│  📁  Files               │              │
│  👥  Shared              │              │
│  ⭐  Starred             │              │
│                          │              │
│  ─────────────────────   │              │
│                          │              │
│  ⚙️  Settings            │              │
│                          │              │
└──────────────────────────┴──────────────┘
Width: 360dp max

Top App Bar

Motion

Duration Scale

Easing

// Standard easing
val emphasized = CubicBezier(0.2f, 0f, 0f, 1f)
val emphasizedDecelerate = CubicBezier(0.05f, 0.7f, 0.1f, 1f)
val emphasizedAccelerate = CubicBezier(0.3f, 0f, 0.8f, 0.15f)

// Linear (rarely used)
val linear = CubicBezier(0f, 0f, 1f, 1f)

2025: Material 3 Expressive

New Features

• Springy Motion: Physics-based animations
• Bolder Typography: More expressive type choices
• Emotional Connection: Design that makes users feel
• Personal Expression: Beyond wallpaper colors

Recommendations

✓ Use dynamic color for personalization
✓ Add meaningful microinteractions
✓ Consider emotional impact of choices
✓ Balance expression with usability

Accessibility

Touch Targets

• Minimum: 48×48dp
• Visual can be smaller, touch area must be 48dp

Contrast

• Normal text: 4.5:1 minimum
• Large text (18sp+): 3:1 minimum
• UI components: 3:1 minimum

Focus

• Visible focus indicator for all interactive elements
• Logical focus order (left-to-right, top-to-bottom)

Screen Readers

Modifier.semantics {
    contentDescription = "Add item to cart"
    stateDescription = "Selected"
}

Layout

Grid System

Canonical Layouts

## List-Detail
For master-detail patterns on tablets
├── List pane (1/3 width)
└── Detail pane (2/3 width)

## Supporting Panel
For content with auxiliary info
├── Main content (2/3 width)
└── Side panel (1/3 width)

## Feed
For scrolling content
└── Single column, card-based

Resources

• Material Design 3
• Material Theme Builder
• Material Components

Design System Template

Use this template to define your app's design system.

App Information

---

Color Tokens

Primary Colors

/* Primary */
--color-primary: #[HEX];
--color-primary-light: #[HEX];
--color-primary-dark: #[HEX];
--color-on-primary: #[HEX];

/* Secondary */
--color-secondary: #[HEX];
--color-secondary-light: #[HEX];
--color-secondary-dark: #[HEX];
--color-on-secondary: #[HEX];

/* Tertiary (Optional) */
--color-tertiary: #[HEX];
--color-on-tertiary: #[HEX];

Background & Surface

/* Light Mode */
--color-background: #FFFFFF;
--color-surface: #F5F5F5;
--color-surface-variant: #E8E8E8;

/* Dark Mode */
--color-background-dark: #121212;
--color-surface-dark: #1E1E1E;
--color-surface-variant-dark: #2C2C2C;

Text Colors

/* Light Mode */
--color-text-primary: #1A1A1A;
--color-text-secondary: #666666;
--color-text-disabled: #999999;
--color-text-hint: #AAAAAA;

/* Dark Mode */
--color-text-primary-dark: #FFFFFF;
--color-text-secondary-dark: #B3B3B3;
--color-text-disabled-dark: #666666;

Semantic Colors

/* Status */
--color-error: #D32F2F;
--color-error-light: #FFEBEE;
--color-on-error: #FFFFFF;

--color-warning: #F9A825;
--color-warning-light: #FFF8E1;
--color-on-warning: #000000;

--color-success: #388E3C;
--color-success-light: #E8F5E9;
--color-on-success: #FFFFFF;

--color-info: #1976D2;
--color-info-light: #E3F2FD;
--color-on-info: #FFFFFF;

Outline & Divider

--color-outline: #E0E0E0;
--color-outline-variant: #BDBDBD;
--color-divider: #EEEEEE;

---

Typography

Font Families

/* iOS */
--font-family-primary: 'SF Pro Text', -apple-system, sans-serif;
--font-family-display: 'SF Pro Display', -apple-system, sans-serif;

/* Android */
--font-family-primary: 'Roboto', sans-serif;
--font-family-display: 'Roboto', sans-serif;

/* Cross-platform alternative */
--font-family-primary: 'Inter', system-ui, sans-serif;

Type Scale

CSS Variables

--font-size-display-large: 57px;
--font-size-display-medium: 45px;
--font-size-display-small: 36px;
--font-size-headline-large: 32px;
--font-size-headline-medium: 28px;
--font-size-headline-small: 24px;
--font-size-title-large: 22px;
--font-size-title-medium: 16px;
--font-size-title-small: 14px;
--font-size-body-large: 16px;
--font-size-body-medium: 14px;
--font-size-body-small: 12px;
--font-size-label-large: 14px;
--font-size-label-medium: 12px;
--font-size-label-small: 11px;

---

Spacing

Base Unit

--spacing-unit: 8px;

Spacing Scale

--spacing-0: 0px;
--spacing-1: 4px;   /* 0.5 units */
--spacing-2: 8px;   /* 1 unit */
--spacing-3: 12px;  /* 1.5 units */
--spacing-4: 16px;  /* 2 units */
--spacing-5: 20px;  /* 2.5 units */
--spacing-6: 24px;  /* 3 units */
--spacing-8: 32px;  /* 4 units */
--spacing-10: 40px; /* 5 units */
--spacing-12: 48px; /* 6 units */
--spacing-16: 64px; /* 8 units */
--spacing-20: 80px; /* 10 units */

Layout Spacing

/* Screen margins */
--layout-margin-mobile: 16px;
--layout-margin-tablet: 24px;
--layout-margin-desktop: 32px;

/* Content spacing */
--layout-gutter: 16px;
--layout-section-gap: 32px;
--layout-card-gap: 16px;

/* Component internal padding */
--padding-button-horizontal: 24px;
--padding-button-vertical: 12px;
--padding-card: 16px;
--padding-input: 12px;

---

Border Radius

--radius-none: 0px;
--radius-xs: 4px;
--radius-sm: 8px;
--radius-md: 12px;
--radius-lg: 16px;
--radius-xl: 24px;
--radius-2xl: 32px;
--radius-full: 9999px;

Component Defaults

--radius-button: 8px;
--radius-button-pill: 9999px;
--radius-card: 12px;
--radius-input: 8px;
--radius-dialog: 16px;
--radius-fab: 16px;
--radius-chip: 8px;
--radius-avatar: 9999px;

---

Shadows & Elevation

Light Mode

--shadow-1: 0 1px 2px rgba(0, 0, 0, 0.05);
--shadow-2: 0 1px 3px rgba(0, 0, 0, 0.1), 0 1px 2px rgba(0, 0, 0, 0.06);
--shadow-3: 0 4px 6px rgba(0, 0, 0, 0.1), 0 2px 4px rgba(0, 0, 0, 0.06);
--shadow-4: 0 10px 15px rgba(0, 0, 0, 0.1), 0 4px 6px rgba(0, 0, 0, 0.05);
--shadow-5: 0 20px 25px rgba(0, 0, 0, 0.1), 0 10px 10px rgba(0, 0, 0, 0.04);

Dark Mode (Tonal Elevation)

--elevation-1: linear-gradient(0deg, rgba(255,255,255,0.05), rgba(255,255,255,0.05));
--elevation-2: linear-gradient(0deg, rgba(255,255,255,0.08), rgba(255,255,255,0.08));
--elevation-3: linear-gradient(0deg, rgba(255,255,255,0.11), rgba(255,255,255,0.11));
--elevation-4: linear-gradient(0deg, rgba(255,255,255,0.12), rgba(255,255,255,0.12));
--elevation-5: linear-gradient(0deg, rgba(255,255,255,0.14), rgba(255,255,255,0.14));

Component Elevation

---

Motion

Duration

--duration-instant: 50ms;
--duration-fast: 100ms;
--duration-normal: 200ms;
--duration-slow: 300ms;
--duration-slower: 400ms;
--duration-slowest: 500ms;

Easing

--easing-standard: cubic-bezier(0.4, 0.0, 0.2, 1);
--easing-decelerate: cubic-bezier(0.0, 0.0, 0.2, 1);
--easing-accelerate: cubic-bezier(0.4, 0.0, 1, 1);
--easing-sharp: cubic-bezier(0.4, 0.0, 0.6, 1);
--easing-spring: cubic-bezier(0.175, 0.885, 0.32, 1.275);

Common Transitions

--transition-color: color var(--duration-fast) var(--easing-standard);
--transition-background: background-color var(--duration-fast) var(--easing-standard);
--transition-transform: transform var(--duration-normal) var(--easing-standard);
--transition-opacity: opacity var(--duration-normal) var(--easing-standard);
--transition-all: all var(--duration-normal) var(--easing-standard);

---

Components

Buttons

States

Sizes

---

Icons

Size Scale

--icon-xs: 16px;
--icon-sm: 20px;
--icon-md: 24px;
--icon-lg: 32px;
--icon-xl: 48px;

Icon Sets

• iOS: SF Symbols
• Android: Material Symbols
• Cross-platform: [Your chosen set]

---

Touch Targets

/* Minimum sizes */
--touch-target-min: 44px;  /* iOS */
--touch-target-min-android: 48px;  /* Android */

/* Recommended */
--touch-target-recommended: 48px;

/* Spacing between targets */
--touch-target-gap: 8px;

---

Breakpoints

--breakpoint-mobile: 0px;      /* 0-599 */
--breakpoint-tablet: 600px;    /* 600-904 */
--breakpoint-laptop: 905px;    /* 905-1239 */
--breakpoint-desktop: 1240px;  /* 1240-1439 */
--breakpoint-wide: 1440px;     /* 1440+ */

---

Z-Index Scale

--z-base: 0;
--z-dropdown: 100;
--z-sticky: 200;
--z-overlay: 300;
--z-modal: 400;
--z-popover: 500;
--z-toast: 600;
--z-tooltip: 700;

---

Checklist

Before using this design system, verify:

• [ ] All color tokens defined
• [ ] Light and dark mode variants
• [ ] Typography scale complete
• [ ] Spacing scale consistent
• [ ] All component states defined
• [ ] Accessibility requirements met (contrast, touch targets)
• [ ] Motion tokens defined
• [ ] Breakpoints defined
• [ ] Design tool file linked
• [ ] Documentation complete