Get Started as a Developer

The NYSDS gives you a library of web components and a set of design tokens and styles. Install via npm, load the files in your HTML, and start building.

Quick Start

Install the core libraries:

npm install @nysds/components @nysds/styles

Reference the files in your HTML:

<!-- Load the full NYS Design System CSS. Link should go in head. -->
<link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds-full.min.css" />
<!-- Load the NYS Design System JS library. Should go before the closing body tag -->
<script type="module" src="node_modules/@nysds/components/dist/nysds.js"></script>

Then use NYSDS components directly in your HTML:

<nys-alert
  heading="Application received"
  text="Your permit application has been submitted for review."
></nys-alert>

Important: Adjust paths based on your build tool. Many tools (Vite, Webpack) resolve node_modules automatically — use bare imports like import ‘@nysds/components’ and @import ‘@nysds/styles/full’.

Design System Features

Components — A library of accessible, reusable web components for forms, navigation, alerts, modals, and more. See the component reference and read about web component fundamentals.

Design Tokens — CSS custom properties for colors, spacing, typography, shadows, and more. Use them to style custom layouts and align with NYSDS. See the tokens reference.

Styles Framework — The @nysds/styles package provides typography classes, a CSS reset, layout utilities, and agency themes. See the styles framework guide.

Layout & Utilities — A grid system and utility classes for spacing, flex layouts, and responsive design. See the layout utilities reference.

Typography — Font styling and typography tokens. Fonts must be downloaded separately due to licensing. See fonts and typography.

Accessibility — All components are WCAG 2.2 compliant with keyboard navigation and screen reader support. See accessibility.

Framework Guides

NYSDS components are standard web components. They work in any framework. Below are sample setup steps for common frameworks used across New York State agencies. If you notice a bug in these configurations, drop a bug report issue in GitHub.

React

Web components work in React, but React's synthetic event system does not automatically listen to custom events from web components. Use ref callbacks or addEventListener for NYSDS events like nys-change.

import '@nysds/components/react';
function LicenseRenewalForm() {
  const handleChange = (e) => {
    console.log('Selected:', e.detail.value);
  };
  return (
    <nys-select
      label="License type"
      ref={(el) => el?.addEventListener('nys-change', handleChange)}
    >
      <option value="driver">Driver License</option>
      <option value="commercial">Commercial Driver License</option>
    </nys-select>
  );
}

Angular

Add CUSTOM_ELEMENTS_SCHEMA to your module:

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import '@nysds/components';
@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule {}

Vue

We package the Vue JSX files in the @nysds/components/react package. Configure Vite to recognize nys- tags as custom elements:

// vite.config.js
import vue from '@vitejs/plugin-vue';
export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.startsWith('nys-')
        }
      }
    })
  ]
}

.NET / Blazor

Load NYSDS in your layout via local path:

<!-- In _Layout.cshtml or _Host.cshtml -->
<!-- Load the NYS Design System JavaScript library -->
<script type="module" src="node_modules/@nysds/components/dist/nysds.js"></script>
<!-- Load the full NYS Design System CSS -->
<link rel="stylesheet" href="node_modules/@nysds/styles/dist/nysds-full.min.css" />

VSCode Autocomplete

Copy .vscode/ from node_modules/@nysds/components/dist/.vscode/ to your project root. Then add to .vscode/settings.json:

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

Essential Links

• NPM Packages: @nysds/components, @nysds/styles
• GitHub: ITS-HCD/nysds
• Component Reference: Browse all components
• Release Notes: Read the latest updates
• Report Issues: GitHub Issues
• ITS Teams: Troubleshooting channel (ITS staff only)