How you implement the design system depends on the needs of your project and your workstyle. We highly recommend implementing the design system with
npm, as it allows you to easily update the design system version, but we also provide a direct download if
npm will not work for you or your project. We also offer the ability to utilize the design system via direct reference to code and style resources from our CDN.
@cmsgov/design-systempackage if your project uses
npmfor package management.
Download the design system if you are not familiar with
npmand package management.
Utilize the CDN if you would like to reference the design system styles and code directly from your page/application.
Install using npm
Simply add the
@cmsgov/design-system package to your
package.json to install it as a dependency.
npm install --save @cmsgov/design-system@latest yarn add @cmsgov/design-system@latest
The @cmsgov/design-system package includes:
- Pre-compiled SCSS files
- Compiled CSS files
- Compiled React components (CommonJS and ES modules)
- Typescript definition files
- Fonts and image
Package file structure
dist folder contains all the necessary files in the design system, your project should not be importing anything from
└── dist ├── components/ │ └── index.js Compiled JS entry point (CommmonJS) ├── css/ │ └── index.css Compiled CSS entry point ├── esnext/ │ └── index.esm.js Compiled JS entry point (ES Module) ├── fonts/ ├── images/ ├── scss/ │ ├── base/ Base styles, HTML element selectors │ ├── components/ Component styles │ ├── settings/ Variables, mixins, and functions │ ├── utilities/ Utility classes for individual CSS properties │ └── index.scss Precompiled SCSS entry point └── types/ Typescript definition files
Download the zip file from the 'Download Code' button in the header. This will download the latest release and extract the zip file to see the following folder structure. Like the
npm package, the contents of
download/design-system/dist contain design system code and assets.
└── download ├── design-assets/ Design system assets (Sketch files, fonts, designer assets) └── design-system/ Design system package (code, fonts, images) └── dist/
Copy the files and folders from
download/design-system/dist to a relevant place in your project’s code base. Here is an example structure for how this might look:
Utilize the CDN
A content delivery network (CDN) is a collection of servers that dynamically allocate resources dependent on the requester's geographic location in order to optimize the distribution of assets.
Some benefits and applications for utilizing the design system via CDN are:
- Quickly utilize design system code and style assets for development/prototyping
- The CDN caches assets for fast loading and scales automatically in case of a large number of requests
- Ability to utilize a specific version of the design system easily
├── css/ │ ├── index.css │ ├── base/index.css │ ├── components/index.css │ └── utilities/index.css └── js/ ├── react.production.min.js ├── react-dom.production.min.js └── bundle.js
Packages which are currently available for reference:
- design-system - The core CMSDS (versions 3.4.0 and above)
- ds-healthcare-gov - Healthcare.gov themed DS (versions 7.4.0 and above)
- ds-medicare-gov - Medicare.gov themed DS (versions 5.4.0 and above)
package-name is one of the packages named above,
version is the version number and
resource is the file being requested from the resources listed above.
Example for including version 3.4.0 Core CSS via CDN
<link rel="stylesheet" href="https://design.cms.gov/cdn/design-system/3.4.0/css/index.css" crossorigin="anonymous" />
Example for including version 3.4.0 Core JS via CDN
If you do not already have React and React-DOM included in your page, include them before the design system js bundle.
Need help or ran into an issue?
If you're having trouble installing or setting up the design system, or if you think you've found a bug, feel free to open an issue on GitHub.