Getting Started

For Developers

Installing Spirit

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.

Via NPM

Using CDN Assets

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.

Spirit Stylesheet

Icon & Brush Sprites

Because the <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

Fonts

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:

Combining assets

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.

Using CSS

The easiest way to install the entire library of styles is to include the compiled Spirit stylesheet in your product:

Or, using the CDN:

Font Paths

Spirit expects fonts to be located in a peer directory of the stylesheet:

├── fonts
└── styles
    └── spirit.css

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.

Using SCSS

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.

Importing SCSS

You can @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.

Using Icons

Spirit provides an SVG sprite containing all of the icons in the design system. This sprite is located in the NPM package at:

node_modules/@jdrfhq/spirit/dist/spirit.svg

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.

IE11 Support

Spirit uses the svg4everybody polyfill to provide IE11 compatibility.

Using Components

Refer to individual component pages, like Button for detailed usage guidelines on each component. In general:

• Use the code snippets provided in component documentation to ensure proper rendering of Spirit components in your product. Deviation from the DOM structure provided in the code snippet may cause the components to render improperly in your product.
• When modifying components for usage within your product use the BEM Methodology for naming your HTML classes. For example:

External Dependencies

CSS

When using the spirit.css stylesheet there are no additional dependencies or libraries required.

CSS Normalize/Reset

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.

SCSS

A SCSS compiler is required to convert the source .scss files into a .css stylesheet.

Post Processing

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:

JavaScript

When functionality can’t be achieved via HTML and CSS alone, Spirit doc site pages (Card Carousel, Vertical Navigation, and other components as stated on individual component documentation pages) may include JavaSCript to illustrate functionality. This JavaScript is included and intended for example purposes only. Spirit adopting teams may reference these examples to write their own JavaScript for their products. If there is a case where scripted bundles are needed, we do offer them in a following section - Javascript Bundles.

Third Party Libraries

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:

• svg4everybody which provides IE 11 support for the Spirit icon sprite. Use version 2.1.9 or higher.
• inputmask provides masking for form fields (date / phone). See Forms for implementation and guidance. Use version 4.0.6 or higher.
• a11y-dialog provides scripting to create acssible dialog windows. See Dialog for implementation. Use version 5.2.0 or higher.

Component Scripts

spirit.js adds scripting functionality to the Card Carousel, Vertical Navigation and other components as stated on individual component documentation pages.

Custom Scripts

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.

Spirit Script Bundles

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 .js and .min.js postfixes).

Component Scripts

Spirit Dependencies - Spirit dependencies (i.e. svg4everybody)

Spirit Bundle - Component scripts, bundle only scripts (i.e. calls to dependencies), and spirit dependencies.

Use these scripts as needed and at the direction of the project.

For Designers

Dependencies

• macOS
• Sketch app
• Font: Graphik Family
  • If you don’t already have one, purchase a Desktop license and add to the project invoice.
  • After a license has been purchased, email Patrick McKowen at pmckowen@jdrf.org to request a version of the font files that have been fixed to align correctly in Sketch.

Sketch Setup

Plugins

• Sketch Palettes
  • Download the Spirit Palette and then load using the plugin.

Sketch Resources

Nudging Preferences

• Spirit uses an 8px grid. To make your life easier, go to Sketch > Preferences > Canvas > Nudging: Move objects 8px using Shift-Arrow keys.

Add Spirit UI Sketch Library

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.

1. Go here to preview and install: https://sketch.cloud/s/rljLP
2. Click “Add Library to Sketch” button.
3. After confirming, Sketch > Preferences > Libraries will open automatically and Spirit will be added.
4. You will now find Spirit as an option in your Symbols, Text Styles, and Layer Styles. Learn more about using a Sketch Library: https://sketchapp.com/docs/libraries/

Download Spirit Marketing UI Kit

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

Breaking from Spirit Symbols and Styles

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:

• Text wrapping. For example the content for a card spans more or less lines than the card symbol, you’ll want to detach so you can adjust the vertical spacing.
• Text alignment. Spirit text styles are setup for Left alignment but center alignment is also acceptable.
• Shadow and background colors. The elevation layer styles are setup with white backgrounds, so if you need to apply them to an image or container with another background color, you’ll need to detach.