# Visual Design Guidelines

Detailed specifications for colors, typography, spacing, elevation, and shapes in Material Design 3.

## Color System

### Color Roles (Tokens)

Material Design 3 uses a token-based color system with three accent groups:

| Role | Usage |
|------|-------|
| **Primary** | Key components, FAB, prominent buttons |
| **Secondary** | Less prominent components, filters, chips |
| **Tertiary** | Accent, complementary elements |
| **Error** | Error states, destructive actions |
| **Surface** | Backgrounds, cards, dialogs |

Each role includes variants: base color, onColor, container, onContainer.

### Color Contrast Requirements

| Element | Minimum Contrast Ratio | Notes |
|---------|----------------------|-------|
| Body text | **4.5:1** | WCAG AA compliance |
| Large text (18sp+) | **3:1** | 14sp bold also qualifies |
| UI components | **3:1** | Icons, borders, controls |
| Focus indicators | **3:1** | Must be clearly visible |

### Recommended Color Palettes

#### Modern Professional (Business Apps)

| Role | Color | Name |
|------|-------|------|
| Primary | #1976D2 | Blue 700 |
| Secondary | #455A64 | Blue Grey 700 |
| Tertiary | #00897B | Teal 600 |
| Background | #FAFAFA | Grey 50 |

#### Vibrant & Playful (Consumer Apps)

| Role | Color | Name |
|------|-------|------|
| Primary | #6200EE | Deep Purple |
| Secondary | #03DAC6 | Teal Accent |
| Tertiary | #FF5722 | Deep Orange |
| Background | #FFFFFF | White |

#### Dark & Elegant (Premium Apps)

| Role | Color | Name |
|------|-------|------|
| Primary | #BB86FC | Purple 200 |
| Secondary | #03DAC6 | Teal 200 |
| Tertiary | #CF6679 | Red 200 |
| Background | #121212 | Dark surface |

#### Nature & Wellness (Health Apps)

| Role | Color | Name |
|------|-------|------|
| Primary | #4CAF50 | Green 500 |
| Secondary | #8BC34A | Light Green 500 |
| Tertiary | #FFEB3B | Yellow 500 |
| Background | #F1F8E9 | Light Green 50 |

#### Finance & Trust (Banking Apps)

| Role | Color | Name |
|------|-------|------|
| Primary | #00695C | Teal 800 |
| Secondary | #37474F | Blue Grey 800 |
| Tertiary | #FFC107 | Amber 500 |
| Background | #ECEFF1 | Blue Grey 50 |

### Dark Theme Requirements

- Background: #121212 or darker
- Surface colors use elevation-based tonal overlay
- Primary colors should be lighter variants (200-300 range)
- Maintain contrast ratios in dark mode
- Test all states (hover, focus, pressed) in dark mode

## Typography System

### Type Scale

| Style | Size | Weight | Line Height | Usage |
|-------|------|--------|-------------|-------|
| Display Large | 57sp | 400 | 64sp | Hero text |
| Display Medium | 45sp | 400 | 52sp | Large headers |
| Display Small | 36sp | 400 | 44sp | Section headers |
| Headline Large | 32sp | 400 | 40sp | Screen titles |
| Headline Medium | 28sp | 400 | 36sp | Subsection titles |
| Headline Small | 24sp | 400 | 32sp | Card titles |
| Title Large | 22sp | 400 | 28sp | App bar titles |
| Title Medium | 16sp | 500 | 24sp | List item titles |
| Title Small | 14sp | 500 | 20sp | Tabs |
| Body Large | 16sp | 400 | 24sp | Primary body text |
| Body Medium | 14sp | 400 | 20sp | Secondary body text |
| Body Small | 12sp | 400 | 16sp | Captions |
| Label Large | 14sp | 500 | 20sp | Button text |
| Label Medium | 12sp | 500 | 16sp | Navigation labels |
| Label Small | 11sp | 500 | 16sp | Badges |

### Recommended Fonts

| Category | Fonts |
|----------|-------|
| Primary | Roboto (system default) |
| Display | Roboto Serif, Google Sans |
| Monospace | Roboto Mono, JetBrains Mono |

### Text Readability

- **Line length**: 45-75 characters per line (including spaces)
- **Paragraph spacing**: 1.5x line height between paragraphs
- **Letter spacing**: Use default unless brand requires adjustment
- **Text alignment**: Left-aligned for body text (LTR languages)

## Spacing & Layout

### 8dp Grid System

All spacing values should be multiples of 8dp (with 4dp for fine adjustments).

| Token | Value | Usage |
|-------|-------|-------|
| xs | 4dp | Icon padding, fine adjustments |
| sm | 8dp | Tight spacing, inline elements |
| md | 16dp | Default padding, card content |
| lg | 24dp | Section spacing |
| xl | 32dp | Large gaps, group separation |
| xxl | 48dp | Screen margins, major sections |

### Component Dimensions

| Component | Height | Min Width | Notes |
|-----------|--------|-----------|-------|
| Button | 40dp | 64dp | Touch target 48dp |
| FAB | 56dp | 56dp | Standard size |
| Mini FAB | 40dp | 40dp | Secondary actions |
| Extended FAB | 56dp | 80dp | With text label |
| Text Field | 56dp | 280dp | Including label |
| App Bar | 64dp | - | Top app bar |
| Bottom Nav | 80dp | - | With labels |
| Nav Rail | - | 80dp | Tablet/desktop |
| List Item | 56-88dp | - | Depends on content |
| Chip | 32dp | - | Filter/action chips |

### Touch Targets

| Type | Size | Notes |
|------|------|-------|
| Minimum | 48 × 48dp | WCAG requirement |
| Recommended | 56 × 56dp | Primary actions |
| Kids apps | 56dp+ | Larger for motor skills |
| Spacing | 8dp minimum | Between adjacent targets |

## Elevation & Shadows

### Elevation Levels

| Level | Elevation | Usage |
|-------|-----------|-------|
| Level 0 | 0dp | Flat surfaces |
| Level 1 | 1dp | Cards, elevated buttons |
| Level 2 | 3dp | FAB (resting), raised elements |
| Level 3 | 6dp | Navigation drawer, bottom sheet |
| Level 4 | 8dp | FAB (pressed), menus |
| Level 5 | 12dp | Dialogs, modal surfaces |

### Shadow Guidelines

- Use elevation consistently for same component types
- Higher elevation = more important/prominent
- In dark theme, use surface tint instead of shadows
- Avoid excessive elevation (keeps UI grounded)

## Shape System

### Corner Radius

| Size | Radius | Usage |
|------|--------|-------|
| None | 0dp | Sharp edges, dividers |
| Extra Small | 4dp | Badges, small chips |
| Small | 8dp | Buttons, chips, small cards |
| Medium | 12dp | Cards, dialogs, text fields |
| Large | 16dp | FAB, bottom sheets |
| Extra Large | 28dp | Large sheets, expanded cards |
| Full | 50% | Pills, avatars, circular buttons |

### M3 Expressive Shapes

Material 3 Expressive introduces 35 new decorative shapes:
- Organic curves
- Asymmetric corners
- Cut corners
- Scalloped edges

Use sparingly for brand differentiation and visual interest.

### Shape Consistency Rules

- Same component type = same shape
- Related components should share shape family
- Don't mix too many shape styles on one screen
- Consider shape in dark/light theme transitions

## Icons

### Size Specifications

| Size | Dimensions | Usage |
|------|------------|-------|
| Small | 20 × 20dp | Compact UI, inline |
| Standard | 24 × 24dp | Default for most uses |
| Large | 40 × 40dp | Emphasis, empty states |

### Icon Guidelines

- **Touch target**: Always wrap in 48dp minimum clickable area
- **Style**: Outlined (default), Filled (selected/active states)
- **Stroke width**: 2dp for outlined icons
- **Optical alignment**: May need visual adjustments
- **Color**: Use semantic colors (primary, error, etc.)

### Recommended Icon Sets

| Set | Usage |
|-----|-------|
| Material Symbols | Recommended, variable font support |
| Material Icons | Legacy, still widely used |

### Adaptive Icons (App Icon)

| Property | Value |
|----------|-------|
| Canvas size | 108 × 108dp |
| Safe zone | 66 × 66dp (centered circle) |
| Logo size | 48-66dp |
| Max display | 72 × 72dp |
| Layers | Foreground + Background (both 108dp) |
| Android 13+ | Include monochrome layer for theming |