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.
In this repository39 other files it gives its agents.
- agent-starter-packSkill
- agent-state-machineSkill
- local-ai-ollamaSkill
- apple-hig-command-paletteSkill
- apple-hig-empty-statesSkill
- apple-hig-feedback-statusSkill
- apple-hig-inspectorsSkill
- apple-hig-macos-window-layoutSkill
- apple-hig-search-filteringSkill
- apple-hig-settingsSkill
- apple-hig-sf-symbolsSkill
- apple-hig-sidebarsSkill
- apple-hig-toolbarsSkill
- blog-post-publishingSkill
- social-post-kitSkill
- color-principlesSkill
- kika-design-systemSkill
- emergency-switch-appSkill
- product-hunt-polish-reviewSkill
- docs-updateSkill
- project-folder-cleanupSkill
- between-runs-auditSkill
- explain-new-projectSkill
- new-project-gateSkill
- old-project-auditSkill
- project-catch-upSkill
- project-workflowSkill
- project-worth-my-timeSkill
- butterfly-effectSkill
- spreadSkill
- tilSkill
- apple-app-intentsSkill
- macos-app-distribution-dmgSkill
- macos-clipboard-pasteboardSkill
- macos-global-shortcutsSkill
- macos-launch-at-loginSkill
- macos-menubar-swiftuiSkill
- macos-notificationsSkill
- macos-permissions-privacySkill
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
- Distinctive: line 12
Use this skill when designing, reviewing, or implementing typography in Apple-platform apps.
- Distinctive: line 14
Use for SwiftUI text styles, macOS typography, iOS typography, hierarchy, readable sizes, monospaced data, custom font decisions, labels, …
- Distinctive: line 26
Use this skill for:
- Distinctive: line 41
Do not use this skill for:
- Distinctive: line 52
Use SwiftUI styles instead of hardcoded sizes where possible.
- Distinctive: line 76
Avoid using too many sizes on one screen.
- Distinctive: line 89
Avoid very thin weights for functional UI.
- Distinctive: line 93
Prefer hierarchy from size, weight, spacing, and grouping before color.
- Very specific: line 148
Avoid body text below comfortable legibility.
- Distinctive: line 215
Use monospaced digits for changing numeric values.
- Distinctive: line 225
Use monospaced fonts for:
- Distinctive: line 248
Use custom fonts only when they serve the product.
- Distinctive: line 269
When using custom fonts:
- Very specific: line 276
Prefer relativeTo: when cross-platform accessibility scaling matters.
- Distinctive: line 280
Use only when building brand-specific apps, not generic Apple HIG work.
≈ “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.
Files
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 / metadataAvoid using too many sizes on one screen.
3. Use weight carefully
Good UI weights:
Regular
Medium
Semibold
BoldAvoid 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 tightRule:
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 .captionAvoid 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: .captionRules:
- 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 popoversInspector typography
Recommended:
Inspector section label: .caption, secondary, uppercase optional
Field label: .callout, secondary
Field value: .callout or .body
Path/ID: .caption, monospaced if helpfulExample:
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 countsExample:
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 styleBad uses:
Every small label
Settings forms
Inspector fields
Dense data tables
Accessibility-critical UIWhen 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 screensLine 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 paragraphsSwiftUI 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 themReview 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 preservedCommon 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 hierarchyPrompt 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.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
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.

