Spirit is available via NPM and from a CDN. Installing via NPM gives you access to source scss files and design system tokens as scss variables. These source SCSS files are not available via the CDN.
CDN assets are served via an Amazon Cloudfront distribution and are available via the cdn.jdrf.design URL. All the links referenced in this guide contain a version number as part of the url. In order to upgrade to future releases of Spirit you will need to update any CDN urls accordingly.
<use> element is unable to request assets from other domains, the svg sprites must be served locally on your product’s domain and cannot be referenced from the CDN
If using the CDN stylesheet referenced above, fonts will automatically be pulled in. If you are compiling Spirit styles yourself using the source scss files available in the npm package then you can pull in the fonts from the CDN using the following code:
You can utilize assets from both NPM and the CDN. For example you may want to reference the
spirit.css stylesheet from the CDN and also include scss token variables in your product via an NPM install. You can mix and match assets from both sources as long as they are using the same version of Spirit.
The easiest way to install the entire library of styles is to include the compiled Spirit stylesheet in your product:
<link rel="stylesheet" href="/path/to/spirit.css">
Or, using the CDN:
Spirit expects fonts to be located in a peer directory of the stylesheet:
Be sure the fonts are accessible in this manner or they will fail to load. If you use the CDN url the fonts will be pulled in automatically from the CDN.
Use the source scss files from the NPM package if you want to use Spirit tokens and mixins within your own product to provide greater alignment with the Design System’s components.
@import individual Spirit mixins and token files as needed:
You can also
@import individual Spirit components as needed, but at this time there is no dependency resolution when importing individual components, so you will need to use a bit of trial and error to determine which scss partials a particular component depends on.
Spirit provides an SVG sprite containing all of the icons in the design system. This sprite is located in the NPM package at:
Place the sprite in the webroot of your product to use an absolute reference to the file and invoke a specific icon via the
<use> tag within an SVG:
The icon sprite uses a hash syntax to locate the requested icon. Refer to the icon documentation for all of the icon names.
Spirit uses the svg4everybody polyfill to provide IE11 compatibility.
Refer to individual component pages, like Button for detailed usage guidelines on each component. In general:
<button class="spirit-button your-product-cta-button">Sign Up</button>
When using the
spirit.css stylesheet there are no additional dependencies or libraries required.
Spirit does not provide a global CSS reset or normalize file. It is the responsibility of a consuming property and at their discretion to include a global CSS reset or normalize within their product.
A SCSS compiler is required to convert the source
.scss files into a
Spirit uses AutoPrefixer to keep vendor prefixes out of our source code. If you are compiling Spirit SCSS files directly you will need to add this tool into your build process to comply with Spirit’s browser requirements. Use the following AutoPrefixer config:
3rd party libraries are used to solve specific challenges in the Spirit Doc Site. We recommend these or similar packages / solutions are used on consuming properties. For reference, Spirit is using the following 3rd party packages:
2.1.9 or higher.
4.0.6 or higher.
5.2.0 or higher.
spirit.js adds scripting functionality to the Card Carousel, Vertical Navigation and other components as stated on individual component documentation pages.
Some components, like Card, use the
object-fit css property to control image cropping and rendering.
object-fit is not supported in IE11. If your product needs to support the
object-fit css property you use an object-fit polyfill to enable the feature.
As stated above, the scripting used in Spirit is not intended to be used on a production level and is intended to be used as example purposes only. That being said, we do understand there may be a need (i.e. rapid prototyping) to utilize these scripts from the package.
Therefore we have made available via the npm package and the CDN three files (all are also available with the
Use these scripts as needed and at the direction of the project.
This Library allows use of Spirit symbols (buttons, cards, icons, etc) and styles (typography, shadows, etc) across your Sketch documents and have them update to always be in sync.
This file is in pretty early stages but still has some key information and resources, particularly on the grid and page layout: https://sketch.cloud/s/QjwgY
If you find yourself detaching from a Library symbol or style, that could be a signal that custom code will need to be written.
Instead of “detaching”, use Symbol Overrides to keep the elements of your design linked to the Library. This helps your design keep parity with production code and stay in sync with the latest Library updates.
However, there are scenarios where it’s necessary to detach elements without requiring custom development: