Getting started for developers

Overview

The information on this page is for developers at city agencies that are building or redesigning websites or applications using resources outside of the Office of Technology and Innovation (OTI). If you have a website that is currently on TeamSite CMS and supported by OTI, the design system will be applied systematically in future updates. If you have a custom application supported by OTI, ask your OTI support team for more details.

If you’re a developer working for NYC government, here’s how you can get started using the design system.

1. Request an onboarding session

The first step is to reach out to the Digital Service team in the Office of Technology and Innovation (OTI). We’ll assess your needs and make sure the design system is right for your use case. If it is, we’ll help you get onboarded into our Azure project and get access to the code.

2. Get access to the Azure project

We’ll help you get access to the NYC Design System Azure project. Access to the Azure project is required to install and use our library.

3. Set up environment

After getting access to our Azure project, you will receive instructions for setting up your environment to authenticate with our private Azure registry. Once you're able to authenticate with the registry you can begin using the library.

4. Install the @nycds/core package

The @nycds/core package is the primary distribution of our library. It contains bundled outputs of all required CSS and JS. To use the library with your project, you’ll need to set up a new Node.js project or install it in an existing Node.js project.

To set up a new Node.js project, run the following command from a directory where you’d like to store your project’s source code:

npm init

This will create a package.json file, which declares all of your project dependencies. If you have an existing Node.js project, this file should already exist in your project's root directory.

Next, run this command to install our Core package:

npm install @nycds/core

If this command fails with a ‘401 Unauthorized’ error, there is an issue with your .npmrc file or your PAT. Please consult that section of the documentation again.

If the command completes successfully, you’re ready to use the library!

5. Use the library

These instructions assume your project is using a Javascript bundling library such as Webpack, Vite, or Rollup. If you’re new to client-side web development tools, MDN has a guide to help you get started.

You use the design system library by importing the CSS and JS into your project then using the required component CSS classes in your markup. If you’d like to use one of our Custom Elements, you’ll have to import the desired component into a JS file and run its define function to register it.

Importing CSS

You can import the CSS into your project by adding this to a JS source file:

import ‘@nycds/core/dist/nycds-core.css’

Now try using our Button component by referencing its CSS classname:

<button class="nyc-button">My Button</button>

Importing JS

To use the Custom Elements distributed by the library, you can import the desired element’s JS Class and run its define command. For example:

import { NYCBackToTop } from ‘@nycds/core’NYCBackToTop.define()

Now you can use <nyc-back-to-top></nyc-back-to-top> in your application markup.

To see which components provide Custom Elements, view the code tab of each component.

6. Keep the library up to date

To keep the library up to date, simply update the package version of the @nycds/core library in your package.json file. You can run npm outdated to see which packages in your project have newer versions available, then run npm install @nycds/core@latest to get the latest version.

The NYC Digital Design System follows semantic versioning. Semantic versioning is a numbering system used in software development to track changes to a product and is used to indicate whether a release is a patch, a minor release, or a major release. We recommend that after you update to a new version, you follow a standard quality assurance process. For major versions, your team must conduct additional testing as these are usually changes that are not backwards compatible.

Release process

The NYC Digital Design System follows a continuous development cycle as components are updated and new components are introduced. You can expect quarterly releases along with release notes for you to make informed decisions about when you would like to update to the latest version. The release dates will be communicated in advance on this website. Check back for information about upcoming releases.

Defects will be addressed and delivered in patch releases and also communicated on this website.

Quality assurance

The NYC Digital Design System follows a well-defined change request process. We conduct multiple rounds of QA to ensure that all fixes and features are implemented to fulfill the needs of our end users. Our QA process includes automated regression testing, manual testing, and accessibility testing to ensure that the quality of our releases are maintained. All releases can be found in the artifacts directory (opens Azure DevOps).

While every effort is made to assure the quality of our releases, issues and bugs do arise. If you find a bug, send us a message.