Principles of Authoring a Pattern Library

Whether you want to use Warhol or not, having a pattern library is vital to getting your project's design under control. But not all pattern libraries are created equal. Some do a better job at synchronizing your team's understanding of your design system than others and the ones that do the job tend to follow a set of common principles. This article presents the definitive principles for authoring a good, useful and consistent pattern library. It helps you to ensure that the pattern library remains up to date, extensible and actually sees some use by your team.

Glossary for any pattern library

Every design system has its own vocabulary. This glossary defines some common terms that should work with any pattern library, design system or CSS methodology.

Pattern library

A pattern library is a web page that serves as the single source of truth for a design system. It defines the color palette for a project, shows how components are composed and which typography properties can be combined. It contains canonical examples for every building block of user interface that can appear in a project. The building blocks themselves are called the elements of the pattern library and consist of components, a theme, and utilities.

Components

A component is any standalone building block used for a web project, built with markup and CSS styling and might have any special behavior driven by JavaScript. Examples for components are buttons, teasers or even more complex UI objects like a modal dialog. Components are defined via canonical examples in the pattern library. The term “component” refers to the component as a whole, including any child content the component may contain. The canonical definition of a component in the pattern library is called the component definition, an instance of the same component in the actual project (outside the pattern library) is a component implementation. HTML elements inside a component that are not components themselves are called component children. Like the component root elements themselves, they have to be implemented exactly as the pattern library prescribes, down to the last pixel (excluding content of course).

On large, sprawling brownfield projects it is unreasonable to expect a pattern library to define all possible components all the time. Non-components are bits of the user interface that do not follow any component definition, but still must adhere to the theme. They may appear in the production project, but not in the pattern library.

Theme

The theme represents the pattern library's fundamental styling rules like the color palette, fonts and typography features as well as icons. Everything in the project has to follow the theme's rules, whether the element is a component implementation or not.

Utilities

Utilities are additional style rules that can be added to components to tweak their look and feel or to adjust their positioning. Classes that add shadows, floats plus margins or take care of grid positioning are prime examples of utilities. Utilities can be combined, if their styles do not contradict each other.

Principles for authoring a pattern library

The principles for authoring pattern libraries follow the MoSCoW prioritization. Items marked as “must” are hard requirements, “should” is a recommendation and “could” amounts to a nice-to-have.

Must

• A pattern library must be designed for human consumption first. Tools have to adopt to human requirements, not the other way around.
  • Navigating the pattern library must be easy and accessible for everyone.
• A pattern library must be a living web document that adapts to changing circumstances over a project's lifespan and where new components or variations of a component can easily be added. PDFs and other non-interactive formats are not suitable for pattern libraries.
• A pattern library must be designed with extensions in mind. Other pattern libraries must be able to build upon the patterns and components in any other pattern library. An indicator for this is if the library provides guidance on where to extend (which components) and if the code examples do have an extendable API.
• Everything defined within a pattern library must be responsive and the pattern library must offer a user interface that allows the user to view the element in question in its various responsive states.
• Components must be self-contained building blocks of user interfaces that do not depend on any external context apart from a common reset or normalization of styles.
• All components defined in a pattern library must be defined via comprehensive, canonical implementations in HTML and CSS. The styles on multiple examples of the same component must not contradict each other (excluding component variants).
• Components in the pattern library must be defined with clearly recognizable example content, filler text and placeholder images.
• Components must be defined in a way that they are easily reusable by any implementer. The component definition must not depend on specific technologies or frameworks but can be build upon such.
• The color palette and all fonts and typography combinations which can be used throughout a project must be part of the pattern library.
• Definitions for theme, utilities and components must be clearly distinguished and must not be reused for other purposes in the pattern library. For example a component definition must not also serve as a source for colors or typography information.

Should

• Developers should be able to easily improve and extend a pattern library (for example to add documentation and notes).
• The pattern library should be as comprehensive as possible at any given point in time. It should represent as many components with as many use cases with as many examples as is reasonable given the project's overall state.
• The most common variants of a component should be represented first, with less common variations being shown afterwards.
• All elements in the pattern library should be documented explaining how and when to use them and how and when not to use them.
• Components should be authored in an extensible manner so that developers using the pattern library can add new behavior when needed.
• Components should be marked as container components if they can contain other components (like a card component which holds images, texts, buttons) and as presentation components if they can not (like a plain, basic button).
• A pattern library should provide developer tooling to easily use the component code, like a button to copy a component definition's code to the clipboard.
• The pattern library's user interface should be built from the components it defines to facilitate a better understanding of the components and to prevent the pattern library's user interface and the component's styles from influencing each other.

Could

• A pattern library can define components that are not used by every project that is served by the pattern library.
• A pattern library may be set up as one or many code modules which can be directly used by implementers.
• A pattern library can provide interactive user interfaces for implementers that go beyond just defining components. A typography playground or drag-and-drop component composer are useful additions to any pattern library.

Every project deserves a principled pattern library

Pattern libraries are vital for teams of any size. Good design is rooted in consistency and without a single source of design truth, maintaining consistency is next to impossible. This guide serves as a checklist for your pattern library, no matter if your project is just about to start or if you maintain a large legacy project – with or without an existing pattern library. By sticking to the principles you will create an actually useful design reference that both your human team and tools like Warhol will appreciate.

This guide, like a good pattern library, is extendable. If you feel that there's something that we missed (or got completely wrong) please tweet at us!

from Hacker News https://ift.tt/3gmAuRN