Typography
Typography is a core pillar of the New York State Design System, providing a consistent foundation for readability, accessibility, and brand alignment across all New York State digital applications.
Overview
Typography in NYSDS is powered by the core fonts that define the New York State brand. These include:
- Proxima Nova: The primary typeface for body text and UI elements.
- D Sari: The brand font used for agency, program, and initiative titles.
- Oswald: A supporting typeface for content-heavy websites (optional).
Due to licensing restrictions, the fonts themselves are not distributed as part of the open-source NYSDS Design System. They are available exclusively to New York State teams via NYSDS Fonts (internal). However, NYSDS provides a set of typography tokens and utilities that work well with Proxima Nova but will fall back to system fonts if the primary fonts are not available.
Typography Tokens
NYSDS defines typography tokens (also known as CSS variables) — for each font property. These tokens are organized into primitive and semantic categories.
Primitive
Primitive tokens are the raw typographical building blocks: family, size, weight, line height, and letter spacing. These tokens represent a range of sensible default values that can be used to build out interfaces. This includes tokens like --nys-font-family-sans, --nys-font-size-md, and --nys-font-lineheight-lg.
⛔️ These values are not meant to be used directly in your stylesheets. They are used to define the semantic tokens.
Semantic
Semantic tokens map specific properties to specific roles, like headings, body text, and UI elements.
✅ They are meant to be used directly in stylesheets. They help standardize font usage across components and applications.
Here are a few examples of NYSDS' semantic typography tokens:
| Token Name | Description | Example Value |
|---|---|---|
--nys-font-family-body |
Font family for body text. | var(--nys-font-family-sans) |
--nys-font-size-h1 |
Font size for Heading 1 elements. | var(--nys-font-size-5xl) |
--nys-font-size-ui-md |
Medium font size for UI elements. | var(--nys-font-size-md) |
Installing Fonts
⚠️ Note: Fonts in the design system include some proprietary typefaces that are licensed for use exclusively by New York State government agencies and their digital products. These fonts are distributed separately from the design system and are not part of the open-source package to comply with licensing restrictions.
| Token Name | Description | Example Value |
|---|---|---|
--nys-font-family-body | Font family for body text. | var(--nys-font-family-sans) |
--nys-font-size-h1 | Font size for Heading 1 elements. | var(--nys-font-size-5xl) |
--nys-font-size-ui-md | Medium font size for UI elements. | var(--nys-font-size-md) |
Download and Install
To access these fonts:
- Download the appropriate font bundle from NYSDS Fonts. (🔒 Internal NYS Only)
- Extract the fonts into your project.
- Reference the provided
nysds-fonts.cssin the HTML head of your project:
<link rel="stylesheet" href="/assets/fonts/nysds-fonts.css">NYSDS web components use the typography tokens, so as soon as the fonts are installed, the components will appear correctly. More details about using tokens below.
Preload Critical Fonts (optional)
For better performance, preload critical fonts. This helps reduce the chance of a fallback font loading and then the web font loading later, causing layout reflow and a Flash of Unstyled Text (FOUT):
<head>
<link rel="preload" href="/assets/fonts/proximanova-regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
</head>Find more details about preloading fonts and web font best practices in Google's Using Web Fonts guide.
Using Typography in a Project
NYSDS' native web components use the typography tokens.
If you're not using NYSDS components or if you're styling custom elements or parts of the site not covered by the components, use the typography tokens or utility classes directly in CSS and HTML.
Tokens
Apply them using var() in CSS or by using utility classes. Here are some examples:
body {
font-family: var(--nys-font-family-body);
font-size: var(--nys-font-size-body-md);
line-height: var(--nys-font-lineheight-body-md);
}Unfortunately, each property must be set individually, as CSS does not support setting multiple properties at once with var().
This approach isn't too cumbersome when creating a library of components where you can define it once, but it can lead to a lot of repetition for everyday use. To help with this, NYSDS provides utility classes.
Utility Classes
NYSDS also provides utility classes that combine several font tokens into common styles. These can be applied directly in your HTML or included in your project’s CSS.
For example, NYSDS defines several utility classes that apply the font size, line height, and family for specific semantic text roles like heading, body, UI, and display:
.nys-font-h1 {
font: var(--nys-font-size-h1) / var(--nys-font-lineheight-h1) var(--nys-font-family-heading);
letter-spacing: var(--nys-font-letterspacing-h1);
}
.nys-font-body {
font: var(--nys-font-size-md) / var(--nys-font-lineheight-md) var(--nys-font-family-body);
}You can reference these classes in your HTML:
<h1 class="nys-font-h1">Welcome to NYSDS</h1>
<div class="nys-font-body">
<p>This is a sample paragraph styled using NYSDS typography utilities.</p>
<p>The parent element has the .nys-font-body class applied.</p>
</div>Full List of Utility Classes
| Class Name | Description | Example |
|---|---|---|
.nys-font-body-xs | Extra small body text | Discover the latest initiatives happening across New York State. |
.nys-font-body-sm | Small body text | Explore outdoor adventures, from the Adirondacks to Niagara Falls. |
.nys-font-body-md | Medium body text | Welcome to the official website for New York State, where you’ll find services, programs, and resources for residents and businesses. |
.nys-font-h1 | Heading 1 | Experience the Empire State |
.nys-font-h2 | Heading 2 | Explore New York City and Beyond |
.nys-font-h3 | Heading 3 | Parks, Trails, and Natural Wonders |
.nys-font-h4 | Heading 4 | Plan Your Visit Today |
.nys-font-h5 | Heading 5 | Join Our Community |
.nys-font-h6 | Heading 6 | Stay Informed with NYS Updates |
.nys-font-ui-xs | Extra small UI text | Next |
.nys-font-ui-sm | Small UI text | Apply Now |
.nys-font-ui-md | Medium UI text | View All Services |
.nys-font-ui-lg | Large UI text | Explore Programs |
.nys-font-ui-xl | Extra large UI text | Get Started |
.nys-font-display-sm | Small display text | Discover the beauty of upstate New York. |
.nys-font-display-md | Medium display text | Welcome to the Empire State |
.nys-font-display-lg | Large display text | Find Your Next Adventure |
.nys-font-display-xl | Extra large display text | New York State: It’s All Here |
.nys-font-agency | Agency-specific font style | New York State Department of Transportation |
Best Practices
-
Use Semantic Tokens for Consistency
Always use semantic typography tokens for fonts, sizes, and line heights. Avoid primitive tokens or hardcoding font properties. -
Use Utilities When Necessary
Use the predefined.nys-font-*classes for rapid development and consistent styling for parts of your applications or site not powered by NYSDS components. -
Preload Critical Fonts
Preload the most-used font weights and styles to improve perceived performance — in most cases, this is Proxima Nova Regular. -
Extend Existing Components
NYSDS web components automatically reference typography tokens. Use custom styles to extend or override these tokens for specific needs before creating new components.