Warhol is a tool unlike any other, so we need to make sure that we all speak the same language. This page introduces you to Warhol's fundamental concepts and all warhol-specific lingo that you will come across.
Pattern library #
A pattern library is a web page that contains interactive example implementations of styles and components. The pattern library is the single source of truth for your team and also for Warhol. Warhol analyzes the pattern library's HTML and CSS to build up its knowledge about your design system.
What we call a pattern library is not to be confused with the term style guide. “Style guide” is a broad term that may include PDF documents that define abstract rules for design (and even non-design related things) in words or images. In contrast, a pattern library in Warhol's world is always an interactive web page that uses (or at least outputs) HTML and CSS.
(Production) Web Page #
The term production web page refers to any page that implements the styles and components that are defined in a pattern library. A production web page is where you use Warhol's browser extension to find design errors. The page in question does not really need to be “in production”, it is just the part of your project that is not the pattern library - pattern library and production web page are the two sides of the same coin. The distinction between pattern library and production web page is important, so be sure that you know which of the two you are dealing with whenever you come across an error message or read documentation!
A project is a specific production web page that you manage in the web app. A project links a pattern library to a URL for a production web page and provides a few configuration options that control how Warhol runs tests on pages that belong to the project.
If you have one pattern library that defines components for both a web page and a mobile app and you need to tweak some settings between those two use cases, two distinct projects are what you need.
The theme consists of the color palette, typography rules and icons defined in your pattern library. It constitutes basic design rules that apply to all elements in a production web page, components as well as non-components. If your pattern library was a country, the theme would be its constitution.
A component is any standalone building block used for a web project, built with markup and CSS styling. Examples for components are buttons, teasers or even more complex UI objects like a modal dialog. If you know the CSS methodology BEM, components are the B in BEM. From the perspective of Atomic Design, components may be atoms, molecules or sometimes even organisms. If your project was a country, and we think of the pattern library as its constitution, components are individual, specific laws.
For Warhol to property work with components, they need to have unambiguous, unique selectors. The selectors used in the pattern library do not need to be the same selectors as in the production web page, but both must be unambiguous and unique in their respective universes.
The term “component” usually refers to the component as a whole, including any elements the component may contain. Elements inside a component are called component children. Components in the pattern library are called component definitions, components in production web pages are referred to as component implementations. A component definition defines the exact styles and child elements that a component implementation must implement. Warhol will complain about any deviation in a component implementation from the component definition.
Snapshots are data about components and component children that Warhol extracted from a pattern library. When Warhol checks your production web page for errors, the page is actually compared to the snapshots that were created from the pattern library.
Each component gets its own snapshot with sub-snapshots for its children (containing sub-snapshots for its children and so on). While every component is guaranteed to get its own snapshot, component children that are subject to the same style rules get merged into one snapshot and are treated as completely interchangeable. A child snapshot does not describe a specific element but rather something that certain style rules apply to.
The hearts of Warhol's automated services are automated browsers and breakpoints are simply these browser's screen sizes in pixels. Warhol takes snapshots at each of the breakpoints and when testing, picks the matching sets of snapshots for the current screen size as its reference data.
Every element that is neither a component nor a component child is a non-component, also sometimes just called an “element”. Non-components don't have any canonical implementation in the pattern library but must instead follow the broader style rules laid out by the theme.