version: "1.0.0" name: pgts-apple description: Apply Pretty Good Type Scale (PGTS) in iOS, iPadOS, and macOS Swift or SwiftUI projects using the generated PGTS.swift export. Use when a coding agent needs to map PGTS roles to Apple text styles, Dynamic Type, custom fonts, or native app typography.

PGTS Apple

Use this skill when the target is an Apple platform project. Use platforms/apple/PGTS.swift as the generated starter export, tokens/pgts.tokens.json as the canonical PGTS source, and tokens/apple-dynamic-type.json as the Apple Dynamic Type adapter source.

Canonical roles: editorial-mega-display, display-large, display, headline-large, headline, title-large, title, body, footnote, caption, legal.

Lean roles for product UI: display, headline-large, title-large, title, body, footnote.

Integration

Copy or import the generated Swift file into the host app module. Add a package or module declaration only if the host project requires it.

Use PGTSRole for semantic identity, PGTSContext for mobile, desktop, or print contexts, and PGTS.style(_:) for the numeric values:

let style = PGTS.style(.display)
let font = style.font(for: .mobile, design: .serif)

Dynamic Type

Use role.dynamicTypeTextStyle as the semantic scaling hint. The generated file provides point-size anchors, Apple text-style mappings, Dynamic Type size names, and preview helpers, but the host app should still rely on Apple runtime scaling for final rendering.

For SwiftUI custom fonts, use Font.custom(name, size: style.pointSize(for: platform), relativeTo: role.dynamicTypeTextStyle) or style.customFont(name:platform:).

For UIKit custom fonts, use UIFontMetrics(forTextStyle: role.uiKitTextStyle).scaledFont(for:) and set adjustsFontForContentSizeCategory = true on the text control.

Use style.scaledPointSize(for:dynamicTypeSize:) and style.scaledLineHeight(for:dynamicTypeSize:) for previews, web visualization, and design-token inspection. Do not replace Apple runtime scaling with these preview values in production app text controls.

For tvOS, treat generated values as projected until exact tvOS 27 SDK probe data replaces the projection source. Standard SwiftUI and UIKit text controls should still use the platform Dynamic Type APIs.

Font Ownership

PGTS does not bundle fonts. Apply the host app's custom font separately and test the selected typeface for x-height, ascenders, descenders, optical size, and line-height behavior.

Verification

• Confirm all lean roles exist in the host typography layer.
• Check Dynamic Type or text-size accessibility settings.
• Test xSmall, large, xxxLarge, accessibility1, and accessibility5.
• Check tvOS Large Text states when targeting tvOS 27 or later.
• Verify display roles do not clip on compact widths.
• Verify footnote, caption, and legal remain readable.
• Use examples/apple-dynamic-type.html for web-first inspection of the Apple Dynamic Type scale.
• Run npm run build after token changes and npm run validate before returning work.