Typography

Define your typography, with fluid typescales powered by utopia:

export default defineConfig({
  typography: {
    weight: {
      arial: {
        value: {
          regular: "600",
        },
      },
    },
    fluid: {
      arial: {
        value: {
          minWidth: 320,
          minFontSize: 14,
          minTypeScale: 1.25,
          maxWidth: 1435,
          maxFontSize: 16,
          maxTypeScale: 1.25,
          positiveSteps: 5,
          negativeSteps: 3,
        },
      },
    },
  },
});

This will generate the following CSS :

/*____ CSSForge ____*/
:root {
/*____ Typography ____*/
--typography_fluid-arial-4xl: clamp(2.6703rem, 2.5608rem + 0.5474vw, 3.0518rem);
--typography_fluid-arial-3xl: clamp(2.1362rem, 2.0486rem + 0.4379vw, 2.4414rem);
--typography_fluid-arial-2xl: clamp(1.709rem, 1.6389rem + 0.3503vw, 1.9531rem);
--typography_fluid-arial-xl: clamp(1.3672rem, 1.3111rem + 0.2803vw, 1.5625rem);
--typography_fluid-arial-l: clamp(1.0938rem, 1.0489rem + 0.2242vw, 1.25rem);
--typography_fluid-arial-m: clamp(0.875rem, 0.8391rem + 0.1794vw, 1rem);
--typography_fluid-arial-s: clamp(0.7rem, 0.6713rem + 0.1435vw, 0.8rem);
--typography_fluid-arial-xs: clamp(0.56rem, 0.537rem + 0.1148vw, 0.64rem);
--typography_fluid-arial-2xs: clamp(0.448rem, 0.4296rem + 0.0918vw, 0.512rem);
--typography-weight-arial-regular: 600;
}

Customizing Fluid Typography Scales

You can customize the typescale by providing your prefix and custom labels. The prefix will overwrite the name of the key that you are using to define your typography.

const config = defineConfig({
  typography: {
    fluid: {
      comicsans: {
        value: {
          minWidth: 320,
          minFontSize: 14,
          minTypeScale: 1.25,
          maxWidth: 1435,
          maxFontSize: 16,
          maxTypeScale: 1.25,
          positiveSteps: 2,
          negativeSteps: 2,
          prefix: "text",
        },
        settings: {
          customLabel: {
            "-2": "a",
            "-1": "b",
            "0": "c",
            "1": "d",
            "2": "e",
          },
        },
      },
    },
  },
});

This will generate the following CSS :

/*____ CSSForge ____*/
:root {
/*____ Typography ____*/
--typography_fluid-comicsans-text-e: clamp(1.3672rem, 1.3111rem + 0.2803vw, 1.5625rem);
--typography_fluid-comicsans-text-d: clamp(1.0938rem, 1.0489rem + 0.2242vw, 1.25rem);
--typography_fluid-comicsans-text-c: clamp(0.875rem, 0.8391rem + 0.1794vw, 1rem);
--typography_fluid-comicsans-text-b: clamp(0.7rem, 0.6713rem + 0.1435vw, 0.8rem);
--typography_fluid-comicsans-text-a: clamp(0.56rem, 0.537rem + 0.1148vw, 0.64rem);
}

Fluid Typography Checks

Each fluid step is checked from its smallest and largest size in px, as utopia computes them at minWidth and maxWidth:

• Error: more than 2.5× growth. A step whose maximum is more than 2.5 times its minimum fails the build. Past that ratio, 500% browser zoom cannot double the text at some viewport widths (WCAG 1.4.4 Resize Text). Exactly 2.5× passes. Lower maxFontSize or maxTypeScale, or reduce positiveSteps.
• Warning: a static scale. A scale whose every step changes by less than 10% across the viewport range gets one warning, because its clamp() values are effectively static. A single static step is normal where a scale crosses over, usually near the base step, so it is not reported on its own.
• Warning: below the legibility floor. A step whose smaller size is under settings.minLegibleSize (default 12, in px) gets one warning. The first example above warns for s (11.2px), xs (8.96px) and 2xs (7.17px).

When maxTypeScale is larger than minTypeScale, small negative steps can shrink as the viewport grows. Those steps are checked at their smaller end, and the 2.5× error only applies to steps that grow.

settings.minLegibleSize takes a number of px greater than 0, or false to turn the floor off. It only changes the warnings: the tokens and the CSS stay the same.

export default defineConfig({
  typography: {
    fluid: {
      caption: {
        value: {
          minWidth: 320,
          minFontSize: 11,
          minTypeScale: 1.2,
          maxWidth: 1280,
          maxFontSize: 13,
          maxTypeScale: 1.25,
          positiveSteps: 1,
          negativeSteps: 0,
        },
        settings: {
          minLegibleSize: 10,
        },
      },
    },
  },
});

This will generate the following CSS :

/*____ CSSForge ____*/
:root {
/*____ Typography ____*/
--typography_fluid-caption-l: clamp(0.825rem, 0.7615rem + 0.3177vw, 1.0156rem);
--typography_fluid-caption-m: clamp(0.6875rem, 0.6458rem + 0.2083vw, 0.8125rem);
}

Warnings never fail the build. The CLI prints each one to stderr as cssforge: warning: <message> and still writes the outputs, and getDiagnostics(config) returns them to programmatic callers (see Programmatic Usage).