immish/docs/theming.md

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 | Back to Index