Get Started as a Developer

There are two parts of the NYS Design System that are crucial for engineers to understand:

• A library of custom HTML elements, called web components, built with lit.dev and native JS and designed to work anywhere
• A collection of CSS variables that define the style of components and can be used to extend those styles to other components, and layout utilities that can be used to create mobile-responsive layouts

Install Component Library

To start using the NYS Design System in your project, you need to install the core libraries:

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.

<!-- Load the NYS Design System Javascript library -->
<script type="module" 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 the NYS Design System 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)").

Copying Assets (Alternative Step)

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

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

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 NYS Design System 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.

VSCode Autocomplete

To add vscode autocompletion to your editor:

Copy the .vscode/ folder into the root of your project. You can find it in /node_modules/@nysds/components/dist/.vscode/

Edit the following file (create it if it doesn't exist)

./vscode/settings.json

Add the following lines and save the file:

"html.customData": [".vscode/vscode.html-custom-data.json"],
"css.customData": [".vscode/vscode.css-custom-data.json"]

If you have existing settings, add the custom data in addition to the files already listed.

Install Styles

Full CSS Reference

The recommended way to use the NYS Design System styles is to include the full stylesheet, which contains all component styles and layout utilities.

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

Minimal CSS Reference

If you only need access to the design tokens and layout utilities, you can include the minimal stylesheet instead.

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

Install Font Styles

Fonts must be downloaded separately due to licensing restrictions.

Important: Note: These fonts are licensed for New York State applications only and are not distributed as part of the open-source design system.

<!-- Load the NYS Design System Javascript library -->
<script type="module" src="/path/to/nysds.js"></script>
<!-- Load the minimal NYS Design System CSS -->
<link rel="stylesheet" href="/path/to/nysds-typography.css" />

Apply Agency Theming

The NYS Design System 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 NYS Design System styles. For example, "Office of Children and Family Services" uses the health theme. :

<!-- Core NYS Design System 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.

Component Integration

Adding a Component

Once the references are set up, you can start using NYSDS components directly in your HTML. For example, to add an nys-alert component:

<nys-alert
  heading="Welcome to the Design System!"
  text="You can use all the web components the design system offers."
></nys-alert>

Using CSS Variables

The New York State Design System is built on a foundation of CSS variable ramps that define colors, spacing, and other design tokens. These variables style the components themselves but are also meant to be used across your site for consistency. Apply them in your own CSS to align custom layouts and elements to create a consistent visual experience for New Yorkers.

View all available design tokens here.

Accessibility

All components in our design system are built with accessibility in mind. They are WCAG 2.2 compliant and have been tested for screen readers and keyboard navigation. By using these components, your site gains built-in accessibility features, helping ensure a more inclusive experience for all users.

Event Interactions

Most NYS Design System components emit custom JavaScript events that allow developers to respond to user interactions such as clicks, selections, and state changes.

Each component’s event behavior is documented in the “Events” section on its reference page. There, you’ll find:

• A list of all custom events the component emits (e.g., nys-change, nys-click, etc.)
• The event detail object describing what data is passed when the event is fired
• These events are fully accessible through standard DOM event listeners, allowing you to hook into component behavior from your scripts.

Get Support

Need help or want to report an issue? You can:

• Submit or track issues on GitHub
• Review the latest Release Notes
• Ask questions or get troubleshooting help in the Troubleshooting channel on Teams