diff --git a/README.md b/README.md index a6071a7..097aa6b 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Bedrock is designed to be the foundation upon which apps are built, providing: | Guide | Path | Purpose | |-------|------|---------| +| **Typography Guide** | [`Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md`](Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md) | Text styling with `Text.styled()`, typography, and text emphasis | | **Theme Guide** | [`Sources/Bedrock/Theme/THEME_GUIDE.md`](Sources/Bedrock/Theme/THEME_GUIDE.md) | Create custom color themes using Bedrock's protocol-based theming system | | **Branding Guide** | [`Sources/Bedrock/Branding/BRANDING_GUIDE.md`](Sources/Bedrock/Branding/BRANDING_GUIDE.md) | Set up app icons, launch screens, and branded launch animations | | **Settings Guide** | [`Sources/Bedrock/Views/Settings/SETTINGS_GUIDE.md`](Sources/Bedrock/Views/Settings/SETTINGS_GUIDE.md) | Build branded settings screens with reusable UI components | @@ -33,6 +34,14 @@ Bedrock is designed to be the foundation upon which apps are built, providing: Use this checklist when setting up a new app with Bedrock: +#### 📝 Text Styling (Use First) +- [ ] **Read**: `TYPOGRAPHY_GUIDE.md` +- [ ] **Use `Text.styled()`** for all text in your app +- [ ] Choose appropriate `Typography` for each text element (`.heading`, `.body`, `.caption`, etc.) +- [ ] Apply `TextEmphasis` for semantic colors (`.primary`, `.secondary`, `.tertiary`) +- [ ] Use `SectionHeader` for grouped list section titles +- [ ] Use `Label.styled()` for icon + text combinations + #### 🎨 Theming (Required for all apps) - [ ] **Read**: `THEME_GUIDE.md` - [ ] Create `[AppName]Theme.swift` in `Shared/Theme/` @@ -68,9 +77,12 @@ Use this checklist when setting up a new app with Bedrock: When building a new app from scratch: -1. **First**: Read `THEME_GUIDE.md` → Create your app's color theme -2. **Second**: Read `BRANDING_GUIDE.md` → Set up icons and launch screen -3. **Third**: Read `SETTINGS_GUIDE.md` → Build your settings view +1. **First**: Use `Text.styled()` for all text → Semantic typography + colors (see Usage below) +2. **Second**: Read `THEME_GUIDE.md` → Create your app's color theme +3. **Third**: Read `BRANDING_GUIDE.md` → Set up icons and launch screen +4. **Fourth**: Read `SETTINGS_GUIDE.md` → Build your settings view + +> **💡 Key Principle**: Always prefer `Text("Hello").styled(.heading)` over raw `.font()` and `.foregroundStyle()` calls. This ensures consistent styling and makes your code more readable. --- @@ -95,6 +107,44 @@ Then add it to your target: ## Usage +### ⭐ Text Styling (Start Here) + +**The `Text.styled()` extension is the preferred way to style all text in Bedrock apps.** It combines typography and color emphasis into a single, semantic API. + +> **📖 Full Documentation**: See [`TYPOGRAPHY_GUIDE.md`](Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md) for complete typography options, text emphasis levels, and examples. + +```swift +import SwiftUI +import Bedrock + +// ✅ Preferred: Use styled() for all text +Text("Welcome Back") + .styled(.heroBold) + +Text("Your profile is up to date") + .styled(.body, emphasis: .secondary) + +Text("Last updated 5 min ago") + .styled(.caption, emphasis: .tertiary) + +// Labels also support styled() +Label("Settings", systemImage: "gear") + .styled(.subheading) + +// Section headers for grouped lists +SectionHeader("General") +SectionHeader("Notifications", icon: "bell.fill") +``` + +#### Why Use `styled()` First + +- **Single source of truth**: Combines font + color in one call +- **Semantic naming**: Use `.heading`, `.body`, `.caption` instead of raw fonts +- **Theme-aware**: Colors automatically adapt to your registered theme +- **Readable code**: `Text("Hello").styled(.heading)` is clearer than chaining modifiers + +--- + ### Design Constants Use the `Design` enum for consistent spacing, sizing, and styling: @@ -107,7 +157,7 @@ struct MyView: View { var body: some View { VStack(spacing: Design.Spacing.medium) { Text("Hello") - .font(.title) + .styled(.title) .padding(Design.Spacing.large) Button("Tap Me") { } @@ -121,17 +171,21 @@ struct MyView: View { Bedrock provides a **protocol-based color system** that enforces consistent naming while allowing apps to define their own palettes. +> **💡 For Text Colors**: Use `Text.styled()` with `TextEmphasis` instead of manually applying `foregroundStyle()`. See the [Text Styling](#-text-styling-start-here) section above. + #### Using Default Colors Bedrock includes neutral default colors that work out of the box: ```swift +// ✅ Preferred for text: Use styled() Text("Primary Text") - .foregroundStyle(Color.TextColors.primary) + .styled(.body) Text("Secondary Text") - .foregroundStyle(Color.TextColors.secondary) + .styled(.body, emphasis: .secondary) +// For non-text elements, use Color extensions VStack { } .background(Color.Surface.primary) ``` @@ -332,6 +386,23 @@ if DeviceInfo.isLandscape { } ``` +## Styling Quick Reference + +| What You're Styling | Preferred Approach | +|---------------------|-------------------| +| Any text | `Text("...").styled(.typography, emphasis: .level)` | +| Labels | `Label("...", systemImage: "...").styled(...)` | +| Section titles | `SectionHeader("...")` | +| Spacing | `Design.Spacing.medium`, `.large`, etc. | +| Corner radius | `Design.CornerRadius.medium`, `.large`, etc. | +| Backgrounds | `Color.Surface.primary`, `.card`, etc. | +| Accent/brand colors | `Color.Accent.primary`, `.secondary`, etc. | +| Status indicators | `Color.Status.success`, `.error`, etc. | + +> **📖 See Also**: [`TYPOGRAPHY_GUIDE.md`](Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md) for detailed do's and don'ts with text styling. + +--- + ## Design System Reference ### Spacing