pretty-good-type-scale

name	pretty-good-type-scale
description	Apply, tune, validate, or port the Pretty Good Type Scale (PGTS) as a coding-agent workflow for design-system typography in web apps, token pipelines, Swift/iOS/macOS projects, and Android Compose projects. Use when a task mentions PGTS, type-scale tokens, generated typography exports, responsive typography, native typography ports, or code changes to a PGTS-based design system.

Pretty Good Type Scale

Use this skill when you are the coding agent responsible for applying PGTS in code. Treat tokens/pgts.tokens.json as the canonical source. Treat generated files as outputs.

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

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

Coding Workflow

1. Inspect tokens/pgts.tokens.json before changing typography.
2. Identify the target code surface: CSS, DTCG tokens, Swift, Android Compose, or a host token pipeline.
3. Preserve token IDs and semantic role names.
4. Change canonical JSON first when a token value must change.
5. Run npm run build after token edits.
6. Run npm run validate before returning work.
7. Report any remaining alpha risk around line height, tracking, optical size, Dynamic Type, Android font scale, or print proofing.

Web Implementation

Import css/pgts.css. Wrap content in .pgts when semantic HTML aliases should apply. Choose one mode per surface:

• default: conservative minimum values with a desktop breakpoint.
• .fluid: viewport growth through max().
• .fluid-clamped: responsive floor, preferred value, and ceiling through clamp().

Set host font hooks instead of editing generated CSS:

:root {
  --pgts-heading-font-family: var(--brand-heading-font);
  --pgts-body-font-family: var(--brand-body-font);
}

Token Pipeline Implementation

Use tokens/pgts.dtcg.json when the downstream tool expects DTCG-style tokens. Use tokens/pgts.tokens.json when the downstream tool can consume the canonical PGTS schema directly.

Do not hand-edit tokens/pgts.dtcg.json. Regenerate it.

Apple Implementation

Use platforms/apple/PGTS.swift as the starter export. Map roles through PGTSRole, PGTSContext, and PGTS.style(_:).

Apply the host app's custom font separately. Use the app's Dynamic Type policy when converting PGTS point sizes into final rendered text.

Android Implementation

Use platforms/android/PGTSTypography.kt as the starter export. Map lean roles to Material 3 Typography and use sp so user font scaling remains available.

Apply the host app's font family separately. Do not convert Android sp values into fixed pixels.

Guardrails

• Do not invent extra steps between roles unless the user explicitly requests a fork.
• Do not replace semantic roles with framework-only names.
• Do not copy CSS values into native exports by hand.
• Do not remove print values, traditional names, or platform exports during web-only changes.
• Do not treat PGTS as final art direction; tune it against the selected typeface and real copy.