Styles Framework

The @nysds/styles package is the CSS foundation of the NYS Design System. It delivers design tokens as CSS custom properties, a selective CSS reset, typography styles, and layout utility classes — bundled into composable stylesheets you can import based on what your project needs.

Components from @nysds/components handle their own internal styling through shadow DOM. The styles package is for everything outside of components: page layout, typography, spacing, and ensuring your application's baseline styles align with the design system.

For installation and setup instructions, see Get Started as a Developer.

At a glance, the package provides three composable endpoints:

Endpoint File Use when...
Tokens only nysds.min.css You only need design tokens and FOUC prevention
Typography nysds-typography.min.css You need role-based font classes
Full nysds-full.min.css You want everything: reset + tokens + typography + utilities

Stylesheet Endpoints

The @nysds/styles package ships three CSS files, each building on the last. Choose the one that matches your project's needs.

Default — Tokens Only

File: nysds.min.css Import path: @nysds/styles

Copy Code
<!-- Tokens only (smallest footprint) -->
<link rel="stylesheet" href="/path/to/nysds.min.css" />

This is the smallest stylesheet. It includes:

  • Design tokens — All NYSDS color, spacing, typography, and sizing values as CSS custom properties (e.g., --nys-color-theme-primary, --nys-space-200, --nys-font-size-md)
  • FOUC prevention — Rules that hide NYSDS web components (via :not(:defined)) until they finish registering, preventing a flash of unstyled content

Use this when you want access to the design system's token values in your CSS but plan to handle typography, layout, and resets yourself.

Typography — Font Classes

File: nysds-typography.min.css Import path: @nysds/styles/typography

Copy Code
<!-- Typography classes only -->
<link rel="stylesheet" href="/path/to/nysds-typography.min.css" />

This stylesheet provides role-based CSS classes for applying consistent typography across your application:

  • Body text — .nys-font-body-xs, .nys-font-body-sm, .nys-font-body-md
  • Headings — .nys-font-h1 through .nys-font-h6
  • UI text — .nys-font-ui-xs through .nys-font-ui-xl
  • Display text — .nys-font-display-sm through .nys-font-display-xl
  • Agency titles — .nys-font-agency

These classes reference NYSDS font tokens, so they require the default stylesheet (or the full stylesheet) to be loaded alongside them for the CSS custom properties to resolve.

Typography classes are designed to match the text styles in the NYSDS Figma library. For more on fonts, font licensing, and font installation, see Typography.

Full — Everything

File: nysds-full.min.css Import path: @nysds/styles/full

Copy Code
<!-- Full stylesheet (recommended for most projects) -->
<link rel="stylesheet" href="/path/to/nysds-full.min.css" />

This is the recommended stylesheet for most projects. It bundles everything together:

  • CSS reset — A selective reset that normalizes box-sizing, margins, list styles, heading styles, link colors, and paragraph spacing
  • Design tokens — All CSS custom properties
  • FOUC prevention — Component visibility rules
  • Typography styles — Heading, body, list, and link styles using design system tokens
  • Utility classes — Layout grid, flexbox, spacing, display, float, opacity, z-index, and responsive helpers

This is the same stylesheet referenced in the developer setup guide.

How to Reference Stylesheets

There are several ways to load @nysds/styles depending on your project setup.

From node_modules

After installing with npm install @nysds/styles, reference the dist files from node_modules. Most modern build tools (Vite, webpack, Parcel) can resolve these paths directly:

Copy Code
/* In your main CSS file */
@import "@nysds/styles/dist/nysds-full.min.css";

Or reference the file as a <link> tag pointed at the resolved path in your build output.

Copying to your project

If your build tool does not resolve node_modules paths, copy the CSS files into your project's asset directory:

Copy Code
cp node_modules/@nysds/styles/dist/nysds-full.min.css src/assets/css/

Then reference the local copy:

Copy Code
<link rel="stylesheet" href="/assets/css/nysds-full.min.css" />

For the full installation walkthrough, including copying both CSS and JS files, see Get Started as a Developer.

Manual download

For teams that cannot use npm, download the latest release from the NYSDS GitHub releases page and include the CSS files in your project manually. Keep in mind that you will need to check for updates and replace the files when new versions are released.

CSS Reset

The full stylesheet includes a selective CSS reset that establishes consistent baseline styles across browsers. Unlike aggressive resets that strip all default styling, the NYSDS reset is targeted — it normalizes the specific areas where browser defaults cause inconsistency while preserving useful defaults elsewhere.

The reset applies the following:

  • Box-sizing — Sets box-sizing: border-box on all elements, including ::before and ::after pseudo-elements
  • Margins and padding — Zeroes out default margins on body, headings, paragraphs, lists, blockquote, figure, and pre
  • Lists — Removes default list styling (list-style: none) so you can build lists without fighting browser defaults
  • Body defaults — Sets the base font to --nys-font-size-md with --nys-font-lineheight-md using the --nys-font-family-body font family, and sets text color to --nys-color-ink
  • Headings — Applies --nys-font-family-heading with appropriate font sizes, line heights, letter spacing, and margin spacing for h1 through h6
  • Links — Colors links with --nys-color-link, with hover/focus and active states using --nys-color-link-strong and --nys-color-link-strongest
  • List markers — Colors list markers with --nys-color-theme-primary
  • Smooth scrolling — Enables scroll-behavior: smooth on the html element

The reset is included only in the full stylesheet (nysds-full.min.css). If you use the default tokens-only stylesheet, you are responsible for your own reset.

Utility Classes

The full stylesheet includes a set of CSS utility classes for layout and common styling needs. These classes follow the nys- prefix convention and cover:

  • Layout grid — A mobile-first, flexbox-based 12-column grid system with responsive breakpoints
  • Flexbox — Direction, wrap, alignment, and justify utilities
  • Margin and padding — Spacing utilities using the design system's spacing scale
  • Display — Block, flex, inline, none, and table display modes
  • Float — Float left, right, and clear utilities
  • Opacity — Opacity scale from 0 to 100
  • Z-index — Layering utilities
  • Position — Static, relative, absolute, fixed, and sticky
  • Overflow — Overflow handling for both axes
  • Responsive — Breakpoint-prefixed variants for most utilities (e.g., nys-tablet:nys-grid-col-6)

For the complete reference of available utility classes and usage examples, see Utilities.

Choosing an Endpoint

Scenario Stylesheet Why
Starting a new NYS application nysds-full.min.css Get tokens, reset, typography, and layout utilities out of the box
Adding NYSDS components to an existing site with its own CSS nysds.min.css Tokens and FOUC prevention without overriding your existing typography or reset
Building an email template or print stylesheet nysds.min.css Tokens only — you control all other styling
Need typography classes but have your own reset nysds.min.css + nysds-typography.min.css Combine the base tokens with typography classes without bringing in the full reset

Edit this page on GitHub (Permissions required)

Last updated: May 28, 2026