From 24cb2e31480aa8ab6623120dcd919859bb559404 Mon Sep 17 00:00:00 2001
From: Max Rozdobudko <max.rozdobudko@gmail.com>
Date: Sun, 22 Feb 2026 09:05:41 +0200
Subject: [PATCH 1/4] chore: updates .gitignore

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 05762b3..07c9c6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,3 +17,4 @@ default.profraw
 .github/pages/node_modules/
 
 .github/pages/dist/
+.github/pages/.vite/

From d0036ca0f1368cf3515ce786d4b7c28be2d71fd4 Mon Sep 17 00:00:00 2001
From: Max Rozdobudko <max.rozdobudko@gmail.com>
Date: Sun, 22 Feb 2026 19:11:50 +0200
Subject: [PATCH 2/4] Add custom resolver support to ThemeAdaptiveStyle

ThemeAdaptiveStyle now supports pluggable resolution via a Resolver
struct, enabling per-token resolution based on full EnvironmentValues
(not just colorScheme). This allows accessibility-aware tokens,
size-class-dependent styles, and other environment-driven adaptations.

Key changes:
- Add ThemeAdaptiveStyle.Resolver with id-based Equatable
- light/dark become optional (nil for resolver-only tokens)
- Data tokens auto-generate deterministic resolver IDs via JSON+Hasher
- Custom resolvers get unique UUID-based IDs by default
- Codable encode throws for resolver-only tokens (by design)
- Generated code uses resolved(in:) for full environment access
- Update tests to use EnvironmentValues-based resolution
---
 IMPLEMENTATION_DETAILS.md                     |   2 +-
 README.md                                     |   2 +-
 .../ThemeAdaptiveStyle+ShapeStyle.swift       |   2 +-
 Sources/ThemeKit/ThemeAdaptiveStyle.swift     |  92 +++++++++++++-
 .../ThemeShadowedStyleGenerator.swift         |   2 +-
 .../ThemeShapeStyleGenerator.swift            |   2 +-
 .../ThemeFileGeneratorTests.swift             |   2 +-
 .../ThemeAdaptiveStyleTests.swift             | 115 +++++++++++++++---
 8 files changed, 187 insertions(+), 32 deletions(-)

diff --git a/IMPLEMENTATION_DETAILS.md b/IMPLEMENTATION_DETAILS.md
index 6320682..00ff41e 100644
--- a/IMPLEMENTATION_DETAILS.md
+++ b/IMPLEMENTATION_DETAILS.md
@@ -103,7 +103,7 @@ struct ThemeShapeStyle<Style: ShapeStyle>: ShapeStyle, Sendable {
     let keyPath: KeyPath<Theme, ThemeAdaptiveStyle<Style>>
 
     func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
-        environment.theme[keyPath: keyPath].resolved(for: environment.colorScheme)
+        environment.theme[keyPath: keyPath].resolved(in: environment)
     }
 }
 ```
diff --git a/README.md b/README.md
index 8c4dd65..67bd479 100644
--- a/README.md
+++ b/README.md
@@ -203,7 +203,7 @@ struct ThemeShapeStyle<Style: ShapeStyle>: ShapeStyle {
     let keyPath: KeyPath<Theme, ThemeAdaptiveStyle<Style>>
 
     func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
-        environment.theme[keyPath: keyPath].resolved(for: environment.colorScheme)
+        environment.theme[keyPath: keyPath].resolved(in: environment)
     }
 }
 ```
diff --git a/Sources/ThemeKit/ThemeAdaptiveStyle+ShapeStyle.swift b/Sources/ThemeKit/ThemeAdaptiveStyle+ShapeStyle.swift
index 71cf988..5509c1c 100644
--- a/Sources/ThemeKit/ThemeAdaptiveStyle+ShapeStyle.swift
+++ b/Sources/ThemeKit/ThemeAdaptiveStyle+ShapeStyle.swift
@@ -2,6 +2,6 @@ import SwiftUI
 
 extension ThemeAdaptiveStyle: ShapeStyle where Style: ShapeStyle {
     nonisolated public func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
-        resolved(for: environment.colorScheme)
+        resolver.resolve(environment)
     }
 }
diff --git a/Sources/ThemeKit/ThemeAdaptiveStyle.swift b/Sources/ThemeKit/ThemeAdaptiveStyle.swift
index 8ed4d21..9326fa1 100644
--- a/Sources/ThemeKit/ThemeAdaptiveStyle.swift
+++ b/Sources/ThemeKit/ThemeAdaptiveStyle.swift
@@ -1,17 +1,97 @@
 import SwiftUI
 
-nonisolated public struct ThemeAdaptiveStyle<Style: Sendable & Codable & Equatable>: Sendable, Codable, Equatable {
-    public let light: Style
-    public let dark: Style
+nonisolated public struct ThemeAdaptiveStyle<Style: Sendable & Codable & Equatable>: Sendable, Equatable {
 
-    nonisolated public init(light: Style, dark: Style) {
+    public let light: Style?
+    public let dark: Style?
+
+    public let resolver: Resolver
+
+    nonisolated public init(
+        resolver: Resolver,
+    ) {
+        self.light = nil
+        self.dark = nil
+        self.resolver = resolver
+    }
+
+    nonisolated public init(
+        light: Style,
+        dark: Style,
+    ) {
         self.light = light
         self.dark = dark
+        self.resolver = Resolver(id: Self.resolverID(light: light, dark: dark)) { env in
+            env.colorScheme == .dark ? dark : light
+        }
+    }
+
+    private static func resolverID(light: Style, dark: Style) -> String {
+        guard let data = try? JSONEncoder().encode([light, dark]) else {
+            return UUID().uuidString
+        }
+        var hasher = Hasher()
+        hasher.combine(data)
+        return String(hasher.finalize())
     }
 }
 
 public extension ThemeAdaptiveStyle {
-    nonisolated func resolved(for colorScheme: ColorScheme) -> Style {
-        colorScheme == .dark ? dark : light
+    nonisolated func resolved(in environment: EnvironmentValues) -> Style {
+        resolver.resolve(environment)
+    }
+}
+
+// MARK: - Resolver
+
+nonisolated public extension ThemeAdaptiveStyle {
+
+    struct Resolver: Sendable {
+        public let id: String
+        public let resolve: @Sendable (EnvironmentValues) -> Style
+
+        public init(id: String, resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
+            self.id = id
+            self.resolve = resolve
+        }
+
+        public init(resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
+            self.init(id: UUID().uuidString, resolve: resolve)
+        }
+    }
+}
+
+nonisolated extension ThemeAdaptiveStyle.Resolver: Equatable {
+    public static func == (lhs: ThemeAdaptiveStyle<Style>.Resolver, rhs: ThemeAdaptiveStyle<Style>.Resolver) -> Bool {
+        lhs.id == rhs.id
+    }
+}
+
+// MARK: - Codable
+
+nonisolated extension ThemeAdaptiveStyle: Codable {
+    enum CodingKeys: String, CodingKey {
+        case light
+        case dark
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.init(
+            light: try container.decode(Style.self, forKey: .light),
+            dark: try container.decode(Style.self, forKey: .dark)
+        )
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        guard let light, let dark else {
+            throw EncodingError.invalidValue(self, .init(
+                codingPath: encoder.codingPath,
+                debugDescription: "Cannot encode ThemeAdaptiveStyle with a custom resolver — light/dark values are required for serialization."
+            ))
+        }
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(light, forKey: .light)
+        try container.encode(dark, forKey: .dark)
     }
 }
diff --git a/Sources/ThemeKitGenerator/ThemeShadowedStyleGenerator.swift b/Sources/ThemeKitGenerator/ThemeShadowedStyleGenerator.swift
index 7d4fe9d..9310361 100644
--- a/Sources/ThemeKitGenerator/ThemeShadowedStyleGenerator.swift
+++ b/Sources/ThemeKitGenerator/ThemeShadowedStyleGenerator.swift
@@ -20,7 +20,7 @@ nonisolated public struct ThemeShadowedStyleGenerator: Sendable {
 
             nonisolated public func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
                 let shadow = environment.theme[keyPath: shadowKeyPath]
-                    .resolved(for: environment.colorScheme)
+                    .resolved(in: environment)
                 guard let shadowStyle = shadow.shadowStyle else {
                     return AnyShapeStyle(base)
                 }
diff --git a/Sources/ThemeKitGenerator/ThemeShapeStyleGenerator.swift b/Sources/ThemeKitGenerator/ThemeShapeStyleGenerator.swift
index 4613f81..ee7aeb4 100644
--- a/Sources/ThemeKitGenerator/ThemeShapeStyleGenerator.swift
+++ b/Sources/ThemeKitGenerator/ThemeShapeStyleGenerator.swift
@@ -17,7 +17,7 @@ nonisolated public struct ThemeShapeStyleGenerator: Sendable {
             }
 
             nonisolated public func resolve(in environment: EnvironmentValues) -> some ShapeStyle {
-                environment.theme[keyPath: keyPath].resolved(for: environment.colorScheme)
+                environment.theme[keyPath: keyPath].resolved(in: environment)
             }
         }
 
diff --git a/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift b/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
index 4ad2651..cdb5f79 100644
--- a/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
+++ b/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
@@ -167,7 +167,7 @@ struct ThemeFileGeneratorTests {
 
         #expect(shapeStyle.content.contains("func resolve(in environment: EnvironmentValues)"))
         #expect(shapeStyle.content.contains("environment.theme[keyPath: keyPath]"))
-        #expect(shapeStyle.content.contains("environment.colorScheme"))
+        #expect(shapeStyle.content.contains("environment"))
     }
 
     @Test func environmentExtension_containsThemeEntry() throws {
diff --git a/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift b/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
index bf58a15..ba7f329 100644
--- a/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
+++ b/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
@@ -10,21 +10,25 @@ struct ThemeAdaptiveStyleTests {
 
     @Test func init_storesLightAndDark() throws {
         let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
-        #expect(try style.light.hexString == "#FF0000")
-        #expect(try style.dark.hexString == "#0000FF")
+        #expect(try style.light?.hexString == "#FF0000")
+        #expect(try style.dark?.hexString == "#0000FF")
     }
 
-    // MARK: - resolved(for:)
+    // MARK: - resolved(in:)
 
     @Test func resolved_forLight_returnsLightValue() throws {
         let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
-        let resolved = style.resolved(for: .light)
+        var env = EnvironmentValues()
+        env.colorScheme = .light
+        let resolved = style.resolved(in: env)
         #expect(try resolved.hexString == "#FF0000")
     }
 
     @Test func resolved_forDark_returnsDarkValue() throws {
         let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
-        let resolved = style.resolved(for: .dark)
+        var env = EnvironmentValues()
+        env.colorScheme = .dark
+        let resolved = style.resolved(in: env)
         #expect(try resolved.hexString == "#0000FF")
     }
 
@@ -34,8 +38,8 @@ struct ThemeAdaptiveStyleTests {
         let original = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
         let data = try JSONEncoder().encode(original)
         let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
-        #expect(try decoded.light.hexString == "#FF0000")
-        #expect(try decoded.dark.hexString == "#0000FF")
+        #expect(try decoded.light?.hexString == "#FF0000")
+        #expect(try decoded.dark?.hexString == "#0000FF")
     }
 
     @Test func codableRoundTrip_color_jsonStructure() throws {
@@ -84,10 +88,10 @@ struct ThemeAdaptiveStyleTests {
         )
         let data = try JSONEncoder().encode(original)
         let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Gradient>.self, from: data)
-        #expect(decoded.light.stops.count == 2)
-        #expect(decoded.dark.stops.count == 2)
-        #expect(try decoded.light.stops[0].color.hexString == "#FF0000")
-        #expect(try decoded.dark.stops[0].color.hexString == "#0000FF")
+        #expect(decoded.light?.stops.count == 2)
+        #expect(decoded.dark?.stops.count == 2)
+        #expect(try decoded.light?.stops[0].color.hexString == "#FF0000")
+        #expect(try decoded.dark?.stops[0].color.hexString == "#0000FF")
     }
 
     // MARK: - Nested structure
@@ -99,8 +103,8 @@ struct ThemeAdaptiveStyleTests {
         let decoded = try JSONDecoder().decode(
             ThemeAdaptiveStyle<ThemeAdaptiveStyle<Color>>.self, from: data
         )
-        #expect(try decoded.light.light.hexString == "#FF0000")
-        #expect(try decoded.light.dark.hexString == "#0000FF")
+        #expect(try decoded.light?.light?.hexString == "#FF0000")
+        #expect(try decoded.light?.dark?.hexString == "#0000FF")
     }
 
     // MARK: - ShapeStyle resolve(in:) — environment integration
@@ -122,7 +126,7 @@ struct ThemeAdaptiveStyleTests {
     }
 
     @Test func resolve_readsColorSchemeFromEnvironment() throws {
-        // resolve(in:) calls resolved(for: environment.colorScheme).
+        // resolve(in:) calls resolved(in: environment).
         // Verify the environment plumbing selects the correct variant.
         var lightEnv = EnvironmentValues()
         lightEnv.colorScheme = .light
@@ -131,9 +135,9 @@ struct ThemeAdaptiveStyleTests {
 
         let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
 
-        // Trace the same code path as resolve(in:): read colorScheme, call resolved(for:)
-        #expect(try style.resolved(for: lightEnv.colorScheme).hexString == "#FF0000")
-        #expect(try style.resolved(for: darkEnv.colorScheme).hexString == "#0000FF")
+        // Trace the same code path as resolve(in:): read colorScheme, call resolved(in:)
+        #expect(try style.resolved(in: lightEnv).hexString == "#FF0000")
+        #expect(try style.resolved(in: darkEnv).hexString == "#0000FF")
 
         // Exercise the actual ShapeStyle resolve entry point
         let _ = style.resolve(in: lightEnv)
@@ -146,7 +150,7 @@ struct ThemeAdaptiveStyleTests {
         #expect(env.colorScheme == .light)
 
         let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
-        #expect(try style.resolved(for: env.colorScheme).hexString == "#FF0000")
+        #expect(try style.resolved(in: env).hexString == "#FF0000")
         let _ = style.resolve(in: env)
     }
 
@@ -157,7 +161,78 @@ struct ThemeAdaptiveStyleTests {
         {"light": "#FF0000", "dark": "#0000FF"}
         """.utf8)
         let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: json)
-        #expect(try decoded.light.hexString == "#FF0000")
-        #expect(try decoded.dark.hexString == "#0000FF")
+        #expect(try decoded.light?.hexString == "#FF0000")
+        #expect(try decoded.dark?.hexString == "#0000FF")
+    }
+
+    // MARK: - Resolver
+
+    @Test func resolver_init_setsLightAndDarkToNil() {
+        let style = ThemeAdaptiveStyle<Color>(resolver: .init(id: "test") { _ in .red })
+        #expect(style.light == nil)
+        #expect(style.dark == nil)
+    }
+
+    @Test func resolver_customResolver_overridesDefaultBehavior() {
+        // Custom resolver that inverts the default: light in dark mode, dark in light mode
+        let style = ThemeAdaptiveStyle<Color>(resolver: .init(id: "inverted") { env in
+            env.colorScheme == .dark ? Color(hex: 0xFF0000) : Color(hex: 0x0000FF)
+        })
+        var lightEnv = EnvironmentValues()
+        lightEnv.colorScheme = .light
+        #expect(style.resolved(in: lightEnv) == Color(hex: 0x0000FF))
+
+        var darkEnv = EnvironmentValues()
+        darkEnv.colorScheme = .dark
+        #expect(style.resolved(in: darkEnv) == Color(hex: 0xFF0000))
+    }
+
+    @Test func resolver_dataTokens_sameLightDark_areEqual() {
+        let a = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        let b = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        #expect(a == b)
+    }
+
+    @Test func resolver_dataTokens_differentLightDark_areNotEqual() {
+        let a = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        let b = ThemeAdaptiveStyle(light: Color(hex: 0x00FF00), dark: Color(hex: 0x0000FF))
+        #expect(a != b)
+    }
+
+    @Test func resolver_codableRoundTrip_preservesEquality() throws {
+        let original = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        let data = try JSONEncoder().encode(original)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
+        #expect(original == decoded)
+    }
+
+    @Test func resolver_encodingResolverOnly_throws() {
+        let style = ThemeAdaptiveStyle<Color>(resolver: .init(id: "test") { _ in .red })
+        #expect(throws: EncodingError.self) {
+            _ = try JSONEncoder().encode(style)
+        }
+    }
+
+    @Test func resolver_explicitId_isStable() {
+        let resolver1 = ThemeAdaptiveStyle<Color>.Resolver(id: "highContrast") { _ in .white }
+        let resolver2 = ThemeAdaptiveStyle<Color>.Resolver(id: "highContrast") { _ in .black }
+        #expect(resolver1 == resolver2)
+    }
+
+    @Test func resolver_autoId_isUnique() {
+        let resolver1 = ThemeAdaptiveStyle<Color>.Resolver { _ in .red }
+        let resolver2 = ThemeAdaptiveStyle<Color>.Resolver { _ in .red }
+        #expect(resolver1 != resolver2)
+    }
+
+    @Test func resolver_shapeStyleResolve_usesCustomResolver() {
+        let style = ThemeAdaptiveStyle<Color>(resolver: .init(id: "always-red") { _ in .red })
+        var lightEnv = EnvironmentValues()
+        lightEnv.colorScheme = .light
+        var darkEnv = EnvironmentValues()
+        darkEnv.colorScheme = .dark
+        // Custom resolver ignores colorScheme — returns red in both
+        let _ = style.resolve(in: lightEnv)
+        let _ = style.resolve(in: darkEnv)
     }
 }

From 44d7199a8fea4fc8c3ee67d30f912cb774a0da83 Mon Sep 17 00:00:00 2001
From: Max Rozdobudko <max.rozdobudko@gmail.com>
Date: Sun, 22 Feb 2026 21:28:26 +0200
Subject: [PATCH 3/4] refactor: replace light/dark stored properties with
 Defaults enum

Refactor ThemeAdaptiveStyle to support multiple adaptation axes beyond
color scheme. The new Defaults enum (.colorScheme, .sizeClass, .value)
replaces the hardcoded light/dark properties, with each case owning its
resolver creation logic. Backward compatibility preserved via computed
.light/.dark accessors and unchanged init(light:dark:) signature.
---
 CLAUDE.md                                     |   5 +-
 .../ThemeAdaptiveStyle+Defaults.swift         |  88 ++++++++++
 .../ThemeAdaptiveStyle+Resolver.swift         |  26 +++
 Sources/ThemeKit/ThemeAdaptiveStyle.swift     |  96 +++++------
 .../ThemeFileGeneratorTests.swift             |   2 +-
 .../ThemeAdaptiveStyleTests.swift             | 162 ++++++++++++++++++
 6 files changed, 327 insertions(+), 52 deletions(-)
 create mode 100644 Sources/ThemeKit/ThemeAdaptiveStyle+Defaults.swift
 create mode 100644 Sources/ThemeKit/ThemeAdaptiveStyle+Resolver.swift

diff --git a/CLAUDE.md b/CLAUDE.md
index b488acf..e98259e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,7 +38,7 @@ Tests/
 
 ### Core Types (ThemeKit target)
 
-- **`ThemeAdaptiveStyle<Style>`** — Generic wrapper holding `light`/`dark` variants, resolved via `ColorScheme`.
+- **`ThemeAdaptiveStyle<Style>`** — Generic wrapper that pairs optional `Defaults` (the serializable data) with a `Resolver` (a closure that reads `EnvironmentValues`). `Defaults` is a nested enum with three cases: `.colorScheme(light:dark:)`, `.sizeClass(compact:regular:)`, and `.value(_:)`. Each case knows how to create its own resolver. Styles created with a custom `Resolver` have `defaults = nil` and cannot be encoded. Convenience computed properties `.light`, `.dark`, `.compact`, `.regular` extract values from the matching `Defaults` case (returning `nil` for mismatched cases).
 - **Codable conformances** — `Color`, `Gradient`, etc. get `Codable` conformance (via `@retroactive`) for remote/serialized theming.
 
 ### Generated Types (NOT in the package — produced per app)
@@ -84,7 +84,8 @@ A Svelte SPA at `.github/pages/` that lets users build `theme.json` visually ins
 
 - All types are `nonisolated`, `Sendable`, and `Codable`
 - Style resolution goes through SwiftUI's `resolve(in: EnvironmentValues)` — never requires `@Environment` in views
-- Every token must have both light and dark variants (no optionals/fallbacks)
+- Tokens adapt by axis: colorScheme (light/dark), sizeClass (compact/regular), or constant value — the `Defaults` enum case determines which
+- Codable auto-detects format by JSON keys: `{"light","dark"}` → colorScheme, `{"compact","regular"}` → sizeClass, plain value → value
 - `copyWith` pattern enables immutable theme updates at runtime
 - Generated `ShapeStyle` extensions constrain `Self` to `ThemeShapeStyle<ConcreteType>`
 - Shadow tokens also generate unconstrained instance properties on `ShapeStyle` for composition — static and instance properties coexist without conflict
diff --git a/Sources/ThemeKit/ThemeAdaptiveStyle+Defaults.swift b/Sources/ThemeKit/ThemeAdaptiveStyle+Defaults.swift
new file mode 100644
index 0000000..a985763
--- /dev/null
+++ b/Sources/ThemeKit/ThemeAdaptiveStyle+Defaults.swift
@@ -0,0 +1,88 @@
+import SwiftUI
+
+nonisolated public extension ThemeAdaptiveStyle {
+
+    enum Defaults: Sendable, Equatable {
+        case colorScheme(light: Style, dark: Style)
+        case sizeClass(compact: Style, regular: Style)
+        case value(Style)
+
+        func makeResolver() -> Resolver {
+            switch self {
+            case .colorScheme(let light, let dark):
+                Resolver(id: Self.resolverID(self)) { env in
+                    env.colorScheme == .dark ? dark : light
+                }
+            case .sizeClass(let compact, let regular):
+                Resolver(id: Self.resolverID(self)) { env in
+                    env.horizontalSizeClass == .compact ? compact : regular
+                }
+            case .value(let style):
+                Resolver(id: Self.resolverID(self)) { _ in
+                    style
+                }
+            }
+        }
+
+        private static func resolverID(_ defaults: Defaults) -> String {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = .sortedKeys
+            guard let data = try? encoder.encode(defaults) else {
+                return UUID().uuidString
+            }
+            var hasher = Hasher()
+            hasher.combine(data)
+            return String(hasher.finalize())
+        }
+    }
+}
+
+// MARK: - Codable
+
+extension ThemeAdaptiveStyle.Defaults: Codable {
+
+    private enum ColorSchemeCodingKeys: String, CodingKey {
+        case light, dark
+    }
+
+    private enum SizeClassCodingKeys: String, CodingKey {
+        case compact, regular
+    }
+
+    public init(from decoder: Decoder) throws {
+        // Try keyed container first for colorScheme / sizeClass
+        if let container = try? decoder.container(keyedBy: ColorSchemeCodingKeys.self),
+           container.contains(.light) {
+            self = .colorScheme(
+                light: try container.decode(Style.self, forKey: .light),
+                dark: try container.decode(Style.self, forKey: .dark)
+            )
+        } else if let container = try? decoder.container(keyedBy: SizeClassCodingKeys.self),
+                  container.contains(.compact) {
+            self = .sizeClass(
+                compact: try container.decode(Style.self, forKey: .compact),
+                regular: try container.decode(Style.self, forKey: .regular)
+            )
+        } else {
+            // Plain value
+            let container = try decoder.singleValueContainer()
+            self = .value(try container.decode(Style.self))
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        switch self {
+        case .colorScheme(let light, let dark):
+            var container = encoder.container(keyedBy: ColorSchemeCodingKeys.self)
+            try container.encode(light, forKey: .light)
+            try container.encode(dark, forKey: .dark)
+        case .sizeClass(let compact, let regular):
+            var container = encoder.container(keyedBy: SizeClassCodingKeys.self)
+            try container.encode(compact, forKey: .compact)
+            try container.encode(regular, forKey: .regular)
+        case .value(let style):
+            var container = encoder.singleValueContainer()
+            try container.encode(style)
+        }
+    }
+}
diff --git a/Sources/ThemeKit/ThemeAdaptiveStyle+Resolver.swift b/Sources/ThemeKit/ThemeAdaptiveStyle+Resolver.swift
new file mode 100644
index 0000000..b2debb6
--- /dev/null
+++ b/Sources/ThemeKit/ThemeAdaptiveStyle+Resolver.swift
@@ -0,0 +1,26 @@
+import SwiftUI
+
+nonisolated public extension ThemeAdaptiveStyle {
+
+    struct Resolver: Sendable {
+        public let id: String
+        public let resolve: @Sendable (EnvironmentValues) -> Style
+
+        public init(id: String, resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
+            self.id = id
+            self.resolve = resolve
+        }
+
+        public init(resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
+            self.init(id: UUID().uuidString, resolve: resolve)
+        }
+    }
+}
+
+// MARK: - Equatable conformance for Resolver
+
+nonisolated extension ThemeAdaptiveStyle.Resolver: Equatable {
+    public static func == (lhs: ThemeAdaptiveStyle<Style>.Resolver, rhs: ThemeAdaptiveStyle<Style>.Resolver) -> Bool {
+        lhs.id == rhs.id
+    }
+}
diff --git a/Sources/ThemeKit/ThemeAdaptiveStyle.swift b/Sources/ThemeKit/ThemeAdaptiveStyle.swift
index 9326fa1..262afb5 100644
--- a/Sources/ThemeKit/ThemeAdaptiveStyle.swift
+++ b/Sources/ThemeKit/ThemeAdaptiveStyle.swift
@@ -2,16 +2,14 @@ import SwiftUI
 
 nonisolated public struct ThemeAdaptiveStyle<Style: Sendable & Codable & Equatable>: Sendable, Equatable {
 
-    public let light: Style?
-    public let dark: Style?
+    public let defaults: Defaults?
 
     public let resolver: Resolver
 
     nonisolated public init(
         resolver: Resolver,
     ) {
-        self.light = nil
-        self.dark = nil
+        self.defaults = nil
         self.resolver = resolver
     }
 
@@ -19,79 +17,79 @@ nonisolated public struct ThemeAdaptiveStyle<Style: Sendable & Codable & Equatab
         light: Style,
         dark: Style,
     ) {
-        self.light = light
-        self.dark = dark
-        self.resolver = Resolver(id: Self.resolverID(light: light, dark: dark)) { env in
-            env.colorScheme == .dark ? dark : light
-        }
+        let defaults = Defaults.colorScheme(light: light, dark: dark)
+        self.defaults = defaults
+        self.resolver = defaults.makeResolver()
     }
 
-    private static func resolverID(light: Style, dark: Style) -> String {
-        guard let data = try? JSONEncoder().encode([light, dark]) else {
-            return UUID().uuidString
-        }
-        var hasher = Hasher()
-        hasher.combine(data)
-        return String(hasher.finalize())
+    nonisolated public init(
+        compact: Style,
+        regular: Style,
+    ) {
+        let defaults = Defaults.sizeClass(compact: compact, regular: regular)
+        self.defaults = defaults
+        self.resolver = defaults.makeResolver()
     }
-}
 
-public extension ThemeAdaptiveStyle {
-    nonisolated func resolved(in environment: EnvironmentValues) -> Style {
-        resolver.resolve(environment)
+    nonisolated public init(
+        value: Style,
+    ) {
+        let defaults = Defaults.value(value)
+        self.defaults = defaults
+        self.resolver = defaults.makeResolver()
     }
 }
 
-// MARK: - Resolver
+// MARK: - Convenience accessors
+
+public extension ThemeAdaptiveStyle {
 
-nonisolated public extension ThemeAdaptiveStyle {
+    var light: Style? {
+        guard case .colorScheme(let light, _) = defaults else { return nil }
+        return light
+    }
 
-    struct Resolver: Sendable {
-        public let id: String
-        public let resolve: @Sendable (EnvironmentValues) -> Style
+    var dark: Style? {
+        guard case .colorScheme(_, let dark) = defaults else { return nil }
+        return dark
+    }
 
-        public init(id: String, resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
-            self.id = id
-            self.resolve = resolve
-        }
+    var compact: Style? {
+        guard case .sizeClass(let compact, _) = defaults else { return nil }
+        return compact
+    }
 
-        public init(resolve: @escaping @Sendable (EnvironmentValues) -> Style) {
-            self.init(id: UUID().uuidString, resolve: resolve)
-        }
+    var regular: Style? {
+        guard case .sizeClass(_, let regular) = defaults else { return nil }
+        return regular
     }
 }
 
-nonisolated extension ThemeAdaptiveStyle.Resolver: Equatable {
-    public static func == (lhs: ThemeAdaptiveStyle<Style>.Resolver, rhs: ThemeAdaptiveStyle<Style>.Resolver) -> Bool {
-        lhs.id == rhs.id
+// MARK: - resolved(in:)
+
+public extension ThemeAdaptiveStyle {
+    nonisolated func resolved(in environment: EnvironmentValues) -> Style {
+        resolver.resolve(environment)
     }
 }
 
 // MARK: - Codable
 
 nonisolated extension ThemeAdaptiveStyle: Codable {
-    enum CodingKeys: String, CodingKey {
-        case light
-        case dark
-    }
 
     public init(from decoder: Decoder) throws {
-        let container = try decoder.container(keyedBy: CodingKeys.self)
-        self.init(
-            light: try container.decode(Style.self, forKey: .light),
-            dark: try container.decode(Style.self, forKey: .dark)
-        )
+        let defaults = try Defaults(from: decoder)
+        self.defaults = defaults
+        self.resolver = defaults.makeResolver()
     }
 
     public func encode(to encoder: Encoder) throws {
-        guard let light, let dark else {
+        guard let defaults else {
             throw EncodingError.invalidValue(self, .init(
                 codingPath: encoder.codingPath,
-                debugDescription: "Cannot encode ThemeAdaptiveStyle with a custom resolver — light/dark values are required for serialization."
+                debugDescription: "Cannot encode ThemeAdaptiveStyle with a custom resolver — defaults are required for serialization."
             ))
         }
-        var container = encoder.container(keyedBy: CodingKeys.self)
-        try container.encode(light, forKey: .light)
-        try container.encode(dark, forKey: .dark)
+        try defaults.encode(to: encoder)
     }
 }
diff --git a/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift b/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
index cdb5f79..24e1a79 100644
--- a/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
+++ b/Tests/ThemeKitGeneratorTests/ThemeFileGeneratorTests.swift
@@ -167,7 +167,7 @@ struct ThemeFileGeneratorTests {
 
         #expect(shapeStyle.content.contains("func resolve(in environment: EnvironmentValues)"))
         #expect(shapeStyle.content.contains("environment.theme[keyPath: keyPath]"))
-        #expect(shapeStyle.content.contains("environment"))
+        #expect(shapeStyle.content.contains(".resolved(in: environment)"))
     }
 
     @Test func environmentExtension_containsThemeEntry() throws {
diff --git a/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift b/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
index ba7f329..6eeb4d9 100644
--- a/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
+++ b/Tests/ThemeKitTests/ThemeAdaptiveStyleTests.swift
@@ -235,4 +235,166 @@ struct ThemeAdaptiveStyleTests {
         let _ = style.resolve(in: lightEnv)
         let _ = style.resolve(in: darkEnv)
     }
+
+    // MARK: - init(value:)
+
+    @Test func initValue_storesValueDefaults() {
+        let style = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        #expect(style.defaults == .value(Color(hex: 0xFF0000)))
+    }
+
+    @Test func initValue_resolvesSameInAllEnvironments() throws {
+        let style = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        var lightEnv = EnvironmentValues()
+        lightEnv.colorScheme = .light
+        var darkEnv = EnvironmentValues()
+        darkEnv.colorScheme = .dark
+        #expect(try style.resolved(in: lightEnv).hexString == "#FF0000")
+        #expect(try style.resolved(in: darkEnv).hexString == "#FF0000")
+    }
+
+    // MARK: - init(compact:regular:)
+
+    @Test func initSizeClass_storesSizeClassDefaults() {
+        let style = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        #expect(style.compact == Color(hex: 0xFF0000))
+        #expect(style.regular == Color(hex: 0x0000FF))
+    }
+
+    @Test func initSizeClass_resolvesCompactWhenCompact() throws {
+        let style = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        var env = EnvironmentValues()
+        env.horizontalSizeClass = .compact
+        #expect(try style.resolved(in: env).hexString == "#FF0000")
+    }
+
+    @Test func initSizeClass_resolvesRegularWhenRegular() throws {
+        let style = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        var env = EnvironmentValues()
+        env.horizontalSizeClass = .regular
+        #expect(try style.resolved(in: env).hexString == "#0000FF")
+    }
+
+    @Test func initSizeClass_nilFallsBackToRegular() throws {
+        let style = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        // Default EnvironmentValues has horizontalSizeClass == nil
+        let env = EnvironmentValues()
+        #expect(try style.resolved(in: env).hexString == "#0000FF")
+    }
+
+    // MARK: - Computed property cross-checks
+
+    @Test func colorSchemeStyle_returnsNilForSizeClassAccessors() {
+        let style = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        #expect(style.compact == nil)
+        #expect(style.regular == nil)
+    }
+
+    @Test func sizeClassStyle_returnsNilForColorSchemeAccessors() {
+        let style = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        #expect(style.light == nil)
+        #expect(style.dark == nil)
+    }
+
+    @Test func resolverOnly_returnsNilForAllAccessors() {
+        let style = ThemeAdaptiveStyle<Color>(resolver: .init(id: "test") { _ in .red })
+        #expect(style.light == nil)
+        #expect(style.dark == nil)
+        #expect(style.compact == nil)
+        #expect(style.regular == nil)
+    }
+
+    // MARK: - Codable round-trip (sizeClass)
+
+    @Test func codableRoundTrip_sizeClass() throws {
+        let original = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        let data = try JSONEncoder().encode(original)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
+        #expect(decoded.compact == Color(hex: 0xFF0000))
+        #expect(decoded.regular == Color(hex: 0x0000FF))
+    }
+
+    @Test func codableRoundTrip_sizeClass_jsonStructure() throws {
+        let original = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        let data = try JSONEncoder().encode(original)
+        let json = try #require(JSONSerialization.jsonObject(with: data) as? [String: String])
+        #expect(json["compact"] == "#FF0000")
+        #expect(json["regular"] == "#0000FF")
+    }
+
+    @Test func codableRoundTrip_sizeClass_preservesEquality() throws {
+        let original = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        let data = try JSONEncoder().encode(original)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
+        #expect(original == decoded)
+    }
+
+    // MARK: - Codable round-trip (value)
+
+    @Test func codableRoundTrip_value() throws {
+        let original = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        let data = try JSONEncoder().encode(original)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
+        #expect(decoded.defaults == .value(Color(hex: 0xFF0000)))
+    }
+
+    @Test func codableRoundTrip_value_jsonStructure() throws {
+        let original = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        let data = try JSONEncoder().encode(original)
+        let json = try #require(String(data: data, encoding: .utf8))
+        #expect(json == "\"#FF0000\"")
+    }
+
+    @Test func codableRoundTrip_value_preservesEquality() throws {
+        let original = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        let data = try JSONEncoder().encode(original)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: data)
+        #expect(original == decoded)
+    }
+
+    // MARK: - Decode from raw JSON (sizeClass & value)
+
+    @Test func decode_sizeClass_fromRawJSON() throws {
+        let json = Data("""
+        {"compact": "#FF0000", "regular": "#0000FF"}
+        """.utf8)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: json)
+        #expect(decoded.compact == Color(hex: 0xFF0000))
+        #expect(decoded.regular == Color(hex: 0x0000FF))
+    }
+
+    @Test func decode_value_fromRawJSON() throws {
+        let json = Data("\"#FF0000\"".utf8)
+        let decoded = try JSONDecoder().decode(ThemeAdaptiveStyle<Color>.self, from: json)
+        #expect(decoded.defaults == .value(Color(hex: 0xFF0000)))
+    }
+
+    // MARK: - Equality across forms
+
+    @Test func equality_sameColorScheme_areEqual() {
+        let a = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        let b = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        #expect(a == b)
+    }
+
+    @Test func equality_sameSizeClass_areEqual() {
+        let a = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        let b = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        #expect(a == b)
+    }
+
+    @Test func equality_sameValue_areEqual() {
+        let a = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        let b = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        #expect(a == b)
+    }
+
+    @Test func equality_differentForms_areNotEqual() {
+        let colorScheme = ThemeAdaptiveStyle(light: Color(hex: 0xFF0000), dark: Color(hex: 0x0000FF))
+        let sizeClass = ThemeAdaptiveStyle(compact: Color(hex: 0xFF0000), regular: Color(hex: 0x0000FF))
+        let value = ThemeAdaptiveStyle(value: Color(hex: 0xFF0000))
+        #expect(colorScheme != sizeClass)
+        #expect(colorScheme != value)
+        #expect(sizeClass != value)
+    }
 }

From b0a4f1fca7bb2f6926710c725bfd2bbfbcaec7d9 Mon Sep 17 00:00:00 2001
From: Max Rozdobudko <max.rozdobudko@gmail.com>
Date: Sun, 22 Feb 2026 23:12:36 +0200
Subject: [PATCH 4/4] docs: update README for multi-axis token adaptation and
 custom resolvers

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 67bd479..fa53154 100644
--- a/README.md
+++ b/README.md
@@ -7,14 +7,14 @@
 
 **Native-feeling theming for SwiftUI, powered by the environment.**
 
-ThemeKit gives your app a design token system that works exactly like SwiftUI's built-in styles. Every token is adaptive — light and dark variants resolve automatically based on the system color scheme. You declare your tokens in a simple JSON file (just names, no colors), run one command, and you're ready to use `.foregroundStyle(.surface)` anywhere.
+ThemeKit gives your app a design token system that works exactly like SwiftUI's built-in styles. Every token is adaptive — variants resolve automatically based on the environment (color scheme, size class, or any custom axis). You declare your tokens in a simple JSON file (just names, no colors), run one command, and you're ready to use `.foregroundStyle(.surface)` anywhere.
 
 ---
 
 ## ✨ Features
 
 - 🍎 **SwiftUI Native** — tokens resolve through `ShapeStyle.resolve(in:)`, the same mechanism as `.primary` and `.tint`. No `@Environment` wrappers needed in views.
-- 🌗 **Adaptive by Default** — every token carries light and dark variants. The correct one resolves automatically at render time — no manual `colorScheme` checks.
+- 🌗 **Adaptive by Default** — tokens adapt by color scheme (light/dark), size class (compact/regular), or any custom axis via resolvers. The correct variant resolves automatically at render time.
 - 📦 **Minimal Core** — the library is just `ThemeAdaptiveStyle` and a few `Codable` extensions. Everything else is generated.
 - 🔧 **Easy Setup** — declare tokens in JSON, run the plugin, fill in your colors. Four steps total.
 - 🔓 **Full Control** — generated files live in your project, fully readable and yours to extend.
@@ -117,6 +117,35 @@ nonisolated extension ThemeGradients {
 
 That's it — your theme is ready to use.
 
+<details>
+<summary>Advanced</summary>
+
+Beyond light/dark, tokens can adapt by **size class** or hold a **constant value**:
+
+```swift
+// Adapt by horizontal size class (compact vs regular)
+surface: .init(compact: Color(hex: 0xFFFFFF), regular: Color(hex: 0xF7F5EC))
+
+// Same value in all environments
+surface: .init(value: Color(hex: 0xF7F5EC))
+```
+
+For full control, use a **custom resolver** — a closure that reads `EnvironmentValues` directly:
+
+```swift
+surface: .init(resolver: .init(id: "high-contrast") { env in
+    env.colorSchemeContrast == .increased
+        ? Color(hex: 0xFFFFFF)
+        : Color(hex: 0xF7F5EC)
+})
+```
+
+The `id` parameter drives `Equatable` — two resolvers with the same `id` are considered equal, which lets SwiftUI skip unnecessary redraws. Omit it to get a unique auto-generated id.
+
+> **Note:** Tokens created with a custom resolver cannot be encoded to JSON, since they have no serializable defaults.
+
+</details>
+
 ## 🎨 Usage
 
 ### Use tokens in views
@@ -196,7 +225,7 @@ let theme = try JSONDecoder().decode(Theme.self, from: data)
 
 ## ⚙️ How It Works
 
-The generated `ThemeShapeStyle<Style>` bridges your tokens into SwiftUI's style resolution system. It holds a key path into `Theme` and resolves the correct light/dark variant at render time:
+The generated `ThemeShapeStyle<Style>` bridges your tokens into SwiftUI's style resolution system. It holds a key path into `Theme` and resolves the correct variant at render time:
 
 ```swift
 struct ThemeShapeStyle<Style: ShapeStyle>: ShapeStyle {