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.

Semantic Typography Rules

• Prefer PGTS semantic HTML aliases when the generated CSS maps them already. For example, use native h2 for the headline-large role instead of adding class="display", and use native h3 for the title-large role instead of restating it with a class.
• Treat PGTS margins, line height, pseudo-element spacing, optical-size settings, and role sizing as part of the typography system. Do not reset or override them while making ordinary layout changes.
• Solve layout problems with containers first: grid structure, column widths, gaps, padding, alignment, and wrapping. Do not add arbitrary max-width limits, font-size changes, line-height changes, or margin resets to PGTS text roles unless the user or design explicitly asks for that special treatment.
• If a special component needs a local exception, scope it narrowly to that component and the exact selector, preserve the semantic element or role, and override only the required property. Example: a specific grid card may set its own h2 margin-top and margin-bottom to 0 when explicitly requested, while leaving PGTS sizing intact.

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 add explicit PGTS role classes to native semantic headings when the HTML alias already provides the intended role.
• Do not override PGTS spacing or sizing as a layout shortcut; use scoped exceptions only when the user or design explicitly calls for them.
• 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.