Typography System

This project uses a token-driven typography system built with SCSS maps and CSS variables. You define a token once — size, line-height, breakpoints — and the system generates the utility class, the CSS variable, and all responsive overrides from that single definition.

Overview

The typography setup has three parts:

1. Typography tokens — Define font sizes, line-heights, letter-spacing
2. CSS variables & classes — Generated from tokens
3. Mixins — For custom applications

Fonts

Fonts are defined as CSS variables for flexibility:

$font-inter: var(--font-inter);
$base-font-family: $font-inter;

Typography Tokens

$type-tokens: (
    display: (
        lg: (
            size: rem(48px),
            line-height: 1.1,
            letter-spacing: -0.001em,
            breakpoint: (
                tablet: (
                    size: rem(28px),
                ),
                mobile: (
                    size: rem(24px),
                ),
            ),
        ),
    ),
);

$type-tokens is the single source of truth for all typography in the project. Every utility class, CSS variable, and responsive override is generated from this map — you never write the same font size in two places.

Token Structure

group:
  size:
    size: font-size (required)
    line-height: line-height (optional)
    letter-spacing: letter-spacing (optional)
    breakpoint: (optional)
      breakpoint-name:
        size: override font-size

Groups

Top-level keys are semantic groups:

• display — Hero titles, very large text
• heading — Page and section headings
• body — Body text, paragraphs

Available Typography Classes

.text-display-lg   // Hero titles
.text-display-md   // Section headers
.text-heading-lg   // Page headings
.text-heading-md   // Section headings
.text-heading-sm   // Subsection headings
.text-body-lg      // Large body text
.text-body-md      // Standard body text
.text-body-sm      // Small text, captions
.text-body-xs      // Very small text

Usage

HTML Classes

<h1 class="text-display-lg">Page Title</h1>
<p class="text-body-md">Body text here</p>

SCSS Mixins

.card__title {
    @include typography(heading, lg);
}

Mixin options:

@include typography(heading, lg);                    // Base styles only
@include typography(heading, lg, mobile);            // Specific breakpoint
@include typography-with-breakpoints(heading, lg);  // All breakpoints

Responsive Typography

Breakpoints are defined in the token and automatically applied:

display: (
    lg: (
        size: rem(48px),
        breakpoint: (
            tablet: (
                size: rem(32px),
            ),
            mobile: (
                size: rem(24px),
            ),
        ),
    )
);

This generates responsive CSS variables and utility classes automatically.

Font Weights

Defined separately in $font-weights:

$font-weights: (
    light: 300,
    normal: 400,
    medium: 500,
    bold: 700,
);

Usage:

<p class="text-body-md font-medium">Medium text</p>

Generated CSS Variables

:root {
    --instance-display-lg-font-size: 3rem;
    --instance-display-lg-line-height: 1.1;
    --instance-display-lg-tablet-font-size: 1.75rem;
    --instance-display-lg-mobile-font-size: 1.5rem;
}

All tokens generate CSS variables on :root automatically — you never write these by hand. The naming pattern is --instance-{group}-{size}-{property}.

One-off Overrides

.custom-heading {
    --instance-heading-lg-font-size: 2.25rem;
}

Override a token locally by redefining its CSS variable on a specific selector. The utility class picks up the new value without needing a new token or a specificity battle.

Adding New Tokens

1. Open the token file

   Edit src/styles/abstracts/variables/_typography.scss.

2. Add your token

   $type-tokens: (
       display: (
           xl: (
               size: rem(64px),
               line-height: 1.1,
               letter-spacing: -0.002em,
               breakpoint: (
                   tablet: (
                       size: rem(48px),
                   ),
                   mobile: (
                       size: rem(36px),
                   ),
               ),
           ),
       ),
   );

   Tip

   Match your Figma design tokens 1:1 for consistency between design and code.

3. Use the generated class or mixin

   <h1 class="text-display-xl">Hero Title</h1>

   or via SCSS:

   .hero__title {
       @include typography-with-breakpoints(display, xl);
   }

From Figma

Designer provided a type scale

1. Open the Typography / Type Scale board in Figma
2. Copy font sizes, line heights, letter spacing, and weights
3. Map into $type-tokens using semantic naming (display, heading, body + lg/md/sm)

No type scale board

1. Go page by page and collect typography styles
2. Identify repeating patterns
3. Map into $type-tokens semantically
4. Add even one-off sizes as tokens for consistency

Debugging

Enable debug output to see generated classes:

$font-output-generated-class-names: true;

This prints generated class names to the SCSS output during compilation.