# Theming

The app supports comprehensive theming to match user preferences and system settings.

## Theme Structure

```
Theme
├── Color Scheme (light/dark)
├── Typography
├── Component Themes
└── Custom Extensions
```

## Color Schemes

### Light Theme Colors

| Color Role | Usage |
|------------|-------|
| primary | Main accent color, active elements |
| onPrimary | Text/icons on primary color |
| surface | Background color |
| onSurface | Text on surface |
| surfaceContainer | Card backgrounds |
| surfaceContainerHigh | Elevated surfaces |
| surfaceContainerHighest | Highest elevation |
| outline | Borders, dividers |
| error | Error states |

### Dark Theme Colors

Same roles as light theme but with dark-appropriate values:
- Surface colors are dark grays
- Primary colors may be adjusted for contrast
- Text colors are light

### Surface Color Scale

```
Light Mode:
surfaceContainerLowest  → #FFFFFF (white)
surfaceContainerLow     → #F3F3F3
surfaceContainer        → #EEEEEE
surfaceContainerHigh    → #E8E8E8
surfaceContainerHighest → #E2E2E2
surface                 → #F9F9F9
surfaceDim             → #DADADA
surfaceBright          → #F9F9F9

Dark Mode:
surfaceContainerLowest  → #0E0E0E
surfaceContainerLow     → #1B1B1B
surfaceContainer        → #1F1F1F
surfaceContainerHigh    → #242424
surfaceContainerHighest → #2E2E2E
surface                 → #131313
surfaceDim             → #131313
surfaceBright          → #353535
```

## Theme Modes

### System (Default)

Follows device system setting:
- Automatically switches with system
- Respects scheduled dark mode

### Light Mode

Always uses light theme:
- Bright backgrounds
- Dark text
- Suitable for outdoor use

### Dark Mode

Always uses dark theme:
- Dark backgrounds
- Light text
- Reduces eye strain at night
- Saves battery on OLED screens

## Primary Color Options

The app offers color presets:

| Name | Primary Color | Usage |
|------|---------------|-------|
| Default | Blue | Standard app color |
| Red | #F44336 | Bold accent |
| Green | #4CAF50 | Nature theme |
| Purple | #9C27B0 | Elegant |
| Orange | #FF9800 | Warm |
| Pink | #E91E63 | Playful |
| Teal | #009688 | Cool |
| Custom | User-defined | Any color |

## Dynamic Theme

When enabled (and supported by platform):

1. Extract colors from wallpaper
2. Generate harmonious palette
3. Apply as app theme

**Platform Support:**
- Android 12+ (Material You)
- iOS (limited support)

## Colorful Interface

### Enabled (Default)

Primary color applied to:
- App bar titles
- Active navigation items
- Buttons
- Links
- Accent elements

### Disabled

More subtle appearance:
- Neutral app bars
- Reduced color usage
- Focus on content

## Typography

### Font Family

Default: "GoogleSans" (or system font for unsupported locales)

**Unsupported Locales:**
Languages that need special character support fall back to system fonts.

### Text Styles

| Style | Size | Weight | Usage |
|-------|------|--------|-------|
| displayLarge | 18 | SemiBold | Large headings |
| displayMedium | 14 | SemiBold | Medium headings |
| displaySmall | 12 | SemiBold | Small headings |
| titleLarge | 26 | SemiBold | Page titles |
| titleMedium | 18 | SemiBold | Section titles |
| titleSmall | 16 | SemiBold | Card titles |
| bodyLarge | 16 | Normal | Main text |
| bodyMedium | 14 | Normal | Body text |
| bodySmall | 12 | Normal | Captions |

## Component Themes

### App Bar

```
AppBarTheme:
- titleTextStyle: Primary color, 18px, SemiBold
- backgroundColor: Surface color
- foregroundColor: Primary color
- elevation: 0 (flat)
- centerTitle: true
```

### Navigation Bar

```
NavigationBarTheme:
- backgroundColor: Surface container (dark) or surface (light)
- labelTextStyle: 14px, Medium weight
- indicatorColor: Primary with opacity
```

### Buttons

**Elevated Button:**
```
- backgroundColor: Primary color
- foregroundColor: White (light) or Black (dark)
- shape: Rounded rectangle
```

### Input Fields

```
InputDecorationTheme:
- border: Rounded (15px radius)
- focusedBorder: Primary color
- enabledBorder: Outline variant color
- labelStyle: Primary color
```

### Cards/Dialogs

```
- backgroundColor: Surface container
- shape: Rounded corners (10px)
- elevation: Subtle shadow
```

### Chips

```
ChipTheme:
- side: No border
- shape: Stadium (pill shape)
```

### Progress Indicators

```
ProgressIndicatorTheme:
- Circular: Gap at 3px
- Linear: Rounded track
```

### Bottom Sheet

```
BottomSheetTheme:
- backgroundColor: Surface container
- shape: Rounded top corners
```

### Snackbar

```
SnackBarTheme:
- backgroundColor: Surface container highest
- contentTextStyle: Primary color, bold
```

## Custom Theme Extensions

### Secondary Surface Color

Additional surface variant for secondary text:
```
onSurfaceSecondary: Slightly faded text color
```

Used for:
- Timestamps
- Secondary labels
- Placeholder text

## Decolorized Surfaces

To prevent primary color from tinting surfaces:

The app uses static surface colors instead of seed-generated ones. This ensures:
- Neutral backgrounds
- Consistent appearance
- No unexpected color shifts

## Theme Application

### Build Theme Data

```
Inputs:
- ColorScheme (light or dark)
- Locale (for font selection)

Process:
1. Select base color scheme
2. Apply typography with locale font
3. Configure component themes
4. Add custom extensions

Output:
Complete theme data for the app
```

### Theme Switching

```
User changes theme setting
       │
       ▼
Store new preference
       │
       ▼
Rebuild theme data
       │
       ▼
Notify UI to rebuild
       │
       ▼
App repaints with new theme
```

## Accessibility

### Contrast Ratios

Theme colors maintain WCAG contrast ratios:
- Normal text: 4.5:1 minimum
- Large text: 3:1 minimum

### Color Independence

UI doesn't rely solely on color:
- Icons accompany colors
- Text labels included
- Patterns/shapes differentiate

### System Font Scaling

Typography respects system text size settings.

## Platform Considerations

### Android

- Material 3 design language
- Dynamic color extraction (12+)
- Edge-to-edge content
- System navigation theming

### iOS

- Cupertino adaptations where needed
- System font for locales
- Safe area handling
- Native-feeling interactions

---

[Previous: UI Components](ui-components.md) | [Back to Index](README.md)