Skip to main content

Getting Started

Welcome to the Interstate Design System​

Interstate enables every product team to more quickly deliver and optimize digital experiences with a coherent system of flexible, on-brand, modular UI components.

Communication on Slack or Teams channels is generally the best way to reach others with knowledge of the existing workflow for contributors.

:NEEDS REVISION: Currently no teams channel. Removal of this link may be necessary

Choose your role below to get started with Interstate.

<div className="flex flex-col" style={{ background: 'transparent' }}>
  <Button variant="outline" href="#getting-started__designers" className="m-3">
    Designer
  </Button>
  <Button variant="outline" href="#getting-started__developers" className="m-3">
    Developer
  </Button>
  <Button variant="outline" href="#getting-started__manager" className="m-3">
    Product Manager
  </Button>
</div>

Designers​

Good interaction and interface design begins with understanding our design environment, users, and standards. To that end, designers should thoroughly review the Foundations section of the Interstate Design System. We recommend you start with the following topics:

:NEEDS REVISION: Links need to be updated

Developers​

Using a Interstate component in your project is just like using any other library.

Developers implement Interstate's reusable components to improve speed and consistency while delivering a best-in-class user experience.

:NEEDS REVISION: No longer uses bootstrap and React Components are not using Tailwind. Interstate is created from the building blocks found in Bootstrap layered with React components. This provides a familiar syntax to element class names and treatments, while allowing for an unlimited amount of capabilities.

Use Interstate within your application whether it uses TailwindCSS or React:

Quickstart​

If your project uses React and is already configured with Artifactory you can get started right away. In other cases, continue below to learn more about how to use Interstate in your project.

:NEEDS REVISION: css is not delivered this way, library may not be the package name, may only have one option.

// Existing projects may already be configured to access
// artifactory. If not, follow the instructions below.
import React from 'react';

// Typically, you can import from the full library.
import { Button } from '@interstate/library'
import '@interstate/styles/interstate.comps.min.css';

// or '@interstate/styles/interstate/button.min.css'

function MyComponent() {
  return <Button variant="primary">Click Me</Button>
}

Using Interstate in Your Project​

In the following section, we will:

  1. Setup your project to be able to access artifactory
  2. Install Interstate packages (individually or the entire library)
  3. Use Interstate Styles and Components in your project

The Interstate javascript library is available as a single bundle or as individual components.

Interstate provides packages as CommonJS (CJS), ES Module (ESM), Immediately-invoked Function Expressions (IIFE), and SystemJS (SJS). The type of module used is often determined by the environment using the package, but each module type is available for direct use if needed.

In modern javascript applications, like create-react-app, Interstate will support code-splitting/lazy loading. However, this feature is still under development, so the best way to get only the code you want is to install individual components (i.e. @interstate/button).

Using Artifactory​

Using the artifactory credentials script​

To use Interstate in a React project, you will first need to setup npm/yarn to use the artifactory registry for Interstate packages. We have created a script to help you get your artifcatory credentials and setup your .npmrc file.

To use the artifactory credentials script, you will need to either clone the Interstate repository on to your local machine or download the artifcatory credentials script file Once the script is on your machine, you can execute it in your terminal by running:

:NEEDS REVISION: are we providing this script?

sudo ./scripts/get_artifactory_creds.sh

The script will walk you through the process of getting your artifactory token, which you will use to complete your .npmrc file.

Updating Your .npmrc​

In order to install and use the Interstate node modules, you will need to configure your package manager to use the artifactory registry. An easy way to do this is by using the .npmrc. This file is used to configure npm OR yarn to download @interstate packages from the artifactory registry. If you are using yarn, the .npmrc will work just fine. You won't need a .yarnrc.

For this example, we will use an .npmrc in the project's root directory. Copy the example .npmrc into the root directory of your project and rename the file to .npmrc. Export the ARTIFACTORY_EMAIL and ARTIFACTORY_TOKEN generated by the artifactory credentials script into your system environment, like so:

export ARTIFACTORY_EMAIL=************** && export ARTIFACTORY_TOKEN=**************

Now, your package manager is ready to install @interstate packages from artifactory.

Installing Interstate​

Installing the Interstate Styles Package​

:NEEDS REVISION: styles are baked into the components. this section will need to be removed or rewritten. Interstate relies on css styles that are not packaged with the components or the library, so you will need to install them in your project prior to using the components.

yarn add @interstate/styles

Once installed, you will need to import the styles into your project's entrypoint. Typically, this is a file at the root of your project directory or project src directory, called index.js, App.js, or Main.js. In the top of your entrypoint file, include the following line:

import '@interstate/styles/interstate.comps.min.css';
import '@interstate/styles/icon-font.min.css'; // only if using @interstate/icons without SVG.

If your project utilizes scss and you would like to import interstate styles through your own scss pipeline, you may use @interstate/scss, which includes all Sass files from the framework and all available themes.

Installing Interstate Component Packages​

Interstate is a modular library, so you can import individual components (recommended) OR the entire interstate library into your project.

Individual components can be installed using:

yarn add @interstate/button

:NEEDS REVISION: Is openSeaDragon still used? The entire library can be installed using*:

yarn add @interstate/library openseadragon

*When you install the library, you will need to also install the openseadragon module as a dependency of the multimedia viewer. This will be updated in a future release to remove this requirement.

Using Interstate​

You will need to import the component in the file where you intend to use the component.

:NEEDS REVISION: look up proper way to install components If you installed an individual component:

import Button from @interstate/button

If you installed the entire library:

import { Button } from @interstate/library

That's it! Now you're using Interstate in your project!

Contributing to Interstate​

If you would like to make Interstate better, contributions can be made via pull request on Github.

  • Github
  • Site/Code Organization
  • Contributing Best Practices

Developer Resources​

Product Managers, Business Stakeholders, and Everyone Else​

What is a design system?​

Our Interstate design system is a coherent set of reusable, coded components, branding elements, and interaction patterns that can be combined in different ways to create digital products. Think of it as a set of digital LEGO® bricks that your team uses to build amazing, fully interactive client experiences.

How does a design system benefit our clients?​

Every component in the design system has been carefully thought out, built to exacting standards, and exhaustively tested. :NEEDS REVISION: is this true? Out of the box, they include such built-in benefits as responsive design (they work well on both desktop and mobile) and hooks for analytics tagging. When we build all of our products using a design system, they share a common look and feel and work together seamlessly, so even new products feel familiar and easy to use.

Take a few minutes to peruse Interstate elements and components for inspiration on how you can evolve the user experience of your product. :NEEDS REVISION: we will need an email address To learn more about how Interstate can benefit your users and development teams, contact interstate@coxautoinc.com, or post a message on the #interstate-community Slack channel.

Benefits of Interstate​

  • Efficiency - A build-it once model for most common components
  • Velocity - Prebuilt components lets designers and developers work more quickly
  • High-quality Code - Components are rigorously tested and embody our standards
  • Seamless Experience - Familiar interfaces across products builds client confidence
  • Cost Savings - We don't pay to design, build, test, or maintain duplicate components
  • Rigor - Our governance model guides enhancements and additions to the system