332 lines
6.2 KiB
Markdown
332 lines
6.2 KiB
Markdown
# 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)
|