Typography

SGDS Typography Utilities Skill

Helps developers use SGDS typography utilities for consistent text sizing, weights, spacing, and formatting.

Prerequisites

Required: Complete setup from sgds-utilities-setup skill first.

Typography utilities require the utility CSS import but do NOT require theme files.

Core Concept

All SGDS typography utilities use the sgds: prefix for font sizes, weights, line heights, and letter spacing.

Font Size

Apply text sizes using sgds:text-{size} where the number matches the pixel value:

<p class="sgds:text-12">12px — captions, fine print</p>
<p class="sgds:text-14">14px — labels, helper text</p>
<p class="sgds:text-16">16px — default body text</p>
<p class="sgds:text-20">20px — lead paragraphs, intro text</p>
<h4 class="sgds:text-24">24px — H4 / card headings</h4>
<h3 class="sgds:text-28">28px — H3</h3>
<h2 class="sgds:text-32">32px — H2</h2>
<h1 class="sgds:text-40">40px — H1</h1>
<h1 class="sgds:text-48">48px — page titles</h1>
<h1 class="sgds:text-56">56px — hero display</h1>

Font Size Scale

• 12 = 12px
• 14 = 14px
• 16 = 16px (default)
• 20 = 20px
• 24 = 24px
• 28 = 28px
• 32 = 32px
• 40 = 40px
• 48 = 48px
• 56 = 56px

Sizes outside this base scale (18, 22, 26, 30, 36, 44, 52) are available for responsive use only.

Font Weight

Apply font weights using sgds:font-{weight}:

<p class="sgds:font-light">Light weight (300)</p>
<p class="sgds:font-regular">Regular weight (400) - default</p>
<p class="sgds:font-semibold">Semibold weight (600)</p>
<p class="sgds:font-bold">Bold weight (700)</p>

Font Weight Scale

• light = 300
• regular = 400 (default)
• semibold = 600
• bold = 700

Line Height

Apply line heights using sgds:leading-{scale}:

<!-- Body text (default) -->
<p class="sgds:leading-normal">Normal line height (1.5)</p>

<!-- Display, headings, and subheadings -->
<h1 class="sgds:leading-tight">Tight line height (1.2)</h1>

Line Height Scale

• normal = 1.5 (default — body text)
• tight = 1.2 (display, headings, subheadings)

Letter Spacing

Apply letter spacing using sgds:tracking-{size}:

<!-- Tighter spacing -->
<p class="sgds:tracking-tighter">Tighter letter spacing (-0.05em)</p>
<p class="sgds:tracking-tight">Tight letter spacing (-0.025em)</p>

<!-- Normal spacing -->
<p class="sgds:tracking-normal">Normal letter spacing (0em)</p>

<!-- Wider spacing -->
<p class="sgds:tracking-wide">Wide letter spacing (0.025em)</p>
<p class="sgds:tracking-wider">Wider letter spacing (0.05em)</p>
<p class="sgds:tracking-widest">Widest letter spacing (0.1em)</p>

Letter Spacing Scale

• tighter = -0.0625em
• tight = -0.025em
• normal = 0em (default)
• wide = 0.0625em
• wider = 0.125em

Font Family

Apply font families using sgds:font-{family}:

<!-- Sans-serif (default) -->
<p class="sgds:font-sans">
  System sans-serif font stack
</p>

<!-- Monospace (code) -->
<code class="sgds:font-mono">
  Monospace font for code
</code>

Font Families

• sans - System sans-serif stack (Inter, system-ui, etc.)
• mono - Monospace stack (jetbrainsmono, 'Courier New', etc.)

Common Use Cases

Display Headings (Hero Text)

<h1 class="sgds:text-display-default sgds:text-48 sgds:font-bold sgds:leading-tight sgds:tracking-tight">
  Hero Display Heading
</h1>

<h1 class="sgds:text-display-default sgds:text-56 sgds:font-bold sgds:leading-tight">
  Extra Large Hero
</h1>

Section Headings

<!-- H2 -->
<h2 class="sgds:text-heading-default sgds:text-32 sgds:font-semibold sgds:leading-tight sgds:mb-6">
  Section Heading
</h2>

<!-- H3 -->
<h3 class="sgds:text-heading-default sgds:text-24 sgds:font-semibold sgds:leading-tight sgds:mb-4">
  Subsection Heading
</h3>

<!-- H4 -->
<h4 class="sgds:text-heading-default sgds:text-20 sgds:font-semibold sgds:leading-tight sgds:mb-3">
  Minor Heading
</h4>

Body Text

<!-- Large body text (lead paragraph) -->
<p class="sgds:text-body-default sgds:text-20 sgds:leading-normal sgds:mb-4">
  Lead paragraph with larger text for better readability.
</p>

<!-- Standard body text -->
<p class="sgds:text-body-default sgds:text-16 sgds:leading-normal sgds:mb-4">
  Regular body text for main content.
</p>

<!-- Small body text (captions, metadata) -->
<p class="sgds:text-body-subtle sgds:text-14 sgds:leading-normal">
  Caption or metadata text.
</p>

<!-- Extra small (fine print) -->
<p class="sgds:text-body-subtle sgds:text-12 sgds:leading-normal">
  Fine print or legal text.
</p>

Form Labels

<label class="sgds:text-label-default sgds:text-14 sgds:font-semibold sgds:block sgds:mb-2">
  Form Field Label
</label>

<label class="sgds:text-label-default sgds:text-16 sgds:font-semibold sgds:block sgds:mb-2">
  Larger Form Label
</label>

Links

<a href="#" class="sgds:text-link-default sgds:text-16 sgds:font-regular">
  Standard link
</a>

<a href="#" class="sgds:text-link-default sgds:text-16 sgds:font-semibold">
  Semibold weight link
</a>

Code Blocks

<!-- Inline code -->
<p class="sgds:text-body-default">
  Use the <code class="sgds:font-mono sgds:text-14 sgds:bg-surface-raised sgds:px-1">import</code> statement.
</p>

<!-- Code block -->
<pre class="sgds:font-mono sgds:text-14 sgds:leading-normal sgds:bg-surface-raised sgds:p-4 sgds:rounded">
  function hello() {
    console.log('Hello, world!');
  }
</pre>

Emphasized Text

<p class="sgds:text-body-default sgds:text-16 sgds:leading-normal">
  This is <strong class="sgds:font-semibold">important text</strong> that needs emphasis.
</p>

<p class="sgds:text-body-default sgds:text-16 sgds:leading-normal">
  This is <em class="sgds:font-regular sgds:italic">emphasized text</em> with style.
</p>

Uppercase/Lowercase Text

<!-- Uppercase (e.g., labels, badges) -->
<span class="sgds:text-12 sgds:font-semibold sgds:uppercase sgds:tracking-wider">
  Badge Label
</span>

<!-- Capitalize -->
<h3 class="sgds:text-20 sgds:font-semibold sgds:capitalize">
  capitalize each word
</h3>

<!-- Lowercase -->
<p class="sgds:text-14 sgds:lowercase">
  ALL LOWERCASE TEXT
</p>

Blockquotes

<blockquote class="sgds:text-body-default sgds:text-20 sgds:font-regular sgds:leading-normal sgds:italic sgds:border-l-4 sgds:border-primary-default sgds:pl-6 sgds:my-6">
  "This is an inspiring quote that stands out from the main content."
</blockquote>

Statistics/Numbers

<div class="sgds:text-center">
  <p class="sgds:text-primary-default sgds:text-48 sgds:font-bold sgds:leading-tight sgds:mb-2">
    1,234
  </p>
  <p class="sgds:text-body-subtle sgds:text-14 sgds:font-semibold sgds:uppercase sgds:tracking-wide">
    Active Users
  </p>
</div>

Buttons

<!-- Standard button -->
<button class="sgds:bg-primary-default sgds:text-white sgds:text-16 sgds:font-semibold sgds:px-6 sgds:py-3 sgds:rounded">
  Button Text
</button>

<!-- Small button -->
<button class="sgds:bg-primary-default sgds:text-white sgds:text-14 sgds:font-semibold sgds:px-4 sgds:py-2 sgds:rounded">
  Small Button
</button>

<!-- Large button -->
<button class="sgds:bg-primary-default sgds:text-white sgds:text-20 sgds:font-semibold sgds:px-8 sgds:py-4 sgds:rounded">
  Large Button
</button>

Card with Typography Hierarchy

<div class="sgds:bg-surface-raised sgds:p-6 sgds:rounded-lg">
  <h3 class="sgds:text-heading-default sgds:text-24 sgds:font-semibold sgds:leading-tight sgds:mb-2">
    Card Title
  </h3>
  <p class="sgds:text-body-subtle sgds:text-14 sgds:leading-normal sgds:mb-4">
    Updated 2 hours ago
  </p>
  <p class="sgds:text-body-default sgds:text-16 sgds:leading-normal sgds:mb-4">
    Main card description with good readability.
  </p>
  <a href="#" class="sgds:text-link-default sgds:text-14 sgds:font-regular">
    Read more →
  </a>
</div>

Responsive Typography

Combine with responsive prefixes for adaptive sizing:

<!-- Mobile: 24px, Tablet: 32px, Desktop: 40px -->
<h1 class="sgds:text-24 md:sgds:text-32 lg:sgds:text-40 sgds:font-bold">
  Responsive Heading
</h1>

<!-- Adjust line height at different breakpoints -->
<p class="sgds:text-16 sgds:leading-normal md:sgds:text-20">
  Responsive body text
</p>

Best Practices

DO: Use Semantic Text Size Pairings

<!-- ✅ Good - appropriate size hierarchy -->
<h2 class="sgds:text-32 sgds:font-semibold sgds:mb-4">Section Title</h2>
<p class="sgds:text-16 sgds:leading-relaxed">Body content</p>

<!-- ❌ Avoid - poor hierarchy -->
<h2 class="sgds:text-16 sgds:font-regular">Section Title</h2>
<p class="sgds:text-32">Body content</p>

DO: Pair Font Size with Line Height

<!-- ✅ Good - headings with tight leading (1.2) -->
<h1 class="sgds:text-48 sgds:leading-tight">Display Heading</h1>

<!-- ✅ Good - body text with normal leading (1.5) -->
<p class="sgds:text-16 sgds:leading-normal">Body text</p>

<!-- ❌ Avoid - heading without tight leading -->
<h1 class="sgds:text-48 sgds:leading-normal">Poor heading spacing</h1>

DO: Use Appropriate Weights for Emphasis

<!-- ✅ Good - clear visual hierarchy -->
<h2 class="sgds:font-bold">Bold Heading</h2>
<p class="sgds:font-regular">Regular body text</p>

<!-- ❌ Avoid - everything too bold -->
<h2 class="sgds:font-bold">Bold Heading</h2>
<p class="sgds:font-bold">Bold body text (too heavy)</p>

DO: Use Monospace for Code

<!-- ✅ Good - monospace for code -->
<code class="sgds:font-mono sgds:text-14">const foo = 'bar';</code>

<!-- ❌ Avoid - sans-serif for code -->
<code class="sgds:font-sans sgds:text-14">const foo = 'bar';</code>

DO: Adjust Tracking for Large Text

<!-- ✅ Good - tighter tracking for display text -->
<h1 class="sgds:text-56 sgds:font-bold sgds:tracking-tight">
  Hero Heading
</h1>

<!-- ✅ Good - wider tracking for small caps -->
<span class="sgds:text-12 sgds:font-semibold sgds:uppercase sgds:tracking-wider">
  Label
</span>

Troubleshooting

Font Size Not Applied

Problem: A font size class has no effect

Solutions:

1. Only base sizes are utility classes: 12, 14, 16, 20, 24, 28, 32, 40, 48, 56
2. Check that sgds: prefix is included
3. Verify no CSS specificity conflicts from other stylesheets
4. Check for !important rules overriding the utility

Line Height Issues

Problem: Line height appears incorrect

Solutions:

1. Remember font size utilities include default line heights
2. Override with explicit sgds:leading-* classes if needed
3. Check for inherited line-height values from parent elements

Font Weight Not Changing

Problem: Font weight utilities don't change weight

Solutions:

1. Ensure the font family supports the weight you're using
2. Verify font files are loaded correctly
3. Check browser font rendering settings
4. Try a different weight to test if font supports it

Text Too Tight/Loose

Problem: Letter spacing looks wrong

Solutions:

1. Use sgds:tracking-tight for large headings
2. Use sgds:tracking-wider for small uppercase text
3. Leave normal tracking for body text
4. Avoid extreme tracking values

Quick Reference

Font Size

sgds:text-12   /* 12px */
sgds:text-14   /* 14px */
sgds:text-16   /* 16px (default) */
sgds:text-20   /* 20px */
sgds:text-24   /* 24px */
sgds:text-28   /* 28px */
sgds:text-32   /* 32px */
sgds:text-40   /* 40px */
sgds:text-48   /* 48px */
sgds:text-56   /* 56px */

Font Weight

sgds:font-light        /* 300 */
sgds:font-regular      /* 400 (default) */
sgds:font-semibold     /* 600 */
sgds:font-bold         /* 700 */

Line Height

sgds:leading-normal    /* 1.5 (default — body text) */
sgds:leading-tight     /* 1.2 (display, headings, subheadings) */

Letter Spacing

sgds:tracking-tighter  /* -0.05em */
sgds:tracking-tight    /* -0.025em */
sgds:tracking-normal   /* 0em (default) */
sgds:tracking-wide     /* 0.025em */
sgds:tracking-wider    /* 0.05em */
sgds:tracking-widest   /* 0.1em */

Font Family

sgds:font-sans  /* System sans-serif */
sgds:font-mono  /* Monospace */

For AI Agents: Use only the 10 base font sizes — 12, 14, 16, 20, 24, 28, 32, 40, 48, 56. Use sgds:text-16 for body, sgds:text-32 for H2, sgds:text-40–sgds:text-48 for H1, sgds:text-56 for hero display. Use sgds:leading-tight (1.2) for display text and all headings; use sgds:leading-normal (1.5) for all body text. Use semibold (600) or bold (700) for headings, regular (400) for body text. Always use monospace font for code.