apple-typography-workflow

name

apple-typography-workflow

description

Guide Apple platform typography decisions and implementation across SwiftUI Font, UIKit UIFont, AppKit NSFont, San Francisco system fonts, SF Pro, SF Compact, SF Mono, SF Pro Rounded, New York serif design, Dynamic Type, text styles, fontDesign, fontWeight, fontWidth, monospaced digits, custom font bundle integration, font licensing and redistribution boundaries, accessibility scaling, and Xcode font asset validation. Use when a task mentions Apple typography, San Francisco, SF Pro, SF Compact, SF Mono, New York, Dynamic Type, UIFontMetrics, preferredFont, NSFont.TextStyle, custom fonts, UIAppFonts, ATSApplicationFontsPath, or text style repair.

Apple Typography Workflow

Purpose

Use this skill to choose, implement, repair, and validate Apple platform typography that respects system font behavior, Dynamic Type, accessibility, platform conventions, and custom-font bundle boundaries.

It is not the generic visual-design workflow, not the SF Symbols workflow, and not the Xcode project execution workflow.

When To Use

• Use this skill when the task mentions Apple typography, San Francisco, SF Pro, SF Compact, SF Mono, SF Pro Rounded, New York, system fonts, Dynamic Type, text styles, font designs, font weights, font widths, monospaced digits, or custom font integration.
• Use this skill when code uses SwiftUI Font, fontDesign, fontWeight, fontWidth, UIKit UIFont, UIFontMetrics, UIFontDescriptor.SystemDesign, AppKit NSFont, preferred fonts, UIAppFonts, or ATSApplicationFontsPath.
• Use this skill when text does not scale correctly, hard-coded point sizes are hurting accessibility, custom fonts are not loading, or a project is bundling fonts unnecessarily.
• Recommend apple-ui-accessibility-workflow when the work is broader accessibility review beyond typography scaling and readability.
• Recommend sf-symbols-workflow when the task is icon or symbol selection rather than text.
• Recommend xcode-build-run-workflow when the next step is adding font files, Info.plist keys, bundle resources, target membership, preview, build, or simulator validation.

Single-Path Workflow

1. Classify the typography job:
   • system text style choice
   • San Francisco or system design choice
   • monospaced or monospaced-digit choice
   • New York or serif design choice
   • Dynamic Type repair
   • custom font integration
   • font licensing or redistribution boundary
   • Xcode resource or Info.plist validation
2. Apply the Apple docs gate:
   • read the relevant Apple documentation first
   • state the documented behavior being relied on before recommending implementation
   • if Apple docs and current code disagree, stop and surface the conflict
   • if no relevant Apple docs can be found, say that explicitly before proceeding
3. Choose system typography first:
   • use SwiftUI Font text styles and system designs for SwiftUI
   • use UIFont.preferredFont(forTextStyle:) and UIFontMetrics for UIKit
   • use NSFont.preferredFont(forTextStyle:options:) or system font APIs for AppKit
   • use custom font files only when the app's brand or content requirements justify them
4. Preserve accessibility scaling:
   • prefer Dynamic Type text styles over hard-coded point sizes
   • scale custom fonts through the framework-supported metrics path
   • ensure controls and layout can adapt to larger text
   • avoid using font weight, width, size, or color as the only signal for state
5. Check platform and asset boundaries:
   • do not bundle Apple system font files for normal app UI
   • avoid machine-local font paths in public docs, project files, or scripts
   • use documented Info.plist keys and Xcode resource membership for custom font files
   • state licensing and redistribution concerns once when the task asks to extract, modify, bundle, or publish Apple font assets
6. Return one recommendation path with:
   • chosen text style or font design
   • Dynamic Type behavior
   • custom font or system font decision
   • documented Apple behavior relied on
   • validation or handoff step

Inputs

• request: optional free-text task description used to classify the typography question.
• target_framework: optional framework emphasis such as swiftui, uikit, appkit, or mixed.
• target_platforms: optional platform list such as ios, macos, watchos, tvos, visionos, or mixed-apple.
• font_assets: optional paths or names for custom font files.
• text_role: optional text role such as body, headline, caption, code, tabular data, brand display, or dense utility UI.
• Defaults:
  • Apple docs-first guidance always applies
  • system typography is preferred before bundled custom fonts
  • Dynamic Type and readability are part of the first recommendation, not a later polish step

Outputs

• status
  • success: the request belongs to this workflow and a typography recommendation is ready
  • handoff: another skill owns the next step after typography-aware classification
  • blocked: docs, asset, platform, licensing, or project context is insufficient for an honest recommendation
• path_type
  • system-typography
  • dynamic-type-repair
  • custom-font-integration
  • licensing-boundary
  • project-validation
  • handoff
• output
  • classified typography job
  • chosen system text style, design, or custom font path
  • Dynamic Type and accessibility behavior
  • licensing or redistribution boundary when relevant
  • documented Apple behavior relied on
  • validation or handoff step

Guards and Stop Conditions

• Do not bundle Apple system font files for ordinary app UI.
• Do not hard-code machine-local font paths into public project files, scripts, or docs.
• Do not skip Dynamic Type when user-facing text is involved.
• Do not claim a custom font is loaded or available until the project resource and Info.plist path have been validated.
• Do not use typography alone to communicate important state.
• Do not repeat licensing warnings after stating the concern once for a private local task, unless the task changes into public redistribution or release.
• Stop with blocked when the task depends on unavailable font files, unknown license terms, or target-platform behavior that cannot be checked.

Fallbacks and Handoffs

• Recommend apple-ui-accessibility-workflow for broader accessibility implementation or review.
• Recommend sf-symbols-workflow when the work is primarily symbol, icon, or glyph selection rather than text.
• Recommend swiftui-app-architecture-workflow or appkit-app-architecture-workflow when typography changes reveal ownership or view-structure problems.
• Recommend xcode-build-run-workflow for font files, bundle resources, Info.plist keys, target membership, preview, build, or simulator validation.
• Recommend explore-apple-swift-docs when the user primarily needs raw Apple documentation lookup.
• Recommend references/snippets/apple-xcode-project-core.md when repo policy or Xcode project-integrity guidance is needed before applying font resources.

Customization

Use references/customization-flow.md.

scripts/customization_config.py exists to preserve the repo-wide customization-file contract, but the first version of this skill defines no runtime-enforced knobs.

Keep the first release focused on typography classification, system-font choices, Dynamic Type behavior, custom-font boundaries, and validation handoffs. If future iterations add deterministic font-bundle checks, document those helpers before relying on them.

References

Workflow References

• references/system-typography-and-dynamic-type.md
• references/custom-fonts-and-licensing.md
• references/customization-flow.md

Support References

• Recommend explore-apple-swift-docs when the user needs direct Apple-docs lookup instead of typography workflow guidance.
• Recommend references/snippets/apple-xcode-project-core.md when the user needs reusable Xcode project policy before integrating font assets.
• Apple documentation anchors to verify include Human Interface Guidelines Typography, SwiftUI Font, SwiftUI Applying custom fonts to text, UIKit Scaling fonts automatically, UIFontDescriptor.SystemDesign, UIFontMetrics, UIFont.preferredFont(forTextStyle:), AppKit NSFont, UIAppFonts, and ATSApplicationFontsPath.

Script Inventory

• scripts/customization_config.py