Get started with the design system (for developers)

If you’re a developer, start here to make sure you have everything you need to use the design system.


There are two ways to develop your website or application with the Ontario Design System.

Distribution package

  • Most flexible option to create custom applications/sites
  • Complete set of design system components
  • Includes complete styles, in both CSS and SASS
  • Bundled with HTML, JS examples
  • Easy-to-download Zip file

Learn more about the distribution package.

npm packages

  • Modular options to create custom applications/sites
  • Includes complete styles and assets
  • Use in place of the distribution package
  • Versioned releases via npm
  • Rolling releases

Learn more about the npm packages.

Web components

  • Rich HTML elements that are ready to use
  • Support for HTML and JavaScript frameworks
  • Created and tested to follow the Ontario Design System
  • Versioned releases via npm
  • Rolling releases

Learn more about the web components.

About the distribution package

One option to get started with using the design system within your own application/site is to use the official Ontario Design System distribution package.

The distribution package combines sample code of each component with all the necessary files (HTML, CSS/SCSS, JavaScript) to build into your development projects.

The package also includes assets, such as:

  • font files
  • the Ontario favicon set

You can find SCSS variables and usage in each component section.

Previous releases

Read the release notes and download previous versions.

Get the distribution package

Download manually

Create a folder where you can put all your files to keep them consistent and separate from other project files (for example, in a folder called vendor).

When a new version is released, you can easily replace the contents of this folder with the new version.

  1. Download latest version (1.8.0)
  2. Unzip the distribution package.
  3. Rename the extracted folder to ontario-design-system.
  4. Move this folder into your project (for example, the same place as your other static assets).
  5. Import ontario-design-system/styles/ds-theme.css (or ds-theme.min.css) globally into your own project. Read the import guidance for more details.

Download with a script

You may also integrate the distribution package into your project using a script (instead of manually), and organize it to fit your needs.

For example, the following script will download a particular release version and move the contents to a folder under src/assets/vendor.

Note: remember to update the DS_VERSION number to the version you’d like to download.

export DS_VERSION=1.8.0 && \
    export && \
    export VEN_DIR=src/assets/vendor  && \
    export DS_UNZIP_DIR=$VEN_DIR/ontario-design-system && \
    curl$ > $VEN_DIR/$DS_ZIP_NAME && \
    unzip -o $VEN_DIR/$DS_ZIP_NAME -d $DS_UNZIP_DIR && \
    rm $VEN_DIR/$DS_ZIP_NAME && \
    rm $DS_UNZIP_DIR/version-release-notes-*.* && \
    rm -rf $DS_UNZIP_DIR/html-samples && \
    rm $DS_UNZIP_DIR/index.html && \
    rm $DS_UNZIP_DIR/package.json && \
    rm -rf $DS_UNZIP_DIR/styles/components && \
    rm -rf $DS_UNZIP_DIR/styles/sass && \
    rm -rf $DS_UNZIP_DIR/fonts/

You may customize the items that the script deletes if you’d like to keep them within your project.

Import the styles

In your main CSS file, add an import statement to import the Design System styles into your project.

Using @import and the path to your assets, add the Design System styles to your application/site’s CSS.

@import '<path-to-vendor-dir>/vendor/ontario-design-system/styles/ds-theme.min.css’

Now that the design system is a part of your project, all of the global styles are applied automatically (header styles, paragraph spacing, etc). You may also use any of the component classes to create buttons, checkboxes and more.

Package contents

Folder Description
fonts Font assets ⁠— contains various versions of each font, including TTF, WOFF, WOFF2 and SVG.
html-samples HTML samples that give an example of each component’s HTML and CSS.
icons Icon files ⁠— learn more about icons in the Primary icons and the Secondary icon guidance.
index.html Sample highlighting the different components that can be opened up in a browser.
logos Copies of the Ontario logo.
scripts Supporting JavaScript files for various Design System components. For example, back-to-top scrolling code sample.
styles Styles used by the Design System, including component styles as well as the combined styles (ds-theme.css et ds-theme.min.css).

Building custom components

The design system distribution package contains SCSS files with variables. These can help you build new custom components and pages in alignment with the design system standards.

Simply import ontario-design-system/styles/sass/_variables-import.scss into your component. This file will import several categories of variables all at once (grid, colour, font, spacing, etc).

Example: colour variables

.ontario-callout-alert {
    border-color: $ontario-colour-alert;

Software requirements

Internally, we use Node.js 16 to build the static site, but externally many working with the Design System dist package will run into the need for SASS and SVGxUse in order to get the best experience with using the design system.

Our versions are as follows:

If you have any questions or feedback, please get in touch.