theme-system by sampaio-tech/ios-design-system

Theme System Overview

This iOS Design System uses a centralized theme system with 8 color palettes, 22 typography styles, and automatic light/dark mode support.

Theme Access Pattern

Always access theme via context:

final theme = IosTheme.of(context);

Color Systems

1. System Colors (`theme.defaultColors`)

Standard iOS colors that adapt to brightness:

systemBlue, systemRed, systemGreen, systemYellow, systemOrange
systemPink, systemPurple, systemTeal, systemIndigo
systemGray01 through systemGray06
systemBlack, systemWhite

2. Label Colors (`theme.defaultLabelColors`)

Semantic text colors:

primary - Main text (100% opacity)
secondary - Secondary text (60% opacity)
tertiary - Disabled text (30% opacity)
quartenary - Placeholder (18% opacity)

3. Fill Colors (`theme.defaultFillColors`)

Background fills for UI elements:

primary, secondary, tertiary, quartenary
Auto-adapting opacity for light/dark

4. System Backgrounds (`theme.defaultSystemBackgroundsColors`)

Screen-level backgrounds:

primaryLight, primaryDarkBase, primaryDarkElevated
secondaryLight, secondaryDarkBase, secondaryDarkElevated
tertiaryLight, tertiaryDarkBase, tertiaryDarkElevated

5. Grouped Backgrounds (`theme.defaultSystemGroupedBackgroundsColors`)

For Settings-style grouped lists (same structure as System Backgrounds)

6. Separator Colors (`theme.defaultSeparatorColors`)

opaque - Prominent borders
nonOpaque - List dividers (default)

7. System Materials

Colors for blur effects:

systemMaterialsBackgroundsColors
systemMaterialsLabelsTextColors
systemMaterialsFillColors

8. App Decorations

Pre-built themes:

weatherDecorations - Weather app gradients
stocksDecorations - Stocks dark theme
neutralMusicDecorations - Apple Music theme
neutralPodcastDecorations - Podcast theme
appStoreDecorations - App Store theme
booksDecorations - Books theme

Typography System

22 text styles using SF Pro Text font:

Titles

largeTitleRegular/Bold - 34pt (Page headers)
title1Regular/Bold - 28pt
title2Regular/Bold - 22pt
title3Regular/Bold - 20pt

Body

headlineRegular/Bold - 17pt semibold
bodyRegular/Bold - 17pt (default text)
calloutRegular/Bold - 16pt
subheadlineRegular/Bold - 15pt

Small

footnoteRegular/Bold - 13pt
caption1Regular/Bold - 12pt
caption2Regular/Bold - 11pt (smallest)

Usage Examples

Basic Theme Access

@override
Widget build(BuildContext context) {
  final theme = IosTheme.of(context);

  return Container(
    color: theme.defaultColors.systemBlue,
    child: Text(
      'Hello',
      style: theme.typography.bodyRegular.copyWith(
        color: theme.defaultLabelColors.primary,
      ),
    ),
  );
}

Brightness-Specific Styling

final backgroundColor = switch (theme) {
  IosLightThemeData() => theme.defaultSystemBackgroundsColors.primaryLight,
  IosDarkThemeData() => theme.defaultSystemBackgroundsColors.primaryDarkBase,
};

Theme Injection

void main() {
  runApp(
    IosAnimatedTheme(
      data: IosLightThemeData(), // or IosDarkThemeData()
      duration: Duration(milliseconds: 180),
      child: CupertinoApp(home: MyApp()),
    ),
  );
}

Critical Rules

ALWAYS access via IosTheme.of(context)
NEVER hardcode colors (Color(0x...) or Colors.*)
NEVER hardcode text styles (use theme.typography.*)
ALWAYS test both light and dark modes
ALWAYS use theme for ALL visual properties

Common Theme Patterns

Primary action color:

theme.defaultColors.systemBlue

Main text:

theme.defaultLabelColors.primary

Button background:

theme.defaultFillColors.secondary

Screen background:

theme.defaultSystemBackgroundsColors.primaryLight // light mode
theme.defaultSystemBackgroundsColors.primaryDarkBase // dark mode

Divider:

theme.defaultSeparatorColors.nonOpaque

File Locations

Theme implementation: /lib/src/theme/settings/theme.dart
Colors: /lib/src/theme/colors/default.dart
Typography: /lib/src/theme/typography/typography.dart
Constants: /lib/src/theme/settings/constants.dart

theme-system