agentleFS
aka-kikaaka-kika/akakika-skills/skills/apple-hig/apple-hig-typography/SKILL.md

apple-hig-typography

Skill11 starsChanged 3 months agoMITView on GitHub

Use when designing, reviewing, or implementing typography in Apple-platform apps — SwiftUI text styles, hierarchy, readable sizes, monospaced data, custom fonts, labels, captions, and accessibility.

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. About 0 are common, 13 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when designing, reviewing, or implementing typography in Apple-platform apps.

    line 12
  2. Distinctive:

    Use for SwiftUI text styles, macOS typography, iOS typography, hierarchy, readable sizes, monospaced data, custom font decisions, labels, …

    line 14
  3. Distinctive:

    Use this skill for:

    line 26
  4. Distinctive:

    Do not use this skill for:

    line 41
  5. Distinctive:

    Use SwiftUI styles instead of hardcoded sizes where possible.

    line 52
  6. Distinctive:

    Avoid using too many sizes on one screen.

    line 76
  7. Distinctive:

    Avoid very thin weights for functional UI.

    line 89
  8. Distinctive:

    Prefer hierarchy from size, weight, spacing, and grouping before color.

    line 93
  9. Very specific:

    Avoid body text below comfortable legibility.

    line 148
  10. Distinctive:

    Use monospaced digits for changing numeric values.

    line 215
  11. Distinctive:

    Use monospaced fonts for:

    line 225
  12. Distinctive:

    Use custom fonts only when they serve the product.

    line 248
  13. Distinctive:

    When using custom fonts:

    line 269
  14. Very specific:

    Prefer relativeTo: when cross-platform accessibility scaling matters.

    line 276
  15. Distinctive:

    Use only when building brand-specific apps, not generic Apple HIG work.

    line 280

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Apple HIG Typography

Apply system text styles, a small hierarchy, and accessible sizing to typography in Apple-platform apps. Reach for it when cleaning up fonts, building readable dashboards or popovers, or reviewing custom-font and accessibility decisions.

Purpose

Use this skill when designing, reviewing, or implementing typography in Apple-platform apps.

Use for SwiftUI text styles, macOS typography, iOS typography, hierarchy, readable sizes, monospaced data, custom font decisions, labels, captions, metadata, and accessibility.

Core rule

Use system text styles first. Customize only when the product needs it.

Typography should make the interface easier to scan, not more decorative.

When to use this skill

Use this skill for:

  • Typography cleanup
  • Font hierarchy
  • Dashboard readability
  • Menu bar popover text
  • Settings text
  • Inspector labels
  • Metadata text
  • Code/terminal-style UI
  • Custom font review
  • Accessibility text review

When not to use this skill

Do not use this skill for:

  • Icon choice; use apple-hig-sf-symbols
  • Spacing/layout only; use apple-hig-layout
  • Sidebar structure; use apple-hig-sidebars
  • Marketing landing pages unless they are inside an Apple app

Apple typography principles

1. Prefer system text styles

Use SwiftUI styles instead of hardcoded sizes where possible.

Text("Title")
    .font(.title2)

Text("Body text")
    .font(.body)

Text("Metadata")
    .font(.caption)
    .foregroundStyle(.secondary)

2. Use a small hierarchy

Most screens need only three levels:

Primary:   title / headline
Secondary: body / callout
Tertiary:  caption / metadata

Avoid using too many sizes on one screen.

3. Use weight carefully

Good UI weights:

Regular
Medium
Semibold
Bold

Avoid very thin weights for functional UI.

4. Use color less than hierarchy

Prefer hierarchy from size, weight, spacing, and grouping before color.

Good:

Text("Last updated 2 min ago")
    .font(.caption)
    .foregroundStyle(.secondary)

Bad:

Text("Last updated 2 min ago")
    .font(.caption)
    .foregroundStyle(.blue)

unless blue communicates an action or link.

Recommended SwiftUI text styles

.largeTitle  = rare hero/screen title
.title       = main title
.title2      = major section title
.title3      = compact title
.headline    = row/card heading
.body        = default readable text
.callout     = secondary body or compact explanation
.subheadline = supporting label
.footnote    = fine print
.caption     = metadata, badges, timestamps
.caption2    = avoid unless space is very tight

Rule:

Do not use the smallest text style just to fit too much content. Reduce content instead.

macOS practical guidance

For macOS productivity UI:

Window title / screen title: .title2 or .title3
Card title: .headline
Row title: .body or .headline
Row subtitle: .callout or .subheadline
Metadata: .caption
Tiny helper text: .footnote or .caption

Avoid body text below comfortable legibility. For dense macOS UI, .caption is acceptable for metadata, but not for primary content.

Menu bar popover typography

Recommended:

Header title: .headline or .title3
Status: .caption or .callout
Primary action: .body or .headline
List row title: .body
List row subtitle: .caption
Footer: .caption

Rules:

- Keep labels short
- Avoid paragraphs in popovers
- Prefer 1-line row titles
- Use captions only for metadata
- Do not use huge hero type in small popovers

Inspector typography

Recommended:

Inspector section label: .caption, secondary, uppercase optional
Field label: .callout, secondary
Field value: .callout or .body
Path/ID: .caption, monospaced if helpful

Example:

HStack {
    Text("Status")
        .font(.callout)
        .foregroundStyle(.secondary)

    Spacer()

    Text("Running")
        .font(.callout)
}

Dashboard typography

Dashboards should be calm and scannable.

Rules:

- Do not use huge numbers unless the number is the main decision point.
- Avoid too many equal-size metrics.
- Use captions for labels and body/headline for values.
- Use monospaced digits for changing numbers.
- Use one main visual emphasis per card.

Monospaced text

Use monospaced digits for changing numeric values.

Text("00:42")
    .font(.body.monospacedDigit())

Text("128 tasks")
    .font(.body.monospacedDigit())

Use monospaced fonts for:

Code
Logs
Terminal output
Paths
IDs
Timers
Counters
Token counts

Example:

Text(filePath)
    .font(.system(.caption, design: .monospaced))
    .textSelection(.enabled)

Custom font rules

Use custom fonts only when they serve the product.

Good uses:

Brand-heavy marketing screen
Terminal/code UI
Distinctive hero title
Numerical dashboard style

Bad uses:

Every small label
Settings forms
Inspector fields
Dense data tables
Accessibility-critical UI

When using custom fonts:

Text("Terminal")
    .font(.custom("JetBrainsMono-Regular", size: 13, relativeTo: .body))

Prefer relativeTo: when cross-platform accessibility scaling matters.

Brand font conventions

Use only when building brand-specific apps, not generic Apple HIG work.

SF Pro / system font = default app UI
SF Mono or JetBrains Mono = terminal/log/code surfaces
Brand display font = marketing/brand headlines only
Avoid custom fonts in dense settings and inspector screens

Line length

Readable text should not be too wide.

Short UI labels: no issue
Long body text: target roughly 50–75 characters per line
Popover text: keep very short; do not use long paragraphs

SwiftUI cap:

Text(longText)
    .frame(maxWidth: 420, alignment: .leading)
    .fixedSize(horizontal: false, vertical: true)

SF Symbols with text

Symbols should match surrounding text size and weight.

Good:

Label("Settings", systemImage: "gearshape")
    .font(.body)

Avoid overpowering labels:

HStack {
    Image(systemName: "gearshape")
        .font(.system(size: 28, weight: .bold))
    Text("Settings")
        .font(.caption)
}

Accessibility rules

- Do not use tiny text for important content
- Do not rely on color alone
- Keep contrast strong enough
- Let system text styles handle scaling where possible
- Avoid thin weights
- Keep labels clear and literal
- Make paths/IDs selectable if users need to copy them

Review checklist

[ ] System text styles are used by default
[ ] Screen has no more than 3 major type levels
[ ] Primary content is readable
[ ] Metadata is visually secondary
[ ] Captions are not used for essential content
[ ] Weights are not too thin
[ ] Changing numbers use monospaced digits
[ ] Long text has a readable line length
[ ] Custom fonts are justified
[ ] Symbols match text size and weight
[ ] Accessibility and contrast are preserved

Common mistakes

Hardcoding every font size
Too many type sizes on one screen
Huge headings in small popovers
Captions used for important text
Thin weights in low contrast UI
Random custom fonts everywhere
Monospaced font used for normal paragraphs
Changing numbers jitter because digits are proportional
Icons overpower text
Color used instead of hierarchy

Prompt template

Use the apple-hig-typography skill to clean up typography in this Apple-platform app.

Goal:
Make text easier to scan, more native, and more accessible.

Rules:
- Use SwiftUI system text styles first.
- Limit each screen to a small typography hierarchy.
- Use Regular, Medium, Semibold, or Bold for UI.
- Avoid thin weights for functional text.
- Use captions only for metadata or minor helper text.
- Use monospaced digits for changing numbers.
- Use monospaced design only for code, logs, paths, IDs, timers, and counters.
- Keep long text at readable line length.
- Use custom fonts only when justified.
- Keep SF Symbols aligned with text size and weight.
- Preserve accessibility and contrast.

Before coding:
1. Audit all font modifiers.
2. Identify hardcoded sizes.
3. Identify too-small important text.
4. Propose a simplified type scale.
5. Then implement.

After coding:
1. List files changed.
2. Explain the typography hierarchy.
3. List hardcoded fonts removed.
4. Explain custom font decisions.
5. Give manual test steps.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.