@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/ios-localization/references/formatstyle-locale.md

@@ -1,31 +1,37 @@
-# FormatStyle & Locale-Aware Formatting
+# FormatStyle, Locale and Layout Direction
 
-Comprehensive reference for locale-aware formatting in iOS 15+ using `FormatStyle`. Never hard-code date, number, or measurement formats -- these break in every locale except the one you tested. `ios-localization` owns `FormatStyle` guidance when the issue is locale-aware user-facing display: numbers, dates, currency, units, names, lists, calendars, separators, and locale preview/testing. Locale-aware formatting matters even in single-language apps; explicitly recommend testing or previewing user-facing output under multiple locales. Use the `swift-formatstyle` skill for broader standalone FormatStyle API design.
+`FormatStyle` needs iOS 15 or later. This skill uses it for locale-aware
+display: numbers, dates, currency, units, names, lists, calendars and
+separators, plus previews and tests across locales. Custom `FormatStyle`
+types, `ParseableFormatStyle`, parsing, `Date.IntervalFormatStyle`,
+`URL.FormatStyle` and reusable formatter API design belong to
+`swift-formatstyle`; here they only get locale risks and testing advice unless
+someone asks for the implementation. Whatever the value, recommend previewing
+it in several locales such as `en_US`, `de_DE`, `ar_SA` and `ja_JP`.
 
 ## Contents
 
-- [Date Formatting](#date-formatting)
-- [Number Formatting](#number-formatting)
-- [Measurement Formatting](#measurement-formatting)
-- [Duration Formatting](#duration-formatting)
-- [PersonNameComponents Formatting](#personnamecomponents-formatting)
-- [ByteCountFormatStyle](#bytecountformatstyle)
-- [ListFormatStyle](#listformatstyle)
-- [Custom FormatStyle Implementation](#custom-formatstyle-implementation)
-- [Forcing a Specific Locale](#forcing-a-specific-locale)
-- [RTL Layout Deep Dive](#rtl-layout-deep-dive)
-- [`@ScaledMetric for Dynamic Type`](#scaledmetric-for-dynamic-type)
-- [Layout Testing with Accessibility Inspector](#layout-testing-with-accessibility-inspector)
-- [Quick Reference Table](#quick-reference-table)
-
-## Migration from Legacy Formatters
-
-`FormatStyle` (iOS 15+) replaces the older `Formatter` subclasses. If you encounter legacy code, migrate to `FormatStyle`:
-
-| Legacy | Modern replacement |
-|--------|-------------------|
-| `DateFormatter` | `.formatted(.dateTime...)` or `Date.FormatStyle` |
-| `NumberFormatter` | `.formatted(.number...)` or `IntegerFormatStyle` / `FloatingPointFormatStyle` |
+1. [Replacing legacy formatters](#replacing-legacy-formatters)
+2. [Dates](#dates)
+3. [Numbers](#numbers)
+4. [Measurements](#measurements)
+5. [Durations](#durations)
+6. [Person names](#person-names)
+7. [Byte counts](#byte-counts)
+8. [Lists](#lists)
+9. [Custom styles](#custom-styles)
+10. [Pinning a locale](#pinning-a-locale)
+11. [Right-to-left in depth](#right-to-left-in-depth)
+12. [ScaledMetric and Dynamic Type](#scaledmetric-and-dynamic-type)
+13. [Checking layout with Accessibility Inspector](#checking-layout-with-accessibility-inspector)
+14. [Cheat sheet](#cheat-sheet)
+
+## Replacing legacy formatters
+
+| Old formatter | FormatStyle replacement |
+|---|---|
+| `DateFormatter` | `.formatted(.dateTime...)`, `Date.FormatStyle` |
+| `NumberFormatter` | `.formatted(.number...)`, `IntegerFormatStyle`, `FloatingPointFormatStyle` |
 | `DateComponentsFormatter` | `Duration.formatted(.units(...))` or `.time(pattern:)` |
 | `MeasurementFormatter` | `Measurement.formatted(.measurement(...))` |
 | `DateIntervalFormatter` | `(start..<end).formatted(date:time:)` |
@@ -33,612 +39,398 @@ Comprehensive reference for locale-aware formatting in iOS 15+ using `FormatStyl
 | `ByteCountFormatter` | `.formatted(.byteCount(style:))` |
 | `ListFormatter` | `.formatted(.list(type:))` |
 
-`FormatStyle` is value-type, `Sendable`, composable, and works directly in SwiftUI `Text` views. The legacy formatters are reference types that require manual locale and calendar configuration.
+Format styles are value types, `Sendable` and composable, and SwiftUI `Text`
+accepts them directly. The old formatters are classes whose locale and calendar
+you had to configure and share by hand.
 
-## Date Formatting
+## Dates
 
-### Preset date and time styles
+Presets:
 
 ```swift
-let date = Date.now
-
-// Date only
-date.formatted(date: .numeric, time: .omitted)      // "1/15/2026" (US) / "15.01.2026" (DE)
-date.formatted(date: .abbreviated, time: .omitted)   // "Jan 15, 2026" (US) / "15. Jan. 2026" (DE)
-date.formatted(date: .long, time: .omitted)          // "January 15, 2026" (US) / "15. Januar 2026" (DE)
-date.formatted(date: .complete, time: .omitted)      // "Thursday, January 15, 2026" (US)
-
-// Time only
-date.formatted(date: .omitted, time: .shortened)     // "3:30 PM" (US) / "15:30" (DE)
-date.formatted(date: .omitted, time: .standard)      // "3:30:45 PM" (US) / "15:30:45" (DE)
-date.formatted(date: .omitted, time: .complete)       // includes time zone
-
-// Combined
-date.formatted(date: .long, time: .shortened)         // "January 15, 2026 at 3:30 PM"
-date.formatted()                                       // platform default
-```
-
-### Component-based date formatting
+let pickup = Date.now
 
-Build custom date formats by composing components. The system reorders components for each locale.
+pickup.formatted(date: .numeric, time: .omitted)     // 6/3/2026
+pickup.formatted(date: .abbreviated, time: .omitted) // Jun 3, 2026
+pickup.formatted(date: .long, time: .omitted)        // June 3, 2026
+pickup.formatted(date: .complete, time: .omitted)    // Wednesday, June 3, 2026
 
-```swift
-// Month and day
-date.formatted(.dateTime.month().day())               // "Jan 15" (US) / "15 Jan" (UK)
-
-// Full date with weekday
-date.formatted(.dateTime.weekday(.wide).month(.wide).day().year())
-// "Thursday, January 15, 2026" (US) / "Donnerstag, 15. Januar 2026" (DE)
-
-// Month name styles
-date.formatted(.dateTime.month(.wide))                // "January"
-date.formatted(.dateTime.month(.abbreviated))         // "Jan"
-date.formatted(.dateTime.month(.narrow))              // "J"
-date.formatted(.dateTime.month(.twoDigits))           // "01"
-
-// Day styles
-date.formatted(.dateTime.day(.twoDigits))             // "15"
-date.formatted(.dateTime.day(.ordinalOfDayInMonth))   // "3" (third Thursday)
-
-// Year
-date.formatted(.dateTime.year(.defaultDigits))        // "2026"
-date.formatted(.dateTime.year(.twoDigits))            // "26"
-
-// Hour/minute
-date.formatted(.dateTime.hour().minute())             // "3:30 PM" (US, 12h) / "15:30" (DE, 24h)
-date.formatted(.dateTime.hour(.defaultDigits(amPM: .omitted)).minute())  // "3:30"
+pickup.formatted(date: .omitted, time: .shortened)   // 9:40 AM
+pickup.formatted(date: .omitted, time: .standard)    // 9:40:12 AM
+pickup.formatted(date: .omitted, time: .complete)    // adds the time zone
+pickup.formatted()                                   // platform default
 ```
 
-### SwiftUI date display
+Components: list what you want and the system arranges it for the locale.
 
 ```swift
-// Automatic format
-Text(event.date, format: .dateTime.month().day().year())
-
-// Date range
-Text(event.start...event.end)   // "Jan 15 - Jan 20, 2026"
-
-// Relative (auto-updates)
-Text(event.date, style: .relative)   // "2 hours ago", "in 3 days"
-Text(event.date, style: .timer)      // counts up/down live
-Text(event.date, style: .offset)     // "+2 hours" / "-3 days"
+pickup.formatted(.dateTime.weekday(.abbreviated).day().month(.wide))
+pickup.formatted(.dateTime.month(.narrow))            // "J"
+pickup.formatted(.dateTime.month(.twoDigits).day(.twoDigits))
+pickup.formatted(.dateTime.day(.ordinalOfDayInMonth)) // first Wednesday -> 1
+pickup.formatted(.dateTime.year(.twoDigits))
+pickup.formatted(.dateTime.year(.defaultDigits))
+pickup.formatted(.dateTime.hour().minute())           // 12h or 24h per locale
+pickup.formatted(.dateTime.hour(.defaultDigits(amPM: .omitted)).minute())
 ```
 
-### Relative date formatting
-
-```swift
-// Relative (named style)
-let relative = date.formatted(.relative(presentation: .named))
-// "yesterday", "today", "tomorrow", "last Friday", "in 2 weeks"
-
-// Relative (numeric style)
-let relativeNum = date.formatted(.relative(presentation: .numeric))
-// "1 day ago", "in 2 days", "3 weeks ago"
-
-// Relative with specific units
-let relativeCustom = date.formatted(.relative(presentation: .named, unitsStyle: .wide))
-```
+`month(_:)` takes `.wide`, `.abbreviated`, `.narrow`, `.twoDigits`. `day(_:)`
+takes `.twoDigits` or `.ordinalOfDayInMonth`, which counts which occurrence of
+that weekday the date is in the month.
 
-### Date ranges and intervals
+In SwiftUI:
 
 ```swift
-let start = Date.now
-let end = Calendar.current.date(byAdding: .day, value: 5, to: start)!
-
-// Range formatting
-(start..<end).formatted(date: .abbreviated, time: .omitted)
-// "Jan 15 - 20, 2026" (smart about shared month/year)
-
-// Duration of interval
-(start..<end).formatted(.components(style: .wide))
-// "5 days"
+Text(pickup, format: .dateTime.day().month())
+Text(pickup...pickup.addingTimeInterval(7_200))   // a range
+Text(pickup, style: .relative)                   // updates itself
+Text(pickup, style: .timer)                      // counts live
+Text(pickup, style: .offset)
 ```
 
-### ISO 8601 (for APIs, not for display)
+Relative phrasing:
 
 ```swift
-// For serialization to APIs -- NOT for user-facing display
-date.formatted(.iso8601)                              // "2026-01-15T15:30:45Z"
-date.formatted(.iso8601.dateSeparator(.dash).timeSeparator(.colon))
+let lastSync = Date.now.addingTimeInterval(-86_400)
+lastSync.formatted(.relative(presentation: .named))                   // "yesterday"
+lastSync.formatted(.relative(presentation: .numeric))                 // "1 day ago"
+lastSync.formatted(.relative(presentation: .numeric, unitsStyle: .wide))
 ```
 
-## Number Formatting
-
-### Integer and decimal
+Ranges:
 
 ```swift
-let value = 1234567
-
-value.formatted()                                      // "1,234,567" (US) / "1.234.567" (DE) / "1 234 567" (FR)
-value.formatted(.number.grouping(.never))              // "1234567"
-value.formatted(.number.precision(.significantDigits(3))) // "1,230,000"
-
-let decimal = 3.14159
-decimal.formatted(.number.precision(.fractionLength(2)))  // "3.14"
-decimal.formatted(.number.precision(.fractionLength(0...3))) // "3.142"
-
-// Notation
-value.formatted(.number.notation(.compactName))        // "1.2M" (US) / "1,2 Mio." (DE)
-value.formatted(.number.notation(.scientific))         // "1.234567E6"
+let checkIn = Date.now
+let checkOut = checkIn.addingTimeInterval(4 * 86_400)
+(checkIn..<checkOut).formatted(date: .abbreviated, time: .omitted)
+// shared month and year are written once: "Jun 3 - 7, 2026"
+(checkIn..<checkOut).formatted(.components(style: .wide))             // "4 days"
 ```
 
-### Rounding
+ISO 8601 is for the wire, never for people:
 
 ```swift
-let num = 3.456
-
-// Round to 2 fraction digits
-num.formatted(.number.precision(.fractionLength(2)).rounded(rule: .up))     // "3.46"
-num.formatted(.number.precision(.fractionLength(2)).rounded(rule: .down))   // "3.45"
-num.formatted(.number.precision(.fractionLength(2)).rounded(rule: .toNearestOrEven)) // "3.46"
+pickup.formatted(.iso8601.dateSeparator(.dash).timeSeparator(.colon))
 ```
 
-### Percent
+## Numbers
 
-```swift
-let ratio = 0.856
-
-ratio.formatted(.percent)                              // "86%" (US) / "86 %" (FR)
-ratio.formatted(.percent.precision(.fractionLength(1))) // "85.6%"
-
-// Integer percentage
-let score = 92
-score.formatted(.percent)                              // "9,200%" -- probably not what you want!
-// For integer percentages, divide first:
-(Double(score) / 100).formatted(.percent)              // "92%"
-```
-
-### Currency
-
-Always specify the currency code explicitly. The locale controls formatting (symbol position, decimal separator), but the currency code determines the currency.
+Grouping follows the locale: 2,500,000 in the US, 2.500.000 in Germany,
+2 500 000 in France.
 
 ```swift
-let price = Decimal(29.99)
+2_500_000.formatted()                                      // locale grouping
+2_500_000.formatted(.number.grouping(.never))              // 2500000
 
-// Explicit currency code (recommended)
-price.formatted(.currency(code: "USD"))                // "$29.99" (US) / "29,99 $US" (FR) / "US$29.99" (AU)
-price.formatted(.currency(code: "EUR"))                // "EUR29.99" (US) / "29,99 EUR" (DE) / "29,99 EUR" (FR)
-price.formatted(.currency(code: "JPY"))                // "JPY30" (no decimals for yen)
+0.004218.formatted(.number.precision(.significantDigits(3)))   // 0.00422
+72.5.formatted(.number.precision(.fractionLength(2)))          // 72.50
+72.5.formatted(.number.precision(.fractionLength(0...3)))      // 72.5
 
-// Narrow symbol (when space is limited)
-price.formatted(.currency(code: "USD").presentation(.narrow))  // "$29.99" even in non-US locales
+4_300_000.formatted(.number.notation(.compactName))  // "4.3M", German "4,3 Mio."
+6_022.0.formatted(.number.notation(.scientific))
 
-// In SwiftUI
-Text(price, format: .currency(code: order.currencyCode))
+18.6.formatted(.number.rounded(rule: .up, increment: 1))              // 19
+18.6.formatted(.number.rounded(rule: .down, increment: 1))            // 18
+18.5.formatted(.number.rounded(rule: .toNearestOrEven, increment: 1)) // 18
 ```
 
-**Important:** Use `Decimal` (not `Double`) for monetary values to avoid floating-point precision errors.
+Without `increment:` (or a `.precision` of zero fraction digits) the rule only
+applies at the style's default precision, so `18.6` still prints "18.6".
 
-### Ordinal numbers
+Percent multiplies by 100. The integer `92` with `.percent` prints
+"9,200%". Convert to a fraction first:
 
 ```swift
-let position = 3
-position.formatted(.number.notation(.ordinal))         // "3rd" (EN) / "3." (DE) / "3e" (FR)
+let batteryLevel = 92
+(Double(batteryLevel) / 100).formatted(.percent)                            // "92%"
+0.1275.formatted(.percent.precision(.fractionLength(1)))                    // "12.8%"
 ```
 
-## Measurement Formatting
-
-The system auto-converts units based on locale (metric vs imperial) unless you opt out.
-
-### Length / distance
+Currency: always pass `code:`. The code picks the currency; the locale only
+decides where the symbol goes and which separators are used.
 
 ```swift
-let distance = Measurement(value: 5, unit: UnitLength.kilometers)
-
-distance.formatted(.measurement(width: .wide))
-// US: "3.1 miles"  (auto-converts to imperial!)
-// DE: "5 Kilometer"
-// JP: "5 km" (with .abbreviated)
-
-distance.formatted(.measurement(width: .abbreviated))  // "3.1 mi" (US) / "5 km" (DE)
-distance.formatted(.measurement(width: .narrow))       // "3.1mi" (US) / "5km" (DE)
-
-// Prevent auto-conversion (keep original unit)
-distance.formatted(.measurement(width: .wide, usage: .asProvided))
-// US: "5 kilometers" (keeps km even in US locale)
+let fare = Decimal(124_950) / 100
+fare.formatted(.currency(code: "USD"))                      // $1,249.50 in en_US
+fare.formatted(.currency(code: "EUR"))                      // de_DE: "1.249,50" then the euro sign
+Decimal(3200).formatted(.currency(code: "JPY"))             // no decimals for yen
+fare.formatted(.currency(code: "CAD").presentation(.narrow)) // "$" when space is tight
+Text(fare, format: .currency(code: "GBP"))
 ```
 
-### Weight / mass
-
-```swift
-let weight = Measurement(value: 75, unit: UnitMass.kilograms)
+Money belongs in `Decimal`, not `Double`, so binary rounding never shows up in
+a price.
 
-weight.formatted(.measurement(width: .wide))
-// US: "165.3 pounds" / DE: "75 Kilogramm"
-
-weight.formatted(.measurement(width: .abbreviated, usage: .personWeight))
-// Uses locale-appropriate unit for body weight
-```
-
-### Temperature
+Ordinals: the iOS 26.4 SDK has no ordinal `FormatStyle` (`.number.notation`
+offers only `.automatic`, `.compactName` and `.scientific`), so this is the one
+case that still uses `NumberFormatter`:
 
 ```swift
-let temp = Measurement(value: 22, unit: UnitTemperature.celsius)
-
-temp.formatted(.measurement(width: .abbreviated))
-// US: "72 F" (auto-converts!) / FR: "22 C" / DE: "22 C"
-
-// Weather-specific (ensures locale-correct unit)
-temp.formatted(.measurement(width: .abbreviated, usage: .weather))
+let ordinals = NumberFormatter()
+ordinals.numberStyle = .ordinal
+ordinals.string(from: 3)   // "3rd", German "3.", French "3e"
 ```
 
-### Speed
+## Measurements
 
-```swift
-let speed = Measurement(value: 100, unit: UnitSpeed.kilometersPerHour)
-speed.formatted(.measurement(width: .abbreviated))
-// US: "62.1 mph" / DE: "100 km/h"
-```
-
-### Volume
+Units convert to the locale's system (metric or imperial) unless you opt out.
 
 ```swift
-let volume = Measurement(value: 500, unit: UnitVolume.milliliters)
-volume.formatted(.measurement(width: .abbreviated, usage: .drink))
-// US: "16.9 fl oz" / DE: "500 ml"
-```
+let hike = Measurement(value: 12.4, unit: UnitLength.kilometers)
+hike.formatted(.measurement(width: .wide))          // "7.7 miles" in en_US
+hike.formatted(.measurement(width: .abbreviated))   // "7.7 mi"
+hike.formatted(.measurement(width: .narrow))        // "7.7mi"
+hike.formatted(.measurement(width: .wide, usage: .asProvided))  // keeps km
 
-## Duration Formatting
+let luggage = Measurement(value: 23, unit: UnitMass.kilograms)
+luggage.formatted(.measurement(width: .abbreviated, usage: .personWeight))
 
-### Time pattern
+let outside = Measurement(value: 28, unit: UnitTemperature.celsius)
+outside.formatted(.measurement(width: .abbreviated, usage: .weather))   // F in en_US
 
-```swift
-let dur = Duration.seconds(3661) // 1 hour, 1 minute, 1 second
+let windSpeed = Measurement(value: 40, unit: UnitSpeed.kilometersPerHour)
+windSpeed.formatted(.measurement(width: .abbreviated))   // mph in en_US
 
-dur.formatted(.time(pattern: .hourMinuteSecond))       // "1:01:01"
-dur.formatted(.time(pattern: .hourMinute))             // "1:01"
-dur.formatted(.time(pattern: .minuteSecond))           // "61:01"
+let bottle = Measurement(value: 500, unit: UnitVolume.milliliters)
+bottle.formatted(.measurement(width: .abbreviated, usage: .liquid))      // "1.1 pt" in en_US
 ```
 
-### Units style (iOS 16+)
-
-```swift
-dur.formatted(.units(allowed: [.hours, .minutes], width: .wide))
-// "1 hour, 1 minute" (EN) / "1 Stunde, 1 Minute" (DE)
+Usage hints such as `.personWeight`, `.weather` and `.liquid` (iOS 16) choose
+the unit people expect for that kind of value.
 
-dur.formatted(.units(allowed: [.hours, .minutes], width: .abbreviated))
-// "1 hr, 1 min" (EN) / "1 Std., 1 Min." (DE)
+## Durations
 
-dur.formatted(.units(allowed: [.hours, .minutes], width: .narrow))
-// "1h 1m"
-
-// Maximum unit count
-dur.formatted(.units(allowed: [.hours, .minutes, .seconds],
-                     width: .abbreviated,
-                     maximumUnitCount: 2))
-// "1 hr, 1 min" (drops seconds)
+```swift
+let workout = Duration.seconds(3_725)
+workout.formatted(.time(pattern: .hourMinuteSecond))   // "1:02:05"
+workout.formatted(.time(pattern: .hourMinute))         // "1:02"
+workout.formatted(.time(pattern: .minuteSecond))       // "62:05", minutes may pass 59
+
+// iOS 16+
+workout.formatted(.units(allowed: [.hours, .minutes], width: .wide))   // "1 hour, 2 minutes"
+workout.formatted(.units(allowed: [.hours, .minutes, .seconds], width: .abbreviated))
+workout.formatted(.units(width: .narrow, maximumUnitCount: 1))         // "1h"
 ```
 
-## PersonNameComponents Formatting
+Widths are `.wide`, `.abbreviated` and `.narrow`; `maximumUnitCount:` drops the
+smaller units.
 
-Respects locale conventions for name ordering (given-family vs family-given).
+## Person names
 
 ```swift
-var name = PersonNameComponents()
-name.givenName = "John"
-name.familyName = "Appleseed"
-name.namePrefix = "Dr."
-name.nickname = "Johnny"
-
-name.formatted(.name(style: .long))        // "Dr. John Appleseed" (US) / "Appleseed John" (JP)
-name.formatted(.name(style: .medium))      // "John Appleseed" (US) / "Appleseed John" (JP)
-name.formatted(.name(style: .short))       // "John" (US) / "Appleseed" (JP)
-name.formatted(.name(style: .abbreviated)) // "JA" (initials)
-
-// In SwiftUI
-Text(name, format: .name(style: .medium))
+var guest = PersonNameComponents()
+guest.namePrefix = "Dr."
+guest.givenName = "Hana"
+guest.familyName = "Sato"
+
+guest.formatted(.name(style: .long))        // includes the prefix; order follows locale
+guest.formatted(.name(style: .medium))
+guest.formatted(.name(style: .short))       // "Hana" in en_US
+guest.formatted(.name(style: .abbreviated)) // initials
+Text(guest, format: .name(style: .medium))
 ```
 
-## ByteCountFormatStyle
-
-Format file sizes with locale-appropriate units.
+## Byte counts
 
 ```swift
-let bytes: Int64 = 1_536_000
-
-bytes.formatted(.byteCount(style: .file))      // "1.5 MB"
-bytes.formatted(.byteCount(style: .memory))    // "1.46 MB" (uses 1024-based)
-bytes.formatted(.byteCount(style: .binary))    // "1.46 MB"
-
-// Specific allowed units
-bytes.formatted(.byteCount(style: .file, allowedUnits: [.kb]))  // "1,536 kB"
+let backupSize: Int64 = 3_400_000_000
+backupSize.formatted(.byteCount(style: .file))
+backupSize.formatted(.byteCount(style: .memory))   // 1024-based
+backupSize.formatted(.byteCount(style: .binary))
+Int64(5_120).formatted(.byteCount(style: .file, allowedUnits: [.kb]))
 ```
 
-## ListFormatStyle
-
-Join arrays into grammatically correct lists.
+## Lists
 
 ```swift
-let fruits = ["Apples", "Oranges", "Bananas"]
-
-fruits.formatted(.list(type: .and))
-// EN: "Apples, Oranges, and Bananas"
-// FR: "Apples, Oranges et Bananas"
-// AR: "Apples وOranges وBananas"
+let toppings = ["olives", "basil", "garlic"]
+toppings.formatted(.list(type: .and))   // "olives, basil, and garlic"; French uses "et"
+toppings.formatted(.list(type: .or))
 
-fruits.formatted(.list(type: .or))
-// EN: "Apples, Oranges, or Bananas"
+let tips: [Decimal] = [5, 10, 15]
+tips.formatted(.list(memberStyle: .currency(code: "USD"), type: .or))
 
-// With member formatting
-let prices = [Decimal(1.99), Decimal(2.49), Decimal(3.99)]
-prices.formatted(.list(memberStyle: .currency(code: "USD"), type: .and))
-// "$1.99, $2.49, and $3.99"
-
-// Two items
-["Red", "Blue"].formatted(.list(type: .and))
-// "Red and Blue" (no Oxford comma for two items)
+["olives", "basil"].formatted(.list(type: .and))   // "olives and basil", no serial comma
 ```
 
-## Custom FormatStyle Implementation
+## Custom styles
 
-Create a reusable `FormatStyle` for domain-specific formatting.
+Designing custom and parseable styles is `swift-formatstyle` territory. The
+shape, for recognition:
 
 ```swift
-struct AbbreviatedCountStyle: FormatStyle {
+struct ScoreFormat: FormatStyle {
     func format(_ value: Int) -> String {
+        let number = Double(value)
+        let style = FloatingPointFormatStyle<Double>.number.precision(.fractionLength(0...1))
         switch value {
-        case ..<1_000:
-            return "\(value)"
-        case 1_000..<1_000_000:
-            let k = Double(value) / 1_000.0
-            return k.formatted(.number.precision(.fractionLength(0...1))) + "K"
-        case 1_000_000..<1_000_000_000:
-            let m = Double(value) / 1_000_000.0
-            return m.formatted(.number.precision(.fractionLength(0...1))) + "M"
-        default:
-            let b = Double(value) / 1_000_000_000.0
-            return b.formatted(.number.precision(.fractionLength(0...1))) + "B"
+        case 1_000_000_000...: return (number / 1_000_000_000).formatted(style) + "B"
+        case 1_000_000...: return (number / 1_000_000).formatted(style) + "M"
+        case 1_000...: return (number / 1_000).formatted(style) + "K"
+        default: return value.formatted()
         }
     }
 }
 
-extension FormatStyle where Self == AbbreviatedCountStyle {
-    static var abbreviatedCount: AbbreviatedCountStyle { .init() }
+extension FormatStyle where Self == ScoreFormat {
+    static var score: ScoreFormat { ScoreFormat() }
 }
 
-// Usage
-let followers = 12_500
-followers.formatted(.abbreviatedCount)  // "12.5K"
-
-// In SwiftUI
-Text(followers, format: .abbreviatedCount)
+let shown = 48_200.formatted(.score)     // "48.2K"
+Text(48_200, format: .score)
 ```
 
-### Custom ParseableFormatStyle (for input parsing)
-
-```swift
-struct AbbreviatedCountStyle: ParseableFormatStyle {
-    var parseStrategy: AbbreviatedCountParseStrategy { .init() }
-
-    func format(_ value: Int) -> String { /* same as above */ }
-}
-
-struct AbbreviatedCountParseStrategy: ParseStrategy {
-    func parse(_ value: String) throws -> Int {
-        let cleaned = value.uppercased().trimmingCharacters(in: .whitespaces)
-        if cleaned.hasSuffix("K") {
-            guard let num = Double(cleaned.dropLast()) else { throw parseError }
-            return Int(num * 1_000)
-        }
-        // ... handle M, B, plain numbers
-        guard let num = Int(cleaned) else { throw parseError }
-        return num
-    }
-
-    private var parseError: some Error {
-        DecodingError.dataCorrupted(.init(codingPath: [], debugDescription: "Invalid count"))
-    }
-}
-```
+A parseable variant adds `ParseableFormatStyle` with a `parseStrategy` whose
+`parse(_:) throws` reads the suffix back and throws on malformed input, for
+example `DecodingError.dataCorrupted`. Send any real implementation work there.
 
-## Forcing a Specific Locale
+## Pinning a locale
 
-Occasionally you need a specific locale (server APIs, fixed-format exports). Use `.locale()` modifier:
+`.locale(_:)` forces a locale, which is right for serialization or for a
+document that must always look one way, such as a German invoice PDF:
 
 ```swift
-// Force US format for API serialization (not user display)
-let usPrice = price.formatted(.currency(code: "USD").locale(Locale(identifier: "en_US")))
-
-// Force a date format for an API
-let apiDate = date.formatted(.iso8601)  // Prefer ISO 8601 for APIs
-
-// Force German format for a German-language PDF export
-let deDate = date.formatted(.dateTime.month(.wide).day().year().locale(Locale(identifier: "de_DE")))
+let invoiceDate = Date.now.formatted(.dateTime.day().month().year().locale(Locale(identifier: "de_DE")))
+let payloadDate = Date.now.formatted(.iso8601)   // preferred for APIs
 ```
 
-**Warning:** Never force a locale for user-facing UI. Always let the system locale drive user-visible formatting.
-
-## RTL Layout Deep Dive
-
-### How SwiftUI auto-mirrors
+Never pin a locale in user-facing UI.
 
-SwiftUI respects `layoutDirection` from the environment. When the user's language is RTL:
+## Right-to-left in depth
 
-1. **HStack**: Children render right-to-left
-2. **Leading/Trailing**: `.leading` = right side, `.trailing` = left side
-3. **Padding**: `.padding(.leading, 16)` applies to right side
-4. **NavigationStack**: Back button appears on trailing (left) side
-5. **Lists**: Disclosure chevrons point left
-6. **ScrollView**: Horizontal scrolling starts from the right
-7. **Text alignment**: Default alignment follows reading direction
+SwiftUI takes `layoutDirection` from the environment. Under RTL, `.leading` is
+the right edge, horizontal `ScrollView` content starts at the right, list
+chevrons point left and the back button sits on the left.
 
-### Image flipping
+Flip: `chevron.forward`, `arrow.right` and custom directional assets, using
+`.flipsForRightToLeftLayoutDirection(true)`.
 
-```swift
-// Directional images SHOULD flip
-Image(systemName: "chevron.forward")
-    .flipsForRightToLeftLayoutDirection(true)
-
-Image(systemName: "arrow.right")
-    .flipsForRightToLeftLayoutDirection(true)
-
-Image("progress-arrow")
-    .flipsForRightToLeftLayoutDirection(true)
-
-// These should NOT flip:
-// - Logos and brand marks
-// - Photos and illustrations
-// - Clock faces (clockwise is universal)
-// - Music notation
-// - Checkmarks
-// - Mathematical symbols (+, -, =)
-// - Media playback controls (play triangle always points right)
-
-// SF Symbols with .rtl variant auto-flip (e.g., text.alignleft has text.alignright)
-// Check SF Symbols app for RTL variants
-```
+Do not flip: logos and brand marks, photos and illustrations, clock faces,
+music notation, checkmarks, mathematical symbols, media playback controls.
 
-### Environment-based testing
+SF Symbols that ship an RTL variant switch on their own; the SF Symbols app
+shows which do.
 
 ```swift
-// Preview with RTL
-#Preview("Arabic RTL") {
-    ContentView()
+#Preview("Seat map, Hebrew") {
+    SeatMapView()
         .environment(\.layoutDirection, .rightToLeft)
-        .environment(\.locale, Locale(identifier: "ar"))
+        .environment(\.locale, Locale(identifier: "he"))
 }
 
-// Preview with both directions side by side
-#Preview("LTR vs RTL") {
-    HStack(spacing: 0) {
-        ContentView()
-            .environment(\.layoutDirection, .leftToRight)
-            .frame(maxWidth: .infinity)
-        Divider()
-        ContentView()
-            .environment(\.layoutDirection, .rightToLeft)
-            .environment(\.locale, Locale(identifier: "ar"))
-            .frame(maxWidth: .infinity)
+#Preview("Both directions") {
+    HStack {
+        FareRow().environment(\.layoutDirection, .leftToRight)
+        FareRow().environment(\.layoutDirection, .rightToLeft)
     }
 }
 ```
 
-### Semantic content attributes (UIKit interop)
-
-When mixing UIKit views via `UIViewRepresentable`, set semantic content attribute:
+UIKit views inside a `UIViewRepresentable` read `semanticContentAttribute`:
+`.forceLeftToRight`, `.forceRightToLeft`, or `.unspecified`, the default, which
+follows the system.
 
 ```swift
-class MyUIView: UIView {
-    override var semanticContentAttribute: UISemanticContentAttribute {
-        // .forceLeftToRight for phone numbers, code
-        // .forceRightToLeft to force RTL
-        // .unspecified to follow system (default)
-        .unspecified
+struct CardNumberField: UIViewRepresentable {
+    func makeUIView(context: Context) -> UITextField {
+        let field = UITextField()
+        field.semanticContentAttribute = .forceLeftToRight
+        return field
     }
+    func updateUIView(_ uiView: UITextField, context: Context) {}
 }
 ```
 
-### Bidirectional text
-
-When mixing LTR and RTL text (e.g., English brand names in Arabic text), Unicode bidirectional algorithm handles it automatically. For edge cases:
+Mixed-direction text follows the Unicode bidirectional algorithm. For edge
+cases like a phone number inside Arabic text, prefix a left-to-right mark
+`\u{200E}`, or set `.environment(\.layoutDirection, .leftToRight)` on that one
+view.
 
-```swift
-// Force LTR for specific content within RTL context
-Text("\u{200E}+1 (555) 123-4567")  // LTR mark before phone number
-
-// Or use environment override on a specific view
-Text(phoneNumber)
-    .environment(\.layoutDirection, .leftToRight)
-```
+| Problem | Fix |
+|---|---|
+| `.padding(.left)` | `.padding(.leading)` |
+| `.offset(x:)` to push content one way | Alignment or trailing padding |
+| `.multilineTextAlignment(.left)` | `.multilineTextAlignment(.leading)` |
+| Rounding top-left and top-right corners | Round leading and trailing corners |
+| "Swipe right to archive" | "Swipe toward the leading edge", or rely on system swipe actions |
 
-### Common RTL pitfalls
+## ScaledMetric and Dynamic Type
 
-| Issue | Wrong | Correct |
-|-------|-------|---------|
-| Fixed position | `.padding(.left, 16)` | `.padding(.leading, 16)` |
-| Absolute offset | `.offset(x: -20)` for "move left" | Use alignment or `.padding(.trailing)` |
-| Text alignment | `.multilineTextAlignment(.left)` | `.multilineTextAlignment(.leading)` |
-| Corner radius | Only rounding top-left/top-right | Round leading/trailing corners |
-| Swipe gestures | "Swipe right to delete" | "Swipe to leading edge" -- or use system gestures |
-
-## `@ScaledMetric` for Dynamic Type
-
-Use `@ScaledMetric` to make custom spacing, icon sizes, and padding scale with the user's Dynamic Type setting.
+`@ScaledMetric(relativeTo:)` scales your own numbers, such as spacing, icon
+size and padding, together with the text style you name.
 
 ```swift
-struct ProfileRow: View {
-    @ScaledMetric(relativeTo: .body) private var avatarSize = 44.0
-    @ScaledMetric(relativeTo: .body) private var spacing = 12.0
+struct ContactRow: View {
+    @ScaledMetric(relativeTo: .body) private var portraitSide: CGFloat = 36
+    @ScaledMetric(relativeTo: .body) private var gap: CGFloat = 10
 
     var body: some View {
-        HStack(spacing: spacing) {
-            AvatarView()
-                .frame(width: avatarSize, height: avatarSize)
-            VStack(alignment: .leading) {
-                Text(name).font(.headline)
-                Text(subtitle).font(.subheadline)
-            }
+        HStack(spacing: gap) {
+            Image(systemName: "person.crop.circle")
+                .resizable()
+                .frame(width: portraitSide, height: portraitSide)
+            Text("Mira Lopez")
         }
     }
 }
 ```
 
-### relativeTo parameter
-
-`@ScaledMetric` scales proportionally to a text style. Choose the text style that the metric logically accompanies:
-
-| Text style | Base size | Use for |
-|------------|-----------|---------|
-| `.body` | 17pt | General spacing, icons next to body text |
-| `.caption` | 12pt | Small icons, fine spacing |
-| `.title` | 28pt | Large icons, hero spacing |
-| `.largeTitle` | 34pt | Hero images, splash elements |
+Which style to scale against:
 
-### Testing Dynamic Type
+| `relativeTo` | Base size | Good for |
+|---|---|---|
+| `.body` | 17 pt | General spacing |
+| `.caption` | 12 pt | Small icons |
+| `.title` | 28 pt | Large icons |
+| `.largeTitle` | 34 pt | Hero elements |
 
 ```swift
-// Preview with large text
-#Preview("Accessibility XXL") {
-    ContentView()
-        .dynamicTypeSize(.accessibility3)
+#Preview("Accessibility 3") {
+    ContactRow().dynamicTypeSize(.accessibility3)
 }
 
-// Preview matrix
-#Preview("Dynamic Type Sizes") {
+#Preview("All sizes") {
     ScrollView {
         ForEach(DynamicTypeSize.allCases, id: \.self) { size in
-            ContentView()
-                .dynamicTypeSize(size)
-                .padding()
-                .border(Color.gray)
+            ContactRow().dynamicTypeSize(size)
         }
     }
 }
 ```
 
-## Layout Testing with Accessibility Inspector
-
-Accessibility Inspector (Xcode > Open Developer Tool > Accessibility Inspector) provides:
-
-1. **Audit**: Scans running app for accessibility issues including truncated text
-2. **Inspection**: Shows exact font sizes and Dynamic Type response
-3. **Settings**: Override Dynamic Type size, Bold Text, Reduce Motion on device without changing system settings
-
-### Quick test workflow
-
-1. Launch app in Simulator
-2. Open Accessibility Inspector, target the Simulator
-3. Use the Settings panel to set Dynamic Type to "Accessibility XXL"
-4. Navigate through every screen -- look for truncated text, overlapping elements, broken layouts
-5. Switch to RTL (set language to Arabic in scheme options)
-6. Repeat navigation -- check all alignment and reading order
-
-## Quick Reference Table
-
-| Data type | FormatStyle | Example output (US) |
-|-----------|-------------|---------------------|
-| `Date` | `.dateTime.month().day().year()` | "Jan 15, 2026" |
-| `Date` range | `(start..<end).formatted(date:time:)` | "Jan 15 - 20, 2026" |
-| `Date` relative | `.relative(presentation: .named)` | "yesterday" |
-| `Int` | `.number` | "1,234,567" |
-| `Int` ordinal | `.number.notation(.ordinal)` | "3rd" |
-| `Int` compact | `.number.notation(.compactName)` | "1.2M" |
-| `Double` | `.number.precision(.fractionLength(2))` | "3.14" |
-| `Double` | `.percent` | "85.6%" |
-| `Decimal` | `.currency(code: "USD")` | "$29.99" |
-| `Measurement` | `.measurement(width: .abbreviated)` | "5 km" / "3.1 mi" |
-| `Duration` | `.time(pattern: .hourMinuteSecond)` | "1:01:01" |
-| `Duration` | `.units(width: .abbreviated)` | "1 hr, 1 min" |
-| `PersonNameComponents` | `.name(style: .medium)` | "John Doe" |
-| `Int64` (bytes) | `.byteCount(style: .file)` | "1.5 MB" |
-| `[String]` | `.list(type: .and)` | "A, B, and C" |
+## Checking layout with Accessibility Inspector
+
+Open it from Xcode > Open Developer Tool > Accessibility Inspector.
+
+- Audit finds problems, truncated text among them.
+- Inspection shows font sizes and whether an element reacts to Dynamic Type.
+- Settings overrides Dynamic Type, Bold Text and Reduce Motion without touching
+  system settings.
+
+Routine:
+
+1. Run the app in Simulator and point the inspector at it.
+2. Set Dynamic Type to Accessibility XXL.
+3. Visit every screen and look for truncation and overlap.
+4. Switch the scheme's App Language to Arabic.
+5. Visit the screens again for alignment and reading order.
+
+## Cheat sheet
+
+| Value | Style | en_US sample |
+|---|---|---|
+| `Date` | `.dateTime.month().day().year()` | Jun 3, 2026 |
+| Date range | `(start..<end).formatted(date:time:)` | Jun 3 - 7, 2026 |
+| Relative date | `.relative(presentation: .named)` | yesterday |
+| `Int` | `.number` | 2,500,000 |
+| `Int` | `NumberFormatter` with `numberStyle = .ordinal` | 3rd |
+| `Int` | `.number.notation(.compactName)` | 4.3M |
+| `Double` | `.number.precision(.fractionLength(2))` | 72.50 |
+| `Double` | `.percent` | 92% (for 0.92) |
+| `Decimal` | `.currency(code: "USD")` | $1,249.50 |
+| `Measurement` | `.measurement(width: .abbreviated)` | 7.7 mi |
+| `Duration` | `.time(pattern: .hourMinuteSecond)` | 1:02:05 |
+| `Duration` | `.units(width: .abbreviated)` | 1 hr, 2 min, 5 sec |
+| `PersonNameComponents` | `.name(style: .medium)` | Hana Sato |
+| `Int64` | `.byteCount(style: .file)` | 3.4 GB |
+| `[String]` | `.list(type: .and)` | olives, basil, and garlic |