Get Started as a Developer

The NYS Design System (NYSDS) provides a set of reusable, accessible web components, design tokens, and styles to help New York State teams build consistent, user-friendly digital products. This guide will walk you through the steps to integrate NYSDS into your project.

Install the libraries

To start using NYSDS in your project, you need to install the core libraries:

Copy Code
npm install @nysds/components @nysds/styles

Reference the files in your application

Once you've installed the packages, reference them in your application or site.

Copy Code
<!-- Load the NYS Design System Javascript library -->
<script src="/path/to/nysds.js"></script>
<!-- Load the full NYS Design System CSS -->
<link rel="stylesheet" href="/path/to/nysds-full.min.css" />

Important:

  • Replace the path/to with the actual path to the installed files (for example, from node_modules).
  • Place the <script> right before the closing </body> tag, so the DOM is fully loaded before NYSDS initializes.
  • Many modern build tools allow you to reference files directly from node_modules, but you can also copy them into your project assets (see "Copying Assets (Alternative Step)").

Apply Agency Theming

The NYSDS includes prebuilt theme stylesheets for agency branding (e.g. colors, buttons, etc).

To apply a theme, add the agency stylesheet in the <head> alongside core NYSDS styles. For example, "Office of Children and Family Services" uses the health theme. :

Copy Code
<!-- Core NYSDS styles -->
<link rel="stylesheet" href="/path/to/nysds-full.min.css" /> 
<!-- Agency theme (Health) --> 
<link rel="stylesheet" href="/path/to/nysds-theme-health.min.css" />

Note: If no agency theme is applied, components will default to NYS blue.

Copying Assets (Alternative Step)

If you prefer to host the NYSDS files locally within your project, you can copy them from node_modules to your project's asset directories.

If you wanted to copy the NYSDS CSS and JS files to src/assets/css/vendor and src/assets/js/vendor respectively, you could use the following command:

Copy Code
mkdir -p src/assets/css/vendor && mkdir -p src/assets/js/vendor
cp -r node_modules/@nysds/components/dist/nysds.* src/assets/js/vendor
cp -r node_modules/@nysds/styles/dist/* src/assets/css/vendor

This will copy over styles and scripts, but when new versions are released, you will need to update via npm and copy them over again.

Manual Asset Management (Alternative Step)

If you want to avoid npm altogether, you can download the latest release from the NYSDS GitHub repository and copy the files you need directly into your project. Keep in mind that you will need to manually check for updates and replace the files as new versions are released.

Edit this page on GitHub (Permissions required)

Last updated: October 8, 2025