name: typography-ref description: Apple platform typography reference (San Francisco fonts, text styles, Dynamic Type, tracking, leading, internationalization) through iOS 26

Typography Reference

Complete reference for typography on Apple platforms including San Francisco font system, text styles, Dynamic Type, tracking, leading, and internationalization through iOS 26.

San Francisco Font System

Font Families

SF Pro and SF Pro Rounded (iOS, iPadOS, macOS, tvOS)

Main system fonts for most UI elements
Rounded variant for friendly, approachable interfaces (e.g., Reminders app)

SF Compact and SF Compact Rounded (watchOS, narrow columns)

Optimized for constrained spaces and small sizes
watchOS default system font

SF Mono (Code environments, monospaced text)

Monospaced font for code editors and technical content
Consistent character widths for alignment

New York (Serif system font)

Serif alternative for editorial content
Works with text styles just like SF Pro

Variable Font Axes

Weight Axis (9 weights)

Ultralight, Thin, Light, Regular, Medium, Semibold, Bold, Heavy, Black
Continuous weight spectrum via variable fonts
Avoid light weights at small sizes (legibility issues)

Width Axis (WWDC 2022)

Condensed — narrowest width
Compressed — narrow width
Regular — standard width (default)
Expanded — wide width

Access via:

// iOS/macOS
let descriptor = UIFontDescriptor(fontAttributes: [
    .family: "SF Pro",
    kCTFontWidthTrait: 1.0 // 1.0 = Expanded
])

SF Arabic (WWDC 2022)

Matches SF Pro design language for Arabic text
Proper right-to-left support

Optical Sizes

Variable fonts automatically adjust optical size based on point size:

Text variant (< 20pt) — more spacing, sturdier strokes
Display variant (≥ 20pt) — tighter spacing, refined details
Smooth transition (17-28pt) with variable SF Pro

From WWDC 2020:

"TextKit 2 abstracts away glyph handling to provide a consistent experience for international text."

Text Styles & Dynamic Type

System Text Styles

Text Style	Default Size (iOS)	Use Case
`.largeTitle`	34pt	Primary page headings
`.title`	28pt	Secondary headings
`.title2`	22pt	Tertiary headings
`.title3`	20pt	Quaternary headings
`.headline`	17pt (Semibold)	Emphasized body text
`.body`	17pt	Primary body text
`.callout`	16pt	Secondary body text
`.subheadline`	15pt	Tertiary body text
`.footnote`	13pt	Footnotes, captions
`.caption`	12pt	Small annotations
`.caption2`	11pt	Smallest annotations

Emphasized Text Styles

Apply .bold symbolic trait to get emphasized variants:

// UIKit
let descriptor = UIFontDescriptor.preferredFontDescriptor(withTextStyle: .title1)
let boldDescriptor = descriptor.withSymbolicTraits(.traitBold)!
let font = UIFont(descriptor: boldDescriptor, size: 0)

// SwiftUI
Text("Bold Title")
    .font(.title.bold())

Actual weights by text style:

Some styles map to medium
Others map to semibold, bold, or heavy
Depends on semantic hierarchy

Leading Variants

Tight Leading (reduces line height by 2pt on iOS, 1pt on watchOS):

// UIKit
let descriptor = UIFontDescriptor.preferredFontDescriptor(withTextStyle: .body)
let tightDescriptor = descriptor.withSymbolicTraits(.traitTightLeading)!

// SwiftUI
Text("Compact text")
    .font(.body.leading(.tight))

Loose Leading (increases line height by 2pt on iOS, 1pt on watchOS):

// SwiftUI
Text("Spacious paragraph")
    .font(.body.leading(.loose))

Dynamic Type

Automatic Scaling (iOS): Text styles scale automatically based on user preferences from Settings → Display & Brightness → Text Size.

Custom Fonts with Dynamic Type:

// UIKit - UIFontMetrics
let customFont = UIFont(name: "Avenir-Medium", size: 34)!
let bodyMetrics = UIFontMetrics(forTextStyle: .body)
let scaledFont = bodyMetrics.scaledFont(for: customFont)

// Also scale constants
let spacing = bodyMetrics.scaledValue(for: 20.0)

// SwiftUI - .font(.custom(_:relativeTo:))
Text("Custom scaled text")
    .font(.custom("Avenir-Medium", size: 34, relativeTo: .body))

// @ScaledMetric for values
@ScaledMetric(relativeTo: .body) var padding: CGFloat = 20

Platform Differences

macOS

No Dynamic Type support in AppKit
Text style sizes optimized for macOS control sizes
Catalyst apps use iOS sizes × 77% (legacy) or macOS-optimized sizes ("Optimize Interface for Mac")

watchOS

Smaller text styles optimized for watch faces
Tight leading default for compact displays

visionOS

System fonts work identically to iOS
Dynamic Type support included

Tracking & Leading

Tracking (Letter Spacing)

Tracking adjusts space between letters. Essential for optical size behavior.

Size-Specific Tracking Tables:

SF Pro includes tracking values that vary by point size to maintain optimal spacing:

Larger sizes: tighter tracking
Smaller sizes: looser tracking

Example from Apple Design Resources:

34pt (largeTitle): +0.016 tracking
17pt (body): +0.008 tracking
11pt (caption2): +0.06 tracking

Tight Tracking API (for fitting text):

// UIKit
textView.allowsDefaultTightening(for: .byTruncatingTail)

// SwiftUI
Text("Long text that needs to fit")
    .lineLimit(1)
    .minimumScaleFactor(0.5) // Allows tight tracking

Manual Tracking:

// UIKit
let attributes: [NSAttributedString.Key: Any] = [
    .font: UIFont.preferredFont(forTextStyle: .body),
    .kern: 2.0 // 2pt tracking
]

// SwiftUI
Text("Tracked text")
    .tracking(2.0)
    .kerning(2.0) // Alternative API

Important: Use .tracking() not .kerning() API for semantic correctness. Tracking disables ligatures when necessary; kerning does not.

Leading (Line Spacing)

Default Line Height: Calculated from font's built-in metrics (ascender + descender + line gap).

Language-Aware Adjustments: iOS 17+ automatically increases line height for scripts with tall ascenders/descenders:

Arabic
Thai, Lao
Hindi, Bengali, Telugu

From WWDC 2023:

"Automatic line height adjustment for scripts with variable heights"

Manual Leading:

// UIKit
let paragraphStyle = NSMutableParagraphStyle()
paragraphStyle.lineSpacing = 8.0 // 8pt additional space

// SwiftUI
Text("Custom spacing")
    .lineSpacing(8.0)

Third-Party Font Tracking

New in iOS 18: Font vendors can embed tracking tables in custom fonts using STAT table + CTFont optical size attribute.

let attributes: [String: Any] = [
    kCTFontOpticalSizeAttribute as String: pointSize
]
let descriptor = CTFontDescriptorCreateWithAttributes(attributes as CFDictionary)
let font = CTFontCreateWithFontDescriptor(descriptor, pointSize, nil)

Internationalization

Bidirectional Text

Complex Script Example (from WWDC 2021):

Kannada word "October":

Character index 4 has split vowel → 2 glyphs
Glyphs reorder before ligature application
Glyph index ≠ character index

This is why TextKit 2 uses NSTextLocation instead of integer indices.

Hebrew/Arabic Selection: Single visual selection = multiple NSRanges in AttributedString due to right-to-left layout.

Line Breaking

Language-Aware (iOS 17+):

Chinese, Japanese, Korean: break at semantic boundaries
German: avoid breaking compound words
English: prefer breaking at hyphens

Even Line Breaking (TextKit 2): Justified paragraphs use improved line breaking algorithm:

Reduces stretched-out lines
More even interword spacing
Automatic in TextKit 2

Text Clipping Prevention

Best Practices:

Use Dynamic Type (auto-adjusts)
Set .lineLimit(nil) or .lineLimit(2...5) in SwiftUI
Use .minimumScaleFactor() for constrained single-line text
Test with large accessibility sizes

CSS & Web Typography

System UI Font Families:

font-family: system-ui; /* SF Pro */
font-family: ui-rounded; /* SF Pro Rounded */
font-family: ui-serif; /* New York */
font-family: ui-monospace; /* SF Mono */

Legacy:

font-family: -apple-system; /* deprecated, use system-ui */

Code Examples

Emphasized Large Title (SwiftUI)

Text("Recipe Editor")
    .font(.largeTitle.bold()) // Emphasized variant

Custom Font + Dynamic Type (UIKit)

let customFont = UIFont(name: "Avenir-Medium", size: 17)!
let metrics = UIFontMetrics(forTextStyle: .body)
label.font = metrics.scaledFont(for: customFont)
label.adjustsFontForContentSizeCategory = true

Rounded Design (UIKit)

let descriptor = UIFontDescriptor
    .preferredFontDescriptor(withTextStyle: .largeTitle)
    .withDesign(.rounded)!
let font = UIFont(descriptor: descriptor, size: 0)

Rounded Design (SwiftUI)

Text("Today")
    .font(.largeTitle.bold())
    .fontDesign(.rounded)

ScaledMetric (SwiftUI)

struct RecipeView: View {
    @ScaledMetric(relativeTo: .body) var padding: CGFloat = 20

    var body: some View {
        Text("Recipe")
            .padding(padding) // Scales with Dynamic Type
    }
}

typography-ref