diff --git a/README.md b/README.md index bf8a870..314657c 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ Use this checklist when setting up a new app with Bedrock: - [ ] Define custom `SurfaceColorProvider` with your brand colors - [ ] Define custom `AccentColorProvider` for interactive elements - [ ] Create typealiases for easy access (e.g., `AppSurface`, `AppAccent`) +- [ ] **Legibility Alignment**: Apply `.preferredColorScheme(.dark)` to the root view if using a dark theme to ensure system text resolves to white (Required for legibility) - [ ] Apply theme colors to all views (never use hardcoded colors) #### 🚀 Branding & Launch Screen (Required for all apps) @@ -47,8 +48,9 @@ Use this checklist when setting up a new app with Bedrock: - [ ] Define `Color.Branding.primary`, `.secondary`, `.accent` - [ ] Create `AppIconConfig` extension for your app - [ ] Create `LaunchScreenConfig` extension for your app -- [ ] Create `LaunchScreen.storyboard` with matching brand color +- [ ] Create `LaunchScreen.storyboard` with matching brand color (Mandatory for no-flash launch) - [ ] Add `INFOPLIST_KEY_UILaunchStoryboardName` to build settings +- [ ] **Remove** `INFOPLIST_KEY_UILaunchScreen_*` settings from project (Unreliable) - [ ] Wrap app entry point with `AppLaunchView` inside a ZStack - [ ] Generate and export app icon using `IconGeneratorView` diff --git a/Sources/Bedrock/Branding/BRANDING_GUIDE.md b/Sources/Bedrock/Branding/BRANDING_GUIDE.md index 05420ea..f7a9a7b 100644 --- a/Sources/Bedrock/Branding/BRANDING_GUIDE.md +++ b/Sources/Bedrock/Branding/BRANDING_GUIDE.md @@ -641,6 +641,16 @@ patternStyle: .none --- +## Definitive Best Practices + +To ensure every app satisfies the highest quality standards for launch and legibility: + +1. **Launch Screen**: Always use the `LaunchScreen.storyboard` (Step 3). Info.plist background colors alone are unreliable and cause a white flash. +2. **Base Layer**: Wrap your App's root view in a `ZStack` with a `Color` matching your launch screen as the bottom-most layer. +3. **Color Scheme**: If utilizing a dark theme, **always** apply `.preferredColorScheme(.dark)` to your root view to prevent black semantic text colors. + +--- + ## Summary Checklist ### Branding Configuration diff --git a/Sources/Bedrock/Theme/THEME_GUIDE.md b/Sources/Bedrock/Theme/THEME_GUIDE.md index 2ddec04..436f9f9 100644 --- a/Sources/Bedrock/Theme/THEME_GUIDE.md +++ b/Sources/Bedrock/Theme/THEME_GUIDE.md @@ -363,7 +363,26 @@ Use the accent color for: - Selected states - Active indicators -### 5. Dark Theme Considerations +### 5. Legibility Rule: Color Scheme Alignment (Critical) + +A common "Gotcha" when using custom dark themes is the "black-on-dark" text overlap. This occurs because iOS defaults to Light Mode, causing system labels and Bedrock components that rely on semantic colors (like `.primary`) to resolve as Black. + +**The Fix:** +Always enforce the color scheme at the root of any app using a dark surface provider: + +```swift +@main +struct YourApp: App { + var body: some Scene { + WindowGroup { + MainContentView() + .preferredColorScheme(.dark) // Enforce dark semantic colors + } + } +} +``` + +### 6. Dark Theme Considerations For dark themes: - Surface colors get lighter as elevation increases