diff --git a/CHANGELOG.md b/CHANGELOG.md
index c78e6e1..c83532a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,41 @@ All notable changes to RichText are documented here.
 
 ---
 
+## 3.1.1
+
+Two regressions from 3.1.0.
+
+**macOS backgrounds were no longer transparent.**
+
+3.1.0 guarded the `drawsBackground` KVC call with `responds(to:)`.
+KVC does not need that selector, it falls back to the `_drawsBackground` ivar.
+So the guard always failed: the background stayed opaque, and every macOS launch
+emitted a spurious `webViewConfigurationFailed`.
+
+Now uses `underPageBackgroundColor`, public API on iOS 15 and macOS 12.
+
+**`cssGenerationFailed` fired during a SwiftUI view update.**
+
+The handler ran synchronously from `makeUIView` and `updateUIView`.
+Mutating state inside it produced "Modifying state during view update" — the
+warning #72 had already fixed.
+
+Errors are now delivered on the next main-queue turn.
+
+Both are covered by regression tests.
+macOS transparency is asserted against a real hosted `WKWebView` rather than a
+string comparison, which is why 3.1.0 shipped without catching it.
+
+**Docs.**
+
+Fixed examples that did not compile: ambiguous `.blue` and `.cyan` color
+literals, a redeclared `let css`, and `fullScreenCover(item:)` bound to a
+non-`Identifiable` `String`.
+
+Removed 18 trailing-whitespace errors.
+
+---
+
 ## 3.1.0
 
 A correctness release. Every change below is source-compatible - nothing public was removed.
@@ -30,7 +65,7 @@ RichText(html: html)
         switch error {
         case .cssGenerationFailed:
             // fontColor or linkColor holds an invalid hex value, so the browser
-            // is dropping the declaration and the colour falls back to default
+            // is dropping the declaration and the color falls back to default
             break
         case .webViewConfigurationFailed:
             // macOS: the web view background could not be made transparent
@@ -75,7 +110,7 @@ Nothing is removed; all of these still compile and behave as before.
 | `RichTextConstants.bodyCSS` | nothing - it was never applied |
 | `Configuration.isColorsImportant` | `.colorPreference(forceColor:)`, or `ColorSet(light:dark:isImportant:)` |
 
-`Configuration.isColorsImportant` deserves a note: it was recorded but never read during CSS generation, so `Configuration(isColorsImportant: .all)` silently did nothing. `!important` comes from the colour sets alone.
+`Configuration.isColorsImportant` deserves a note: it was recorded but never read during CSS generation, so `Configuration(isColorsImportant: .all)` silently did nothing. `!important` comes from the color sets alone.
 
 ```swift
 // ❌ had no effect
@@ -129,7 +164,7 @@ Configuration(fontColor: ColorSet(light: "000000", dark: "FFFFFF", isImportant:
 Version 3.0.0 maintains **100% backward compatibility** for v2.x users while providing a clear path to modern APIs:
 
 - ✅ **Zero Breaking Changes**: All existing v2.x code works unchanged
-- ✅ **Automatic Performance**: Better async/await performance and font rendering without code changes  
+- ✅ **Automatic Performance**: Better async/await performance and font rendering without code changes
 - ✅ **Guided Migration**: Helpful deprecation warnings with clear modern API alternatives
 - ✅ **Additive Enhancement**: New features are optional and don't affect existing functionality
 - ✅ **Future-Proof**: Modern architecture ready for Swift 6+ and future iOS/macOS versions
diff --git a/README.md b/README.md
index 6d04709..13fb01a 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ Styling, light and dark theming, custom fonts, media callbacks and typed errors
 
 - **Cross-platform** — iOS 15.0+ and macOS 12.0+, Swift 5.9+
 - **Automatic sizing** — the view resizes itself as the content lays out, including late images, web fonts and `<details>` toggles
-- **Theming** — automatic light/dark mode, custom colour sets, transparent or custom backgrounds
+- **Theming** — automatic light/dark mode, custom color sets, transparent or custom backgrounds
 - **Typography** — system, monospaced, italic, custom and bundled fonts, with Dynamic Type support
 - **Interactive media** — click callbacks for images and videos
 - **Link handling** — Safari, `SFSafariViewController`, or your own handler
@@ -94,7 +94,7 @@ See [the API reference](docs/API.md) for every modifier, and [advanced usage](do
    ```
    https://github.com/NuPlay/RichText.git
    ```
-3. Select version rule: **"Up to Next Major Version"** from **"3.1.0"**
+3. Select version rule: **"Up to Next Major Version"** from **"3.1.1"**
 4. Click **Add Package**
 
 ### Manual Package.swift
@@ -103,7 +103,7 @@ Add RichText to your `Package.swift`:
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/NuPlay/RichText.git", .upToNextMajor(from: "3.1.0"))
+    .package(url: "https://github.com/NuPlay/RichText.git", .upToNextMajor(from: "3.1.1"))
 ],
 targets: [
     .target(
diff --git a/Sources/RichText/Models/ColorSet.swift b/Sources/RichText/Models/ColorSet.swift
index ccc0ece..fe2f18c 100644
--- a/Sources/RichText/Models/ColorSet.swift
+++ b/Sources/RichText/Models/ColorSet.swift
@@ -97,7 +97,7 @@ public struct ColorSet: Equatable {
     }
     
     private func isValidHexColor(_ hex: String) -> Bool {
-        // `#RGB`, `#RGBA`, `#RRGGBB` and `#RRGGBBAA` are all valid CSS colours. The previous
+        // `#RGB`, `#RGBA`, `#RRGGBB` and `#RRGGBBAA` are all valid CSS colors. The previous
         // 6-or-8 rule rejected the two shorthand forms as invalid even though they render
         // fine, and disagreed with `BackgroundColor.isHexColorLiteral`, which already
         // accepted all four lengths.
diff --git a/Sources/RichText/Models/Configuration.swift b/Sources/RichText/Models/Configuration.swift
index 2730d8b..c769bde 100644
--- a/Sources/RichText/Models/Configuration.swift
+++ b/Sources/RichText/Models/Configuration.swift
@@ -38,12 +38,12 @@ public struct Configuration {
     /// deprecation warning.
     var storedColorPreference: ColorPreference
 
-    /// The requested colour enforcement preference.
+    /// The requested color enforcement preference.
     ///
     /// - Warning: Assigning this does not change the generated CSS. `!important` is driven
     ///   entirely by ``ColorSet/isImportant`` on ``fontColor`` and ``linkColor``, and this
     ///   property has never been read during CSS generation. Use
-    ///   ``RichText/colorPreference(forceColor:)``, which sets both colour sets, or pass
+    ///   ``RichText/colorPreference(forceColor:)``, which sets both color sets, or pass
     ///   `ColorSet(light:dark:isImportant:)` directly.
     @available(*, deprecated, message: "Has no effect on the generated CSS. Use .colorPreference(forceColor:) on the view, or pass ColorSet(light:dark:isImportant:) for fontColor/linkColor.")
     public var isColorsImportant: ColorPreference {
diff --git a/Sources/RichText/Models/RichTextConstants.swift b/Sources/RichText/Models/RichTextConstants.swift
index e07e4b1..2abb250 100644
--- a/Sources/RichText/Models/RichTextConstants.swift
+++ b/Sources/RichText/Models/RichTextConstants.swift
@@ -48,7 +48,7 @@ public struct RichTextConstants {
     //
     // The percentage `min-height`/`max-height` that used to sit here resolved against a
     // containing block of `auto` height, so both were no-ops and neither did anything for
-    // the responsive behaviour. `min-height: 100%` in particular would have stretched every
+    // the responsive behavior. `min-height: 100%` in particular would have stretched every
     // image to the full container height the moment a definite height appeared.
     //
     // `loading: lazy` was also dropped: `loading` is an HTML attribute, not a CSS property,
@@ -268,12 +268,12 @@ extension RichTextConstants {
         "iframe{width:100%; height:\(height)px; border: none;}"
     }
 
-    /// Link colouring.
+    /// Link coloring.
     public static func linkCSS(color: String) -> String {
         "a:link {color: \(color); transition: color 0.2s ease;}"
     }
 
-    /// A `<style>` block for a single colour scheme, followed by the opening `<BODY>` tag.
+    /// A `<style>` block for a single color scheme, followed by the opening `<BODY>` tag.
     public static func styleDocument(css: String, customCSS: String) -> String {
         """
         <style type='text/css'>
diff --git a/Sources/RichText/Models/RichTextEnums.swift b/Sources/RichText/Models/RichTextEnums.swift
index f0cf93a..5f7e55b 100644
--- a/Sources/RichText/Models/RichTextEnums.swift
+++ b/Sources/RichText/Models/RichTextEnums.swift
@@ -93,7 +93,7 @@ public enum RichTextError: LocalizedError {
     /// The web view could not be configured as requested, so it will not look or behave as
     /// the configuration asked for.
     case webViewConfigurationFailed
-    /// The generated CSS will not be applied as intended, for example because a colour was
+    /// The generated CSS will not be applied as intended, for example because a color was
     /// given as an invalid hex value and the browser will drop the declaration.
     case cssGenerationFailed
     /// A media click message from the page could not be handled.
diff --git a/Sources/RichText/Views/RichText.swift b/Sources/RichText/Views/RichText.swift
index cb39dac..f8d05b5 100644
--- a/Sources/RichText/Views/RichText.swift
+++ b/Sources/RichText/Views/RichText.swift
@@ -19,7 +19,7 @@ import SwiftUI
 ///     .fontType(.system)
 ///     .lineHeight(150)
 ///     .imageRadius(8)
-///     .linkColor(light: .blue, dark: .cyan)
+///     .linkColor(light: Color.blue, dark: Color.cyan)
 ///     .placeholder {
 ///         ProgressView("Loading...")
 ///     }
diff --git a/Sources/RichText/Views/Webview.swift b/Sources/RichText/Views/Webview.swift
index 01c680e..9cafca4 100644
--- a/Sources/RichText/Views/Webview.swift
+++ b/Sources/RichText/Views/Webview.swift
@@ -104,18 +104,9 @@ extension WebView: NSViewRepresentable {
         // Set delegate
         webview.navigationDelegate = context.coordinator
         
-        // Configure appearance.
-        //
-        // `drawsBackground` is not part of WKWebView's public API, it is reached through KVC.
-        // `setValue(_:forKey:)` raises NSUnknownKeyException if the key ever goes away, and
-        // that is an Objective-C exception Swift cannot catch, so it would take the host app
-        // down. Probe for the setter and report a configuration failure instead.
-        if webview.responds(to: NSSelectorFromString("setDrawsBackground:")) {
-            webview.setValue(false, forKey: "drawsBackground")
-        } else {
-            webViewLogger.error("WKWebView no longer exposes drawsBackground; background will not be transparent")
-            conf.errorHandler?(.webViewConfigurationFailed)
-        }
+        // `underPageBackgroundColor` is the public WebKit API for the color behind a page.
+        // It is available from macOS 12, which is this package's minimum deployment target.
+        webview.underPageBackgroundColor = .clear
         
         // Load HTML content
         loadHTMLIfNeeded(in: webview, coordinator: context.coordinator)
@@ -307,6 +298,19 @@ extension WebView {
 }
 
 extension WebView {
+    /// Reports an error after the current SwiftUI representable update has completed.
+    @MainActor
+    func reportError(_ error: RichTextError) {
+        guard let errorHandler = conf.errorHandler else { return }
+
+        // Calling user code synchronously from make/update can mutate SwiftUI state while a
+        // view update is in progress. Capture the handler belonging to the failing
+        // configuration, then deliver the error on the next main-queue turn.
+        DispatchQueue.main.async {
+            errorHandler(error)
+        }
+    }
+
     /// Loads HTML content into the WebView safely on main thread, skipping redundant reloads
     /// - Parameters:
     ///   - webView: The WKWebView instance to load content into
@@ -315,21 +319,21 @@ extension WebView {
     private func loadHTMLIfNeeded(in webView: WKWebView, coordinator: Coordinator) {
         let htmlString = generateHTML()
         let baseURL = conf.baseURL
-        
+
         guard coordinator.loadedHTML != htmlString || coordinator.loadedBaseURL != baseURL else {
             webViewLogger.debug("Skipping reload, generated HTML and base URL are unchanged")
             return
         }
-        
+
         // A malformed hex value is not rejected anywhere: it reaches the stylesheet as
         // `color: #whatever`, and the browser drops that declaration along with the rest of
-        // the rule. The text or link colour then silently falls back to the default, which is
+        // the rule. The text or link color then silently falls back to the default, which is
         // very hard to trace from the outside, so surface it.
         if !conf.fontColor.isValid || !conf.linkColor.isValid {
-            webViewLogger.error("Invalid hex colour in fontColor or linkColor; the declaration will be dropped by the browser")
-            conf.errorHandler?(.cssGenerationFailed)
+            webViewLogger.error("Invalid hex color in fontColor or linkColor; the declaration will be dropped by the browser")
+            reportError(.cssGenerationFailed)
         }
-        
+
         coordinator.loadedHTML = htmlString
         coordinator.loadedBaseURL = baseURL
         
diff --git a/TestApp/README.md b/TestApp/README.md
index 5a4e273..847c87b 100644
--- a/TestApp/README.md
+++ b/TestApp/README.md
@@ -63,7 +63,7 @@ The test app covers all major features:
 - **Height Tracks the Content**: Opening a `<details>`, late-loading images and web fonts all resize the view instead of being clipped
 - **No Redundant Reloads**: The document is reloaded only when the HTML or base URL changes, so in-page state survives a SwiftUI update
 - **Dynamic Type Keeps `fontType`**: `supportsDynamicType` no longer discards `.monospaced`, `.italic` or `.customName`
-- **More Errors Reported**: Invalid hex colours raise `.cssGenerationFailed`; macOS transparency failures raise `.webViewConfigurationFailed`
+- **More Errors Reported**: Invalid hex colors raise `.cssGenerationFailed`; macOS transparency failures raise `.webViewConfigurationFailed`
 
 ### New in v3.0.0
 - **Better Font Rendering**: Monospaced and italic fonts should display correctly
diff --git a/Tests/RichTextTests/RichTextSwiftTestingTests.swift b/Tests/RichTextTests/RichTextSwiftTestingTests.swift
index 9b0700c..8d0bd70 100644
--- a/Tests/RichTextTests/RichTextSwiftTestingTests.swift
+++ b/Tests/RichTextTests/RichTextSwiftTestingTests.swift
@@ -1,5 +1,6 @@
 import Testing
 import SwiftUI
+import WebKit
 @testable import RichText
 
 #if canImport(UIKit)
@@ -52,7 +53,7 @@ struct RichTextAllTests {
             #expect(config.storedColorPreference == .all)
         }
 
-        @Test("Color preference is only applied through the colour sets")
+        @Test("Color preference is only applied through the color sets")
         func colorPreferenceOnlyAppliesThroughColorSets() {
             // `isColorsImportant` is recorded but never read during CSS generation, which is
             // why it is deprecated. `!important` comes from the ColorSets alone.
@@ -325,6 +326,84 @@ struct RichTextAllTests {
         }
     }
 
+    @Suite("WebView Behavior Tests", .serialized)
+    struct WebViewBehaviorTests {
+        #if canImport(AppKit)
+        @Test("macOS RichText creates a transparent WebView without a false configuration error")
+        @MainActor
+        func macOSRichTextCreatesTransparentWebView() async throws {
+            var errors: [RichTextError] = []
+            let configuration = Configuration(errorHandler: { errors.append($0) })
+            let host = NSHostingView(
+                rootView: RichText(html: "<p>Test</p>", configuration: configuration)
+                    .frame(width: 320, height: 100)
+            )
+            host.frame = NSRect(x: 0, y: 0, width: 320, height: 100)
+            host.layoutSubtreeIfNeeded()
+
+            let webView = try #require(findWKWebView(in: host))
+            await waitForMainQueueTurn()
+
+            #expect(webView.underPageBackgroundColor.alphaComponent == 0)
+            #expect(!errors.contains(where: isWebViewConfigurationFailure))
+
+            withExtendedLifetime(host) {}
+        }
+
+        @MainActor
+        private func findWKWebView(in view: NSView) -> WKWebView? {
+            if let webView = view as? WKWebView {
+                return webView
+            }
+
+            for subview in view.subviews {
+                if let webView = findWKWebView(in: subview) {
+                    return webView
+                }
+            }
+            return nil
+        }
+
+        private func isWebViewConfigurationFailure(_ error: RichTextError) -> Bool {
+            if case .webViewConfigurationFailed = error {
+                return true
+            }
+            return false
+        }
+
+        @MainActor
+        private func waitForMainQueueTurn() async {
+            await withCheckedContinuation { continuation in
+                DispatchQueue.main.async {
+                    continuation.resume()
+                }
+            }
+        }
+        #endif
+
+        @Test("Error callbacks are deferred until after the current view update")
+        @MainActor
+        func errorCallbacksAreDeferred() async {
+            let callbackWasDeferred: Bool = await withCheckedContinuation { continuation in
+                var reportCallReturned = false
+                let configuration = Configuration(errorHandler: { _ in
+                    continuation.resume(returning: reportCallReturned)
+                })
+                let webView = WebView(
+                    width: 100,
+                    dynamicHeight: .constant(0),
+                    html: "<p>Invalid CSS</p>",
+                    configuration: configuration
+                )
+
+                webView.reportError(.cssGenerationFailed)
+                reportCallReturned = true
+            }
+
+            #expect(callbackWasDeferred)
+        }
+    }
+
     @Suite("Constants Validation Tests")
     struct ConstantsTests {
 
diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md
index a29f289..1d9ac6f 100644
--- a/docs/ADVANCED.md
+++ b/docs/ADVANCED.md
@@ -53,8 +53,8 @@ RichText(html: html)
 
 ```swift
 RichText(html: html)
-    .foregroundColor(light: .primary, dark: .primary)
-    .linkColor(light: .blue, dark: .cyan)
+    .textColor(light: Color.primary, dark: Color.primary)
+    .linkColor(light: Color.blue, dark: Color.cyan)
     .backgroundColor(.system)
     .colorPreference(forceColor: .all)      // Override HTML colors
 ```
@@ -62,24 +62,26 @@ RichText(html: html)
 ### Interactive Media Handling
 
 ```swift
+private struct SelectedImage: Identifiable {
+    let url: String
+    var id: String { url }
+}
+
 struct ContentView: View {
-    @State private var selectedImage: String?
-    
+    @State private var selectedImage: SelectedImage?
+
     var body: some View {
         RichText(html: htmlWithImages)
             .onMediaClick { media in
                 switch media {
                 case .image(let src):
-                    selectedImage = src
+                    selectedImage = SelectedImage(url: src)
                 case .video(let src):
                     openVideoPlayer(url: src)
                 }
             }
-            .fullScreenCover(item: Binding<String?>(
-                get: { selectedImage },
-                set: { selectedImage = $0 }
-            )) { imageURL in
-                ImageViewer(url: imageURL)
+            .sheet(item: $selectedImage) { image in
+                ImageViewer(url: image.url)
             }
     }
 }
@@ -90,13 +92,13 @@ struct ContentView: View {
 ```swift
 struct ContentView: View {
     @State private var lastError: RichTextError?
-    
+
     var body: some View {
         VStack {
             if let error = lastError {
                 ErrorBanner(error: error)
             }
-            
+
             RichText(html: html)
                 .onError { error in
                     lastError = error
@@ -132,7 +134,7 @@ RichText(html: largeHtmlContent)
 ```swift
 struct ContentView: View {
     @StateObject private var htmlManager = HTMLContentManager()
-    
+
     var body: some View {
         RichText(html: htmlManager.currentHTML)
             .onError { error in
@@ -154,14 +156,14 @@ struct ContentView: View {
 ```swift
 struct BlogPostView: View {
     let post: BlogPost
-    
+
     var body: some View {
         ScrollView {
             VStack(alignment: .leading, spacing: 16) {
                 Text(post.title)
                     .font(.largeTitle)
                     .fontWeight(.bold)
-                
+
                 RichText(html: post.content)
                     .lineHeight(175)
                     .imageRadius(8)
@@ -187,7 +189,7 @@ struct BlogPostView: View {
             .padding()
         }
     }
-    
+
     private func handleMediaClick(_ media: MediaClickType) {
         // Custom media handling
     }
@@ -200,7 +202,7 @@ struct BlogPostView: View {
 struct EmailView: View {
     let emailHTML: String
     @State private var isLoading = true
-    
+
     var body: some View {
         RichText(html: emailHTML)
             .backgroundColor(.system)
@@ -222,7 +224,7 @@ struct EmailView: View {
                 print("Email loading error: \(error)")
             }
     }
-    
+
     private func showLinkConfirmation(_ url: URL) {
         // Show confirmation dialog
     }
@@ -234,7 +236,7 @@ struct EmailView: View {
 ```swift
 struct DocumentationView: View {
     let markdownHTML: String
-    
+
     var body: some View {
         NavigationView {
             RichText(html: markdownHTML)
@@ -242,8 +244,8 @@ struct DocumentationView: View {
                 .lineHeight(170)
                 .backgroundColor(.transparent)
                 .customCSS("""
-                    h1, h2, h3 { 
-                        color: #1d4ed8; 
+                    h1, h2, h3 {
+                        color: #1d4ed8;
                         margin-top: 24px;
                         margin-bottom: 12px;
                     }
diff --git a/docs/API.md b/docs/API.md
index bd5ac01..2081087 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -45,15 +45,15 @@ RichText(html: String, configuration: Configuration, placeholder: AnyView?)
 .fontType(.custom(UIFont.systemFont(ofSize: 16))) // Custom UIFont (iOS only)
 
 // Text colors - Modern API (v3.0.0+)
-.textColor(light: .primary, dark: .primary)         // Modern semantic naming
+.textColor(light: Color.primary, dark: Color.primary) // Modern semantic naming
 
 // Legacy text colors (deprecated but supported)
-.foregroundColor(light: .primary, dark: .primary)   // SwiftUI Colors (deprecated)
+.foregroundColor(light: Color.primary, dark: Color.primary) // SwiftUI Colors (deprecated)
 .foregroundColor(light: UIColor.black, dark: UIColor.white) // UIColors (deprecated)
 .foregroundColor(light: NSColor.black, dark: NSColor.white) // NSColors (deprecated)
 
 // Link colors
-.linkColor(light: .blue, dark: .cyan)      // SwiftUI Colors
+.linkColor(light: Color.blue, dark: Color.cyan) // SwiftUI Colors
 .linkColor(light: UIColor.blue, dark: UIColor.cyan) // UIColors
 
 // Color enforcement
@@ -140,7 +140,7 @@ RichText(html: String, configuration: Configuration, placeholder: AnyView?)
         // The web view could not be configured as requested (macOS transparency)
         print("WebView configuration failed")
     case .cssGenerationFailed:
-        // A colour was given as an invalid hex value, so the browser drops the declaration
+        // A color was given as an invalid hex value, so the browser drops the declaration
         print("CSS generation failed")
     case .mediaHandlingFailed(let media):
         print("Media handling failed: \(media)")
@@ -193,11 +193,11 @@ RichText(html: htmlContent, configuration: config)
 ```swift
 // Generate CSS programmatically (v3.0.0+)
 let richText = RichText(html: html)
-let css = richText.generateCSS(colorScheme: .light, alignment: .center)
+let richTextCSS = richText.generateCSS(colorScheme: .light, alignment: .center)
 
 // Generate CSS from configuration
 let config = Configuration(lineHeight: 150)
-let css = config.generateCompleteCSS(colorScheme: .dark)
+let configurationCSS = config.generateCompleteCSS(colorScheme: .dark)
 ```
 
 Individual rules can be built directly (v3.1.0+). These replace the deprecated
diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index a7603e4..751902a 100644
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -12,7 +12,7 @@ RichText(html: html)
 // 🚀 v3.0.0 - Recommended approaches
 RichText(html: html)
     .transparentBackground()           // Easiest for transparent
-    .backgroundColorHex("#FF0000")     // For hex colors  
+    .backgroundColorHex("#FF0000")     // For hex colors
     .backgroundColorSwiftUI(.blue)     // For SwiftUI colors
     .backgroundColor(.system)          // For system colors
 ```
@@ -56,11 +56,11 @@ RichText(html: html)
 ```swift
 // ✅ v2.x - Still works, but deprecated
 RichText(html: html)
-    .foregroundColor(light: .black, dark: .white)  // Deprecated
+    .foregroundColor(light: Color.black, dark: Color.white) // Deprecated
 
 // 🚀 v3.0.0 - Modern semantic naming
 RichText(html: html)
-    .textColor(light: .black, dark: .white)        // Modern & clear
+    .textColor(light: Color.black, dark: Color.white) // Modern & clear
 ```
 
 #### Enhanced Font Rendering
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 1f19cba..b51cc06 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -62,7 +62,7 @@ RichText(html: largeContent)
 RichText(html: html)
     .colorScheme(.auto)
     .forceColorSchemeBackground(true)
-    .foregroundColor(light: .black, dark: .white)
+    .textColor(light: Color.black, dark: Color.white)
 ```
 
 ### Platform-Specific Issues
@@ -97,7 +97,7 @@ If you experience memory issues with large content:
 // Implement proper cleanup
 struct ContentView: View {
     @State private var html = ""
-    
+
     var body: some View {
         RichText(html: html)
             .onDisappear {