Getting Started

Overview

The Breakthrough T1D Design System is a collection of components designed to maintain consistency across the project’s front-end development. It is available as a GitLab repository, which contains all the necessary files to get started, including CSS, JavaScript, images, and SVG assets. This allows developers to get up and running with minimal setup. Follow the steps below to set up the design system for your project.

Prerequisites

Make sure you have the following installed on your local environment:

  • Node.js (LTS version recommended)
  • npm (comes with Node.js)

Setup

1. Clone the Repository

Start by cloning the design system repository to your local environment using Git:

git clone git@gitlab.10up.com:jdrf/breakthrough-t1d-design-system.git

2. Install Dependencies

Once cloned, navigate into the project directory and install the necessary npm dependencies:

cd your-repo-directory
npm install

3. Build the Design System

After installing the dependencies, build the design system by running the following command:

npm run build

This command will compile all assets, including CSS, JavaScript, images, and SVGs, into the dist folder. The compiled assets are optimized for use in your project.

The design system uses 10up’s Toolkit for compiling and optimizing assets. The toolkit simplifies the development workflow by automating tasks such as compiling CSS, JavaScript, and SVGs, and ensuring all assets are optimized for production.

4. Copy the SVG Directory

To utilize the design system’s icons, you need to copy the svg directory from the dist folder into your project. This directory contains the SVG sprite and individual icons essential for icon usage across the design system.

5. Enqueue the Compiled Assets

In order to apply the design system’s styles and functionality, enqueue the compiled CSS and JavaScript files (bt1d-frontend-css.css and bt1d-frontend-js.js) into your site or HTML.

Here’s an example of how to include these files in your HTML:

<!-- Include the compiled CSS -->
<link rel="stylesheet" href="path/to/dist/bt1d-frontend-css.css">

<!-- Include the compiled JavaScript -->
<script src="path/to/dist/bt1d-frontend-js.js"></script>

Make sure to replace path/to/dist/ with the actual location where the compiled assets are stored in your project.

SVG Sprite Compilation

The design system includes an SVG sprite to manage icons efficiently. By default, the sprite is compiled when you run the npm run build command. However, if you specifically need to update or rebuild the SVG sprite, use the following command:

npm run build:svg-sprite

This command will compile all SVG files into a single sprite, optimized for performance. You can reference the icons from the sprite using use elements with appropriate ID references throughout the design system.

File Structure

The repository is organized as follows:

  • assets/ – The source directory containing all the CSS, JavaScript, and SVG files used for development.
    • css/ – Source styles for the design system.
    • js/ – Source JavaScript files for the design system.
    • svg/ – Source SVG files, including individual icons.
  • dist/ – The compiled directory that contains the optimized assets ready for production.
    • css/ – Compiled and minified CSS.
    • js/ – Compiled and minified JavaScript.
    • svg/ – Compiled SVG sprite and optimized icons.

Customizing Components

You can easily customize components in the design system using utility classes or overriding variables. For example, to change the background color of an element, you can use the bt1d-navy-background-color utility class.

If you need further customization, you can modify the CSS variables in the assets/css/global/tokens.css file and rebuild the design system.

Browser Support

The Breakthrough T1D Design System is tested on modern browsers including:

  • Chrome (latest version)
  • Firefox (latest version)
  • Safari (latest version)
  • Edge (latest version)

For older browsers (e.g., Internet Explorer 11), certain features may require polyfills or may not be fully supported.