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.