SwiftUI's `.primary` and `.secondary` are elegant — adaptive, environment-aware, composable. But they're not *yours*. If your brand lives in a teal `#1B8188`, there's no built-in way to make it feel as native as `.primary`. You end up scattering `Color(hex:)` calls, handling dark mode manually, and losing the composability that makes SwiftUI's styling so nice. Let's fix that by building a theme system that plugs brand colors and gradients directly into `.foregroundStyle()` / `.backgroundStyle()` — the same way `.primary` does. ## TL;DR — There's a ready-to-use package now If you just want the solution — [https://github.com/rozd/theme-kit](https://github.com/rozd/theme-kit) is a **production-ready** Swift package that implements everything this article describes. Drop it in, declare your tokens in a JSON file, run one command, and you get a **native-feeling** theme system that works **exactly** like SwiftUI's built-in styles. Colors, gradients, shadows, dark mode, runtime switching, Codable themes — all handled. Works on iOS, macOS, watchOS, tvOS, and visionOS. 👉 [https://github.com/rozd/theme-kit](https://github.com/rozd/theme-kit) The article below walks through the why and how behind the approach. The package came later as a complete implementation you can use today. ## What We're Building By the end, you'll be able to write this: ```swift .foregroundStyle(.themePrimary) ``` It looks like SwiftUI's built-in `.primary`, but resolves to your brand color — and automatically adapts between light and dark mode. No `@Environment` boilerplate in the view, no `colorScheme == .dark ? ... : ...` ternaries. The same pattern extends to gradients: ```swift .fill(.themePrimaryGradient) ``` The same architecture supports mesh gradients too — though that's out of scope for this article, here's a taste of the API: ```swift .fill(.themeBackgroundMeshGradient) ``` Same pattern, same environment integration, just a different style type under the hood. And because the entire theme lives in the SwiftUI environment, switching themes at runtime is a single assignment: ```swift theme = theme.copyWith( colors: theme.colors.copyWith( primary: .init(light: .purple, dark: .indigo) ) ) ``` Every view in the tree updates instantly. Let's build it. ## The Building Blocks The system is made of a small number of types, each with a single job: - **`ThemeAdaptiveStyle`** — holds light/dark variants of any style - **`ThemeColors`** — semantic color collection (primary, surface, etc.) - **`ThemeGradients`** — semantic gradient collection - **`Theme`** — root container for all style collections - **`ThemeShapeStyle`** — the bridge that makes it all feel native to SwiftUI Plus some glue: environment integration, convenience extensions, and `copyWith` methods for runtime updates. Let's build them one at a time. ## Step 1: The Adaptive Style Wrapper Every style in a theme needs two variants — one for light mode, one for dark. Rather than handling this per-type, we make a single generic wrapper: ```swift nonisolated struct ThemeAdaptiveStyle: Sendable, Codable { let light: Style let dark: Style } extension ThemeAdaptiveStyle { nonisolated func resolved(for colorScheme: ColorScheme) -> Style { colorScheme == .dark ? dark : light } } ``` This is the foundation everything else builds on. `Style` can be `Color`, `Gradient`, `MeshGradient`, or any custom type — the wrapper doesn't care. It just stores two variants and picks the right one based on the current color scheme. Making it `Codable` and `Sendable` from the start pays off later when we want to load themes from Firestore or pass them across concurrency boundaries. ## Step 2: Semantic Style Collections Now we define what a "theme" actually contains. We use Material Design's naming convention — `primary`, `onPrimary`, `surface`, `onSurface` — because it maps well to real UI needs and most designers already think in these terms: ```swift nonisolated struct ThemeColors: Codable { let primary: ThemeAdaptiveStyle let onPrimary: ThemeAdaptiveStyle // ... secondary, surface, onSurface, etc. } ``` Each field is a `ThemeAdaptiveStyle` — light and dark variants baked in. No optionals, no fallbacks. If you have a theme, it's complete. Gradients follow the same pattern: ```swift nonisolated struct ThemeGradients: Codable { let primary: ThemeAdaptiveStyle } ``` You add fields as your design system grows. The structure scales naturally. ## Step 3: The Theme Container The root `Theme` struct simply composes the collections: ```swift nonisolated struct Theme: Sendable, Codable { var colors: ThemeColors var gradients: ThemeGradients } ``` That's it. No protocol conformances to manage, no abstract base classes. Just data. ## Step 4: Default Values Every theme needs sensible defaults. We define them as static properties: ```swift nonisolated extension ThemeColors { static let `default` = ThemeColors( primary : .init(light: Color(hex: 0x1B8188), dark: Color(hex: 0x1B8188)), onPrimary : .init(light: Color(hex: 0xF7F5EC), dark: Color(hex: 0xF7F5EC)), // ... surface, onSurface, etc. ) } nonisolated extension Theme { static let `default` = Theme( colors: .default, gradients: .default, ) } ``` Notice how `primary` keeps the same teal in both modes, but each slot gets independent light/dark control — a `surface` color, for example, might use a warm off-white in light mode and a deep slate in dark. The defaults are your starting point; everything is overridable. ## Step 5: Environment Integration To get the theme into SwiftUI views, we use the `@Entry` macro: ```swift nonisolated extension EnvironmentValues { @Entry var theme: Theme = .default } ``` One line. The theme is now available everywhere via `@Environment(\.theme)`, and defaults to your brand's theme with no setup required. Views that don't care about theming don't need to do anything. At this point, you have a working theme system. You could stop here and use it like this: ```swift struct BrandedLabel: View { @Environment(\.theme) private var theme @Environment(\.colorScheme) private var colorScheme var body: some View { Text("Hello") .foregroundStyle(theme.colors.primary.resolved(for: colorScheme)) } } ``` It works, but it's verbose. Every view needs two `@Environment` properties and a `.resolved(for:)` call. We can do better. ## Step 6: The Key Innovation — `ThemeShapeStyle` This is where it gets interesting. SwiftUI's `ShapeStyle` protocol has a method called `resolve(in:)` that receives the full `EnvironmentValues`. We can use that to read both the theme *and* the color scheme, resolving the right variant automatically: ```swift nonisolated struct ThemeShapeStyle: ShapeStyle { nonisolated(unsafe) let keyPath: KeyPath> func resolve(in environment: EnvironmentValues) -> some ShapeStyle { environment.theme[keyPath: keyPath].resolved(for: environment.colorScheme) } } ``` This is small — nine lines — but it's the heart of the whole system. Let's break down what it does: 1. It stores a `KeyPath` from `Theme` to any `ThemeAdaptiveStyle

Blog

Building a Native-Feeling Theme System in SwiftUI