From 113660a7f99a7bd24b58706920d04c3c030f51ca Mon Sep 17 00:00:00 2001
From: Matt Bruce <mbrucedogs@gmail.com>
Date: Tue, 27 Jan 2026 11:16:14 -0600
Subject: [PATCH] Signed-off-by: Matt Bruce <mbrucedogs@gmail.com>

---
 Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md   | 77 +++++++++++++--------
 Sources/Bedrock/Views/Text/StyledText.swift | 12 +++-
 2 files changed, 58 insertions(+), 31 deletions(-)

diff --git a/Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md b/Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md
index 9cbd5cf..00fbb8c 100644
--- a/Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md
+++ b/Sources/Bedrock/Theme/TYPOGRAPHY_GUIDE.md
@@ -132,49 +132,66 @@ IconLabel("star.fill", "Favorites", .body, emphasis: .secondary)
 
 ## When to Use StyledLabel vs Text()
 
-### Use StyledLabel
+### Use StyledLabel (Preferred)
 
-For simple text with standard styling:
+Use `StyledLabel` for the vast majority of text:
 
 ```swift
+// Simple text
 StyledLabel("Settings", .subheadingEmphasis)
 StyledLabel("Description", .subheading, emphasis: .secondary)
+
+// With multiline alignment
+StyledLabel("Centered text", .body, emphasis: .primary, alignment: .center)
+
+// With line limit
+StyledLabel("One line only", .caption, emphasis: .secondary, lineLimit: 1)
+
+// In buttons (put frame modifiers outside)
+Button(action: onContinue) {
+    StyledLabel("Continue", .heading, emphasis: .custom(AppTextColors.inverse))
+        .frame(maxWidth: .infinity)
+        .frame(height: 50)
+        .background(AppAccent.primary)
+}
 ```
 
-### Use Text() with .typography()
+### Use Text() with .typography() (Rare Exceptions)
 
-When you need additional modifiers:
+Only use `Text()` when you genuinely need modifiers that `StyledLabel` doesn't support:
 
 ```swift
-// Multiline text
-Text("Long description that might wrap to multiple lines")
-    .typography(.subheading)
-    .foregroundStyle(AppTextColors.secondary)
-    .multilineTextAlignment(.center)
-
-// Conditional colors
-Text(title)
-    .typography(.heading)
-    .foregroundStyle(isActive ? AppTextColors.primary : AppTextColors.tertiary)
-
-// With padding/background
-Text(dayLabel)
-    .typography(.caption)
-    .foregroundStyle(AppTextColors.secondary)
-    .padding(.horizontal, Design.Spacing.small)
-    .background(AppAccent.light.opacity(0.3))
-
-// Button labels with frame
-Text("Continue")
-    .typography(.heading)
-    .foregroundStyle(AppTextColors.inverse)
-    .frame(maxWidth: .infinity)
-    .frame(height: 50)
-
-// Font design variants
+// Font design variants (rounded, etc.)
 Text(formattedValue)
     .typography(.subheadingEmphasis)
     .fontDesign(.rounded)
+
+// TextField styling
+TextField("Placeholder", text: $value)
+    .typography(.heading)
+
+// Inside special view builders (like Charts AxisValueLabel)
+AxisValueLabel {
+    Text("\(value)%")
+        .font(Typography.caption2.font)  // .typography() won't work here
+        .foregroundStyle(color)
+}
+```
+
+### Never Use Raw `.font()` with System Fonts
+
+Instead of:
+
+```swift
+// BAD
+Text("Title").font(.headline)
+```
+
+Use:
+
+```swift
+// GOOD
+StyledLabel("Title", .heading)
 ```
 
 ---
diff --git a/Sources/Bedrock/Views/Text/StyledText.swift b/Sources/Bedrock/Views/Text/StyledText.swift
index 103ef31..5e64cfb 100644
--- a/Sources/Bedrock/Views/Text/StyledText.swift
+++ b/Sources/Bedrock/Views/Text/StyledText.swift
@@ -25,26 +25,36 @@ public struct StyledLabel: View {
     private let text: String
     private let typography: Typography
     private let emphasis: TextEmphasis
+    private let alignment: TextAlignment?
+    private let lineLimit: Int?
     
     /// Creates a styled label.
     /// - Parameters:
     ///   - text: The text to display.
     ///   - typography: The typography style (default: `.body`).
     ///   - emphasis: The text emphasis/color (default: `.primary`).
+    ///   - alignment: Optional multiline text alignment.
+    ///   - lineLimit: Optional line limit.
     public init(
         _ text: String,
         _ typography: Typography = .body,
-        emphasis: TextEmphasis = .primary
+        emphasis: TextEmphasis = .primary,
+        alignment: TextAlignment? = nil,
+        lineLimit: Int? = nil
     ) {
         self.text = text
         self.typography = typography
         self.emphasis = emphasis
+        self.alignment = alignment
+        self.lineLimit = lineLimit
     }
     
     public var body: some View {
         Text(text)
             .font(typography.font)
             .foregroundStyle(emphasis.color)
+            .multilineTextAlignment(alignment ?? .leading)
+            .lineLimit(lineLimit)
     }
 }