Process

WIP

Token: Should primarily be a value, functionally agnostic.
Element: Composition of various tokens. Specific function, content agnostic.

Component: Composition of various elements, may serve specific functionality that applies to a variety of content use cases.
Utility: Specific function, is either not visible or exists temporarily.

Designer or engineer identifies a need for a new shared component in a project within sprint work.
The design team evaluates the request as a legitimate candidate to be added to the design system.
If valid, designer creates a detailed spec for shared component, and surfaces the need for component in sprint planning. If there are known instances of components that the new component will make obsolete, designer will list this audit in the component spec. Designer should consider both web and mobile platforms when specing out the new component.
When the component is included in a sprint, designer creates a GH Issue, added to the Component Workflow project (link), announcing the new component. The issue includes a responsible engineer and designer.
This issue is shared in #design-system.

Engineer starts building the component in Palette (link to Readme docs), publishes the component as "WIP" with a reference to the issue created by the designer. To keep the project board updated, the pull request for the new component should reference the issue created by the designer. (You can find instructions on how to close issues via pull requests here)
Designer can start adding content to component, in WIP state.
Engineering and Design pair to bring component to full QA'ed completion.
When component is ready to merge, WIP label is removed, Issue is "closed".
The new component is ready for use, and announced in #dev (?)

The same process applies for updates to existing components as well — the emphasis on communication ensures visibility, trust and successful adoption of this system.

We use a github project board to keep track of the process of shipping a new component. The following section describes each swimlane and its purpose in the process.

Board columns

To do: tickets for components being proposed by designers and engineers alike which we review during the design system meeting
In Design: new component design and spec is being worked on by the design team
Design Done: design for new component is completed and uploaded to Zeplin
In Progress: an engineer has created a PR for the component implement and linked the issue to said PR
Visual QA: new component is ready to be visually QA'd before merging the PR
Documentation: a designer and/or engineer has added documentation for the new component
Done: Pr has been merged and new component is now available for use

We only use the following variables to describe sizes: x-small (xs), small (sm), medium (md), large (lg), x-large (xl).

If a similar component comes in more than one size, the components should be named as explicitly as possible to it's use and function, so that people will understand when and how to use it. (e.g. Input, QuickInput).

We use the following terminology to describe common states: default, hover, active, disabled, error.

Have questions? Join us in #design-system on slack, we're always happy to help.