pgts-web

name	pgts-web
description	Apply Pretty Good Type Scale (PGTS) in web projects using the generated CSS. Use when a coding agent needs to integrate PGTS in HTML, CSS, React, Next.js, design-token CSS, responsive typography, print CSS, or browser-based design systems.

PGTS Web

Use this skill when the target is a website or web application. Use css/pgts.css directly unless the host project already has a token build pipeline that must consume tokens/pgts.tokens.json.

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

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

Integration

Import the generated CSS:

<link rel="stylesheet" href="css/pgts.css">

Or import it from application CSS:

@import "./css/pgts.css";

Wrap a document area in .pgts when semantic HTML aliases should apply:

<article class="pgts fluid-clamped">
  <h1>Pretty Good Type Scale</h1>
  <h2>Semantic roles, responsive values</h2>
  <p>Use HTML roles while the mode controls how type responds.</p>
</article>

Use explicit classes when the HTML tag and type role differ:

<p class="headline-large">Section-like copy set as a paragraph</p>

Semantic HTML and Scoped Overrides

PGTS maps semantic HTML to roles where appropriate. In PGTS-wrapped content, prefer the native element when it already carries the intended role: h1 for display, h2 for headline-large, h3 for title-large, h4 for title, and p for body copy.

Use explicit PGTS classes only when the HTML element and visual role intentionally differ. Do not add display to an h2, title-large to an h3, or similar class restatements when the alias is already correct.

Do not override PGTS typography metrics during ordinary layout work. Avoid local resets for heading margins, paragraph margins, line height, font size, letter spacing, pseudo-element spacing, or arbitrary text max-width caps. Adjust grid/flex layout, container width, section gaps, padding, and alignment first.

Scoped exceptions are allowed only for a specific component behavior or when explicitly requested by the design/user. Keep them narrow, such as .featureGrid h2 { margin-top: 0; margin-bottom: 0; }, and leave the semantic element and PGTS role sizing intact.

Modes

• Use default mode for conservative product UI.
• Use .fluid for expressive pages where viewport growth is acceptable.
• Use .fluid-clamped for responsive pages that need a floor, preferred value, and ceiling.
• Use print output from the generated @media print rules; proof the final PDF or physical print.

Font Hooks

Set host font variables outside the generated file:

:root {
  --pgts-heading-font-family: var(--brand-heading-font);
  --pgts-body-font-family: var(--brand-body-font);
  --pgts-heading-wght-axis: 300;
  --pgts-heading-wdth-axis: 88;
  --pgts-heading-opsz-axis: 64;
}

Do not edit css/pgts.css by hand. Update tokens/pgts.tokens.json, then run npm run build.

Verification

• Check one narrow viewport and one desktop viewport.
• Confirm no horizontal overflow from display roles.
• Inspect important headings and copy to confirm they keep semantic PGTS roles without unnecessary class restatements or layout-driven metric overrides.
• Check browser zoom up to 200 percent.
• Confirm the chosen font still reads correctly at body, footnote, caption, and legal.
• Run npm run validate after token or generator changes.