fix(ui): remove blocking hiccup when exporting pdf

Docs/README.es.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem/branch/main/graph/badge.svg)](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem)
-[![Swift](https://img.shields.io/badge/Swift-6.0–6.2-orange.svg)](https://swift.org)
+[![Swift](https://img.shields.io/badge/Swift-6.1+-orange.svg)](https://swift.org)
 ![iOS](https://img.shields.io/badge/iOS-18.0+-blue?logo=apple)
 ![Platform](https://img.shields.io/badge/Platform-iPhone%20%7C%20iPad-lightgrey)
 ![SPM](https://img.shields.io/badge/SPM-Compatible-success)

Docs/README.ja.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem/branch/main/graph/badge.svg)](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem)
-[![Swift](https://img.shields.io/badge/Swift-6.0–6.2-orange.svg)](https://swift.org)
+[![Swift](https://img.shields.io/badge/Swift-6.1+-orange.svg)](https://swift.org)
 ![iOS](https://img.shields.io/badge/iOS-18.0+-blue?logo=apple)
 ![Platform](https://img.shields.io/badge/Platform-iPhone%20%7C%20iPad-lightgrey)
 ![SPM](https://img.shields.io/badge/SPM-Compatible-success)

Docs/README.pt-BR.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem/branch/main/graph/badge.svg)](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem)
-[![Swift](https://img.shields.io/badge/Swift-6.0–6.2-orange.svg)](https://swift.org)
+[![Swift](https://img.shields.io/badge/Swift-6.1+-orange.svg)](https://swift.org)
 ![iOS](https://img.shields.io/badge/iOS-18.0+-blue?logo=apple)
 ![Platform](https://img.shields.io/badge/Platform-iPhone%20%7C%20iPad-lightgrey)
 ![SPM](https://img.shields.io/badge/SPM-Compatible-success)

Docs/architecture/api-map.md

@@ -476,7 +476,7 @@ typealias GentleTouchTokens = GentleSpacingScaleTokens
 ### GentleSurfaceRole (enum: String, Codable, Sendable, CaseIterable)
 ```
 Cases: appBackground, card, cardElevated, cardSecondary, chrome,
-       overlaySheet, overlayPopover, floatingPanel, floatingWidget
+       overlaySheet, overlayPopover, overlayScrim, floatingPanel, floatingWidget
 
 var displayName: String
 var subtitle: String

Docs/architecture/api-quick-ref.md

@@ -132,7 +132,7 @@ design.color(.textPrimary)      // Color for current scheme
 design.color(.primaryCTA)       // Color
 
 // Convenience colors
-design.surface                  // color(.surface)
+design.surfaceBase              // color(.surfaceBase)
 design.background               // color(.background)
 design.borderSubtle             // color(.borderSubtle)
 design.textPrimary              // color(.textPrimary)
@@ -269,8 +269,8 @@ let jsonData = try spec.encodedJSONData()
 let jsonString = try spec.encodedJSONString()
 
 // Decoding
-let spec = try GentleDesignSystemSpec(jsonData: data)
-let spec = try GentleDesignSystemSpec(jsonString: string)
+let spec = try GentleDesignSystemSpec.fromJSONData(data)
+let spec = try GentleDesignSystemSpec.fromJSONString(string)
 ```
 
 ---

Docs/architecture/design-tokens.md

@@ -71,7 +71,7 @@ Theme:    themePrimary, themeSecondary
 - `GentleColorRole.surfaceRoles` - container/background/border colors (6)
 - `GentleColorRole.actionRoles` - interactive element colors (2)
 - `GentleColorRole.themeRoles` - brand/accent colors (2)
-- `GentleColorRole.surfaceBackgroundRoles` - subset valid for surface backgrounds (4): `background`, `surfaceBase`, `surfaceCardSecondary`, `surfaceOverlay`
+- `GentleColorRole.surfaceBackgroundRoles` - subset valid for surface backgrounds (4): `background`, `surfaceBase`, `surfaceCardSecondary`, `surfaceTint`
 
 Use `role.isTextRole`, `role.isSurfaceRole`, `role.isActionRole`, `role.isThemeRole`, or `role.isSurfaceBackgroundRole` for membership checks.
 

Docs/architecture/glossary.md

@@ -33,7 +33,7 @@
 | `GentleSurfaceBackgroundStyle` | Surface background type: .solid(colorRole:), .material(material:tintColorRole:tintOpacity:), .glass(fallbackMaterial:fallbackColorRole:) |
 | `GentleAppleMaterial` | Apple's blur materials: noMaterial, ultraThin, thin, regular, thick, ultraThick, bar |
 | `GentleSurfaceDepthEffect` | Surface depth effects: noEffect, highlightAndIndent(strength:) |
-| `GentleVisualEffect` | Legacy visual effect type (appBackground, surface, surfaceOverlay) |
+| `GentleVisualEffect` | Visual effect type (appBackground, surface, surfaceOverlay) |
 | `GentleInsetRole` | Padding intent (4 roles) |
 | `GentleGapIntent` | Spacing intent (7 levels) |
 

Docs/architecture/workflows.md

@@ -2,16 +2,15 @@
 
 ## Build Commands
 
+> **Always build for the iOS Simulator.** This package depends on UIKit, so bare `swift build` will fail on macOS. Use `xcodebuild` with a simulator destination for all build and test commands.
+
 ### Package
 ```bash
-# Build package
-swift build
-
-# Build for release
-swift build -c release
+# Build package (iOS Simulator)
+xcodebuild build -scheme GentleDesignSystem -destination 'platform=iOS Simulator,name=iPhone 16' -quiet
 
 # Clean build
-swift package clean && swift build
+xcodebuild clean build -scheme GentleDesignSystem -destination 'platform=iOS Simulator,name=iPhone 16' -quiet
 ```
 
 ### Tests

README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gentle-giraffe-apps/GentleDesignSystem/actions/workflows/ci.yml)
 [![Coverage](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem/branch/main/graph/badge.svg)](https://codecov.io/gh/gentle-giraffe-apps/GentleDesignSystem)
-[![Swift](https://img.shields.io/badge/Swift-6.0–6.2-orange.svg)](https://swift.org)
+[![Swift](https://img.shields.io/badge/Swift-6.1+-orange.svg)](https://swift.org)
 ![iOS](https://img.shields.io/badge/iOS-18.0+-blue?logo=apple)
 ![Platform](https://img.shields.io/badge/Platform-iPhone%20%7C%20iPad-lightgrey)
 ![SPM](https://img.shields.io/badge/SPM-Compatible-success)

Sources/GentleDesignSystem/GentleDesignStudioView.swift

@@ -107,7 +107,6 @@ public struct GentleDesignStudioView: View {
                                 } label: {
                                     Label("Export PDF", systemImage: "doc.richtext")
                                 }
-                                .disabled(exportPDFURL == nil)
                             } label: {
                                 Image(systemName: "square.and.arrow.up")
                                     .gentleText(.title3_ml)
@@ -173,7 +172,7 @@ public struct GentleDesignStudioView: View {
                             ProgressView("Preparing PDF export…")
                                 .presentationDetents([.height(260)])
                                 .presentationDragIndicator(.visible)
-                                .task { await refreshExportURLs() }
+                                .task { await generatePDFExport() }
                         }
 
                     case .exportMenu:
@@ -190,7 +189,11 @@ public struct GentleDesignStudioView: View {
             print("themeManager.exportURL error: \(error)")
             exportJSONURL = nil
         }
+    }
 
+    @MainActor
+    private func generatePDFExport() async {
+        exportPDFURL = nil
         do {
             exportPDFURL = try themeManager.exportPDFURL()
         } catch {

Sources/GentleDesignSystem/GentlePDFExporter.swift

@@ -21,6 +21,7 @@ public enum GentlePDFExportError: Error, LocalizedError {
 
 // MARK: - PDF Exporter
 
+@MainActor
 public enum GentlePDFExporter {
 
     // MARK: - Layout Constants
@@ -541,27 +542,23 @@ public enum GentlePDFExporter {
     }
 
     /// Renders a surface using SwiftUI and captures it as a UIImage
-    /// Note: This must be called from the main thread since ImageRenderer requires it
     private static func renderSurfaceWithSwiftUI(spec: GentleDesignSystemSpec, role: GentleSurfaceRole, size: CGSize) -> UIImage? {
-        // Use assumeIsolated since PDF rendering happens on main thread via UIGraphicsPDFRenderer
-        return MainActor.assumeIsolated {
-            let theme = GentleTheme(defaultSpec: spec, editableSpec: spec)
+        let theme = GentleTheme(defaultSpec: spec, editableSpec: spec)
 
-            // Create a SwiftUI view that renders the surface with a gradient background to show the blur
-            let surfaceView = SurfacePreviewView(role: role, size: size)
+        // Create a SwiftUI view that renders the surface with a gradient background to show the blur
+        let surfaceView = SurfacePreviewView(role: role, size: size)
 
-            // Use ImageRenderer to capture the view
-            let renderer = ImageRenderer(content:
-                GentleThemeRoot(theme: theme) {
-                    surfaceView
-                }
-                .environment(\.colorScheme, .light)
-            )
+        // Use ImageRenderer to capture the view
+        let renderer = ImageRenderer(content:
+            GentleThemeRoot(theme: theme) {
+                surfaceView
+            }
+            .environment(\.colorScheme, .light)
+        )
 
-            renderer.scale = 8.0 // 8x scale for crisp PDF output
+        renderer.scale = 8.0 // 8x scale for crisp PDF output
 
-            return renderer.uiImage
-        }
+        return renderer.uiImage
     }
 
     // MARK: - Colors Section