Getting Started

Downloading

Provide links and information for downloading the design system’s files:

File Structure

Provide an overview of the file system structure and how users of the design system should integrate the design system’s code into their project. This info will obviously vary depending on your organization’s environment(s).

design-system-1.0/
├── css/
│   ├── design-system-1.0.css
│   ├── design-system-1.0.min.css
├── fonts/
│   └── [design system web fonts]
├── images/
│   ├── design-system-icons.svg
└── js/
│   ├── design-system-1.0.js
│   └── design-system-1.0.min.js
└── [additional files]

Creating pages and using components

Provide information on how to properly link up design system files in order to create a basic “hello world” template. From there, describe the process of incorporating design system’s components into the project. Again, this will undoubtedly vary based on the setup and technologies your organization utilizes.

Code conventions

Provide a link to learn more about code conventions.

Support and Community

Provide information on where people can go to ask for help, and provide a link to the contribution page to help plant tback to the system.

Styles

The attributes of the brand

Styles are guidelines for core brand attributes, organized by category. These are descriptions of conventions that cut across component and suggest the rules that go into building/designing components and their treatment. Each of these pages is effectively a reference article on how to use and approach the specitic subject area.

Color

Primary Colors

Secondary Colors

Color usage information goes here

Typography

Intro note if necessary.

Desktop Styles

Mobile Styles

Alignment

Describes the positioning of elements in the design system

Description

Iconography

How to style or construct icons for the design system

Icons are a unique beast, so it's important to define how to use and create icons for the design system.

Imagery

Styles for treating pictures and graphics

Image style guidelines go here.

Motion

How the style guide uses motion to enhance the user experience.

For inspiration, check out [Material Design's thorough motion guidelines](https://material.io/guidelines/motion/material-motion.html#material-motion-why-does-motion-matter), as well as all of [Val Head](http://valhead.com/)'s fantastic resources around UI animation.

Voice and Tone

Capturing the personality and authority of the brand in words

For inspiration, check out MailChimp's fantastic [Voice and Tone](http://voiceandtone.com/) website.

Guidelines

Guidelines is where you’ll find UX guidance for specific aspects of app/site design (navigation models, data entry, form validation, accessibility, and so on). These will give high-level tours of the relevant components and styles, with links to the specific pages in the components and styles sections for more detailed guidelines on each element. Each guideline is effectively an article on good usage.

Design Principles

The design system’s guiding values

Here is where you take the time to explain the principles that are encapsulated in the entire design system. These principles will manifest themselves in different ways, from high-level guidelines to low-level components.

For inspiration, be sure to check out Design Principles FTW and what goes into creating good design principles.

Code Conventions

Guidelines for the design system’s code base.

Check out the Frontend Guidelines Questionnaire and CSS Architecture for Design Systems for inspiration.

CSS Utilities

Definitions of helper classes

Utilities are CSS helper classes that apply a single rule to an element. They should be used to accomplish specific styling needs, and should be used sparingly, especially when modifying the default styling of a Style Guide Guide component.

Accessibility

The design system’s approach to accessibility

For inspiration, check out [Salesforce's Lightning Design System accessibility guidelines](https://www.lightningdesignsystem.com/guidelines/accessibility/), and be sure to check out the fantastic [a11yproject](http://a11yproject.com) for an accessibility checklist, patterns, and resources.

Data Display

Presenting quick, actionable data

Data display guidelines go here

Data Entry

High-level form guidelines

Data entry guidelines go here

Data Validation

Guidelines around validating data

Guidelines go here

Input Modes

Guidelines around multiple types of input

Guidelines go here

Navigation

Guidelines for getting around a UI

Guidelines go here

Notifications

Guidelines around how and when to respectfully interrupt users

Guidelines go here

Writing

Guidelines for writing best practices

Guidelines go here

Browser Support

There is a difference between [support and optimization](http://bradfrost.com/blog/mobile/support-vs-optimization/). These guidelines explain which browser environments the design system is optimized for, typically in the form of [graded browser support](https://github.com/yui/yui3/wiki/Graded-Browser-Support).

Blocks and Cards

Items on a page that are singled out, boxed in, etc.

Description

Charts and Graphs

Essential data-viz patterns

Description

Form Controls

The look and feel of form elements

Description of individual components

Icons

Icon reference and usage

Description of icons used in the design.

Buttons

Button reference and usage

Description of buttons used in the design.

Interactive Panels

Components for revealing/hiding content for more compressed and focused layouts

Descrioption of tabs, accordions, modals etc.

Lists and Collections

From simple text lists to complex card collections

Description of types of lists.

Media

Images and video

Description of media types and specs.

Messaging

Tools for status and info updates, from micro-copy tooltips to high-impact alerts

Description

Navigation

Components for wayfinding

Tables

Responsive data display for a range of contexts

Text

Text components description

Description and usage of headers, subheads, text blocks, etc.

Page Templates

This section collects commonly-used page templates that are useful as a starting point for similar use cases.

Header

Visuals and description of the header.

Footer

Visuals and description of footer template.

Newsroom/Blog Main

Visuals and description of template for the main news/blog page. Discuss column widths, best placement of content types, etc.

Newsroom/Blog Article

Additional Pages

Description of templates for additional pages, usually using the Smart Parts flexible grid. Discuss column widths, best placement of content types, etc.

Smart Parts

Descrption of the WordPress theme used in this website

Overview of the Smart Parts WordPress theme.

Grid System

Proper usage of the Smart Parts grid system

Description of classes, media queries, grid breakdown, etc.

CSS Classes

Handy, reusable CSS classes.

List, descriptions and usage of Foundation 6 classes.

Flexible Template

How to build a web page using the Smart Parts flexible template

Details on how to use the flexible template. Adding rows, content types, etc.

Options Page

Usage of the WordPress Options page

Details on all the content that can be changed in the ACF options section of the WP backend.

Custom Post Types

WordPress custom post type usage

Sliders

Description of CPT usage

CTAs

Description of CPT usage

Downloads

Assets related to the design system

Can include links to zipped asset files uploaded through the Media Library, as well as links to additional resources.

Support

Information about getting help with using the design system

People

Describe who’s involved in changes to the system. Describe who’s expected to do the work and who approves changes.

Process

Describe specifically the process or processes by which the system gets updated. What happens when existing component need modified? What if an entire new component needs created? What happens if a component is deprecated? See Canonical’s fantastic decision tree for contributing changes to their design system.

Since a design system is made up of component code, guidelines, documentation, design tools, and resources, keep in mind you’ll likely need to define several processes to contribute each of these ingredients.

Support

Cross-linking to the support page is a good idea here.

Contribute

The process by which the design system gets updated

People

Describe who’s involved in changes to the system. Describe who’s expected to do the work and who approves changes.

Process

Describe specifically the process or processes by which the system gets updated. What happens when existing component need modified? What if an entire new component needs created? What happens if a component is deprecated? See Canonical’s fantastic decision tree for contributing changes to their design system.

Since a design system is made up of component code, guidelines, documentation, design tools, and resources, keep in mind you’ll likely need to define several processes to contribute each of these ingredients.

Support

Cross-linking to the support page is a good idea here.