0
# Material Theming
1

2
Comprehensive theming system that adapts Material Design principles to iOS platform conventions while maintaining design consistency across platforms.
3

4
## Capabilities
5

6
### MaterialTheme
7

8
Main theming composable that provides colors, typography, and shapes to child components with iOS-specific adaptations.
9

10
```kotlin { .api }
11
/**
12
 * MaterialTheme defines the styling principles from the Material Design specification
13
 * This component also provides theme values to child components through composition locals
14
 * @param colors A complete definition of the Material Design color palette
15
 * @param typography A set of text styles to be used as this theme's typography system
16
 * @param shapes A set of corner shapes to be used as this theme's shape system
17
 * @param content The content inheriting this theme
18
 */
19
@Composable
20
fun MaterialTheme(
21
    colors: Colors = MaterialTheme.colors,
22
    typography: Typography = MaterialTheme.typography,
23
    shapes: Shapes = MaterialTheme.shapes,
24
    content: @Composable () -> Unit
25
)
26
```
27

28
**Usage Examples:**
29

30
```kotlin
31
// Basic theme setup
32
MaterialTheme {
33
    // Your app content
34
    MyAppContent()
35
}
36

37
// Custom theme with iOS-appropriate colors
38
MaterialTheme(
39
    colors = lightColors(
40
        primary = Color(0xFF007AFF),      // iOS blue
41
        secondary = Color(0xFF34C759),    // iOS green
42
        surface = Color(0xFFF2F2F7),      // iOS system background
43
        background = Color(0xFFFFFFFF)
44
    ),
45
    typography = Typography(
46
        // iOS-friendly typography scale
47
    )
48
) {
49
    MyAppContent()
50
}
51

52
// Dark theme for iOS
53
MaterialTheme(
54
    colors = darkColors(
55
        primary = Color(0xFF0A84FF),      // iOS dark blue
56
        secondary = Color(0xFF30D158),    // iOS dark green
57
        surface = Color(0xFF1C1C1E),      // iOS dark surface
58
        background = Color(0xFF000000)
59
    )
60
) {
61
    MyAppContent()
62
}
63
```
64

65
### Colors
66

67
Material color palette data class with iOS platform adaptations and accessibility considerations.
68

69
```kotlin { .api }
70
/**
71
 * A color scheme holds all the named color parameters for a Material theme
72
 * Material components use these color parameters to style themselves
73
 * @param primary The primary color is the color displayed most frequently across your app's screens and components
74
 * @param primaryVariant The primary variant color is used to distinguish elements using primary colors
75
 * @param secondary The secondary color provides more ways to accent and distinguish your product
76
 * @param secondaryVariant The secondary variant color is used to distinguish elements using secondary colors  
77
 * @param background The background color appears behind scrollable content
78
 * @param surface Surface colors affect surfaces of components, such as cards, sheets, and menus
79
 * @param error The error color is used to indicate errors in components
80
 * @param onPrimary Color used for text and icons displayed on top of the primary color
81
 * @param onSecondary Color used for text and icons displayed on top of the secondary color
82
 * @param onBackground Color used for text and icons displayed on top of the background color
83
 * @param onSurface Color used for text and icons displayed on top of the surface color
84
 * @param onError Color used for text and icons displayed on top of the error color
85
 * @param isLight Whether this Colors represents a light or dark theme
86
 */
87
@Stable
88
class Colors(
89
    val primary: Color,
90
    val primaryVariant: Color,
91
    val secondary: Color,
92
    val secondaryVariant: Color,
93
    val background: Color,
94
    val surface: Color,
95
    val error: Color,
96
    val onPrimary: Color,
97
    val onSecondary: Color,
98
    val onBackground: Color,
99
    val onSurface: Color,
100
    val onError: Color,
101
    val isLight: Boolean
102
)
103
```
104

105
### Light Colors
106

107
Factory function for creating light theme colors with iOS system color integration.
108

109
```kotlin { .api }
110
/**
111
 * The Material Design light color scheme
112
 * @param primary The primary color is the color displayed most frequently across your app's screens and components
113
 * @param primaryVariant The primary variant color is used to distinguish elements using primary colors
114
 * @param secondary The secondary color provides more ways to accent and distinguish your product
115
 * @param secondaryVariant The secondary variant color is used to distinguish elements using secondary colors
116
 * @param background The background color appears behind scrollable content
117
 * @param surface Surface colors affect surfaces of components, such as cards, sheets, and menus
118
 * @param error The error color is used to indicate errors in components
119
 * @param onPrimary Color used for text and icons displayed on top of the primary color
120
 * @param onSecondary Color used for text and icons displayed on top of the secondary color
121
 * @param onBackground Color used for text and icons displayed on top of the background color
122
 * @param onSurface Color used for text and icons displayed on top of the surface color
123
 * @param onError Color used for text and icons displayed on top of the error color
124
 */
125
fun lightColors(
126
    primary: Color = Color(0xFF6200EE),
127
    primaryVariant: Color = Color(0xFF3700B3),
128
    secondary: Color = Color(0xFF03DAC6),
129
    secondaryVariant: Color = Color(0xFF018786),
130
    background: Color = Color.White,
131
    surface: Color = Color.White,
132
    error: Color = Color(0xFFB00020),
133
    onPrimary: Color = Color.White,
134
    onSecondary: Color = Color.Black,
135
    onBackground: Color = Color.Black,
136
    onSurface: Color = Color.Black,
137
    onError: Color = Color.White
138
): Colors
139
```
140

141
**iOS System Color Examples:**
142

143
```kotlin
144
// iOS-style light colors
145
val iOSLightColors = lightColors(
146
    primary = Color(0xFF007AFF),        // iOS system blue
147
    primaryVariant = Color(0xFF0051D0),  // Darker iOS blue
148
    secondary = Color(0xFF34C759),       // iOS system green
149
    secondaryVariant = Color(0xFF248A3D), // Darker iOS green
150
    background = Color(0xFFFFFFFF),      // iOS system background
151
    surface = Color(0xFFF2F2F7),         // iOS system grouped background
152
    error = Color(0xFFFF3B30),           // iOS system red
153
    onPrimary = Color.White,
154
    onSecondary = Color.White,
155
    onBackground = Color(0xFF000000),    // iOS label
156
    onSurface = Color(0xFF000000),       // iOS label
157
    onError = Color.White
158
)
159
```
160

161
### Dark Colors
162

163
Factory function for creating dark theme colors optimized for iOS dark mode.
164

165
```kotlin { .api }
166
/**
167
 * The Material Design dark color scheme
168
 * @param primary The primary color is the color displayed most frequently across your app's screens and components
169
 * @param primaryVariant The primary variant color is used to distinguish elements using primary colors
170
 * @param secondary The secondary color provides more ways to accent and distinguish your product
171
 * @param secondaryVariant The secondary variant color is used to distinguish elements using secondary colors
172
 * @param background The background color appears behind scrollable content
173
 * @param surface Surface colors affect surfaces of components, such as cards, sheets, and menus
174
 * @param error The error color is used to indicate errors in components
175
 * @param onPrimary Color used for text and icons displayed on top of the primary color
176
 * @param onSecondary Color used for text and icons displayed on top of the secondary color
177
 * @param onBackground Color used for text and icons displayed on top of the background color
178
 * @param onSurface Color used for text and icons displayed on top of the surface color
179
 * @param onError Color used for text and icons displayed on top of the error color
180
 */
181
fun darkColors(
182
    primary: Color = Color(0xFFBB86FC),
183
    primaryVariant: Color = Color(0xFF3700B3),
184
    secondary: Color = Color(0xFF03DAC6),
185
    secondaryVariant: Color = secondary,
186
    background: Color = Color(0xFF121212),
187
    surface: Color = Color(0xFF121212),
188
    error: Color = Color(0xFFCF6679),
189
    onPrimary: Color = Color.Black,
190
    onSecondary: Color = Color.Black,
191
    onBackground: Color = Color.White,
192
    onSurface: Color = Color.White,
193
    onError: Color = Color.Black
194
): Colors
195
```
196

197
**iOS Dark Mode Examples:**
198

199
```kotlin
200
// iOS-style dark colors
201
val iOSDarkColors = darkColors(
202
    primary = Color(0xFF0A84FF),         // iOS dark system blue
203
    primaryVariant = Color(0xFF0056CC),   // Darker variant
204
    secondary = Color(0xFF30D158),        // iOS dark system green
205
    secondaryVariant = Color(0xFF248A3D), // Darker variant
206
    background = Color(0xFF000000),       // iOS system background dark
207
    surface = Color(0xFF1C1C1E),          // iOS system grouped background dark
208
    error = Color(0xFFFF453A),            // iOS system red dark
209
    onPrimary = Color.White,
210
    onSecondary = Color.Black,
211
    onBackground = Color(0xFFFFFFFF),     // iOS label dark
212
    onSurface = Color(0xFFFFFFFF),        // iOS label dark
213
    onError = Color.White
214
)
215
```
216

217
### Typography
218

219
Material typography scale optimized for iOS text rendering and accessibility.
220

221
```kotlin { .api }
222
/**
223
 * The Material Design typography scale includes a range of contrasting styles that support the needs of your product
224
 * @param h1 The largest headline, reserved for short, important text or numerals
225
 * @param h2 The second largest headline, reserved for short, important text or numerals
226
 * @param h3 The third largest headline, reserved for short, important text or numerals
227
 * @param h4 The fourth largest headline, reserved for short, important text or numerals
228
 * @param h5 The fifth largest headline, reserved for short, important text or numerals
229
 * @param h6 The smallest headline, reserved for short, important text or numerals
230
 * @param subtitle1 The largest subtitle, and is typically reserved for medium-emphasis text that is shorter in length
231
 * @param subtitle2 The smallest subtitle, and is typically reserved for medium-emphasis text that is shorter in length
232
 * @param body1 The largest body, and is typically used for long-form writing as it works well for small text sizes
233
 * @param body2 The smallest body, and is typically used for long-form writing as it works well for small text sizes
234
 * @param button Text style for buttons - all caps and medium weight
235
 * @param caption Used sparingly to annotate imagery or to introduce a headline
236
 * @param overline Used sparingly to introduce a headline
237
 */
238
@Immutable
239
class Typography(
240
    val h1: TextStyle = TextStyle(
241
        fontWeight = FontWeight.Light,
242
        fontSize = 96.sp,
243
        letterSpacing = (-1.5).sp
244
    ),
245
    val h2: TextStyle = TextStyle(
246
        fontWeight = FontWeight.Light,
247
        fontSize = 60.sp,
248
        letterSpacing = (-0.5).sp
249
    ),
250
    val h3: TextStyle = TextStyle(
251
        fontWeight = FontWeight.Normal,
252
        fontSize = 48.sp,
253
        letterSpacing = 0.sp
254
    ),
255
    val h4: TextStyle = TextStyle(
256
        fontWeight = FontWeight.Normal,
257
        fontSize = 34.sp,
258
        letterSpacing = 0.25.sp
259
    ),
260
    val h5: TextStyle = TextStyle(
261
        fontWeight = FontWeight.Normal,
262
        fontSize = 24.sp,
263
        letterSpacing = 0.sp
264
    ),
265
    val h6: TextStyle = TextStyle(
266
        fontWeight = FontWeight.Medium,
267
        fontSize = 20.sp,
268
        letterSpacing = 0.15.sp
269
    ),
270
    val subtitle1: TextStyle = TextStyle(
271
        fontWeight = FontWeight.Normal,
272
        fontSize = 16.sp,
273
        letterSpacing = 0.15.sp
274
    ),
275
    val subtitle2: TextStyle = TextStyle(
276
        fontWeight = FontWeight.Medium,
277
        fontSize = 14.sp,
278
        letterSpacing = 0.1.sp
279
    ),
280
    val body1: TextStyle = TextStyle(
281
        fontWeight = FontWeight.Normal,
282
        fontSize = 16.sp,
283
        letterSpacing = 0.5.sp
284
    ),
285
    val body2: TextStyle = TextStyle(
286
        fontWeight = FontWeight.Normal,
287
        fontSize = 14.sp,
288
        letterSpacing = 0.25.sp
289
    ),
290
    val button: TextStyle = TextStyle(
291
        fontWeight = FontWeight.Medium,
292
        fontSize = 14.sp,
293
        letterSpacing = 1.25.sp
294
    ),
295
    val caption: TextStyle = TextStyle(
296
        fontWeight = FontWeight.Normal,
297
        fontSize = 12.sp,
298
        letterSpacing = 0.4.sp
299
    ),
300
    val overline: TextStyle = TextStyle(
301
        fontWeight = FontWeight.Normal,
302
        fontSize = 10.sp,
303
        letterSpacing = 1.5.sp
304
    )
305
)
306
```
307

308
**iOS Typography Examples:**
309

310
```kotlin
311
// iOS-optimized typography
312
val iOSTypography = Typography(
313
    h1 = TextStyle(
314
        fontFamily = FontFamily.Default, // Maps to iOS system font
315
        fontWeight = FontWeight.Light,
316
        fontSize = 96.sp,
317
        letterSpacing = (-1.5).sp
318
    ),
319
    body1 = TextStyle(
320
        fontFamily = FontFamily.Default,
321
        fontWeight = FontWeight.Normal,
322
        fontSize = 16.sp,
323
        letterSpacing = 0.5.sp,
324
        lineHeight = 24.sp // iOS-appropriate line height
325
    )
326
    // ... other styles
327
)
328

329
// Using typography in components
330
Text(
331
    text = "Large Title",
332
    style = MaterialTheme.typography.h4
333
)
334

335
Text(
336
    text = "Body text content",
337
    style = MaterialTheme.typography.body1
338
)
339
```
340

341
### Shapes
342

343
Material shape definitions for component corners, optimized for iOS visual guidelines.
344

345
```kotlin { .api }
346
/**
347
 * Material shape values used to style different shape categories
348
 * @param small The default shape style used by small components like Button or Chip
349
 * @param medium The default shape style used by medium components like Card or AlertDialog
350
 * @param large The default shape style used by large components like ModalBottomSheetLayout
351
 */
352
@Immutable
353
class Shapes(
354
    val small: CornerBasedShape = RoundedCornerShape(4.dp),
355
    val medium: CornerBasedShape = RoundedCornerShape(4.dp),
356
    val large: CornerBasedShape = RoundedCornerShape(0.dp)
357
)
358
```
359

360
**iOS Shape Examples:**
361

362
```kotlin
363
// iOS-style shapes with larger corner radius
364
val iOSShapes = Shapes(
365
    small = RoundedCornerShape(8.dp),   // iOS-style small corner radius
366
    medium = RoundedCornerShape(12.dp), // iOS-style medium corner radius  
367
    large = RoundedCornerShape(16.dp)   // iOS-style large corner radius
368
)
369

370
// Using shapes in components
371
Card(
372
    shape = MaterialTheme.shapes.medium
373
) {
374
    // Card content
375
}
376

377
Button(
378
    shape = MaterialTheme.shapes.small
379
) {
380
    Text("Rounded Button")
381
}
382
```
383

384
### Theme Access
385

386
Utilities for accessing current theme values throughout the component tree.
387

388
```kotlin { .api }
389
object MaterialTheme {
390
    /**
391
     * Retrieves the current Colors at the call site's position in the hierarchy
392
     */
393
    val colors: Colors
394
        @Composable
395
        @ReadOnlyComposable
396
        get()
397

398
    /**
399
     * Retrieves the current Typography at the call site's position in the hierarchy
400
     */
401
    val typography: Typography
402
        @Composable
403
        @ReadOnlyComposable
404
        get()
405

406
    /**
407
     * Retrieves the current Shapes at the call site's position in the hierarchy
408
     */
409
    val shapes: Shapes
410
        @Composable
411
        @ReadOnlyComposable
412
        get()
413
}
414
```
415

416
**Usage Examples:**
417

418
```kotlin
419
@Composable
420
fun ThemedComponent() {
421
    // Access current theme colors
422
    val currentColors = MaterialTheme.colors
423
    
424
    Surface(
425
        color = currentColors.surface,
426
        contentColor = currentColors.onSurface
427
    ) {
428
        Text(
429
            text = "Themed text",
430
            style = MaterialTheme.typography.body1,
431
            color = MaterialTheme.colors.onSurface
432
        )
433
    }
434
}
435
```
436

437
### Content Color Utilities
438

439
Helper functions for determining appropriate content colors based on background colors.
440

441
```kotlin { .api }
442
/**
443
 * The Material color system contains pairs of colors that are typically used for the background
444
 * and content color inside a component. For example, a Button typically uses `primary` for its
445
 * background, and `onPrimary` for the color of its content (usually text or iconography).
446
 * This function tries to match the provided backgroundColor to a 'background' color in this
447
 * Colors, and then will return the corresponding color used for content. For example, when
448
 * backgroundColor is Colors.primary, this will return Colors.onPrimary.
449
 * @param backgroundColor the background color to calculate a content color for
450
 * @return the matching content color for backgroundColor. If backgroundColor is not present in
451
 * the theme's Colors, then returns Color.Unspecified.
452
 */
453
@Composable
454
@ReadOnlyComposable
455
fun contentColorFor(backgroundColor: Color): Color
456

457
/**
458
 * Updates the alpha of this color. Useful for creating translucent colors for iOS-style overlays
459
 */
460
fun Color.copy(alpha: Float): Color
461
```
462

463
**Usage Examples:**
464

465
```kotlin
466
// Automatic content color selection
467
Surface(
468
    color = MaterialTheme.colors.primary
469
) {
470
    Text(
471
        text = "Automatically colored text",
472
        color = contentColorFor(MaterialTheme.colors.primary) // Will be onPrimary
473
    )
474
}
475

476
// Manual content color with alpha
477
Surface(
478
    color = MaterialTheme.colors.surface.copy(alpha = 0.9f) // iOS-style translucent surface
479
) {
480
    // Content
481
}
482
```