Define a component


At this point in the tutorial, our pattern library consists of nothing more than a color palette. This is all nice and well, but does of course only cover very few of all the things that can go wrong with a web projects design. It is time to really nail down how our button should look. Components are Warhol's term for well-defined building blocks of a design system. Components in production must not only follow general rules like the color palette but must also implement all the styles that are prescribed by the pattern library.

Define the button component #

Lets take our old pattern library and add a canonical example of our ideal button component:

<!-- Color palette from before -->
<div class="colorExample" style="background: navy">Primary color</div>
<div class="colorExample" style="background: #EEE">Secondary color</div>
<div class="colorExample" style="background: rgba(255, 0, 0, 0.5)">
  Error color
</div>

<!-- Definition for a button component -->
<button class="basic-button">Example text</button>
<style>
  .basic-button {
    color: #eee;
    background: navy;
    font-weight: bold;
    padding: 0px 1em;
  }
</style>

Markup and styles - that's all you need to get started with components. The updated pattern library can again be hosted on your local machine or somewhere on the web.

Configuring the button component #

With font-weight and padding we introduced two CSS properties to the button that Warhol can't verify based on a color palette. Warhol needs take a proper snapshot of the component. For this, we first must make sure that Warhol can identify the button component in the pattern library and also find instances of the button component in the production web page. To do so, add some component configuration. Let's go back to the web app and update our pattern library configuration. Make sure that the Base URL points to the version of the pattern library that includes the button and then add the following to the “Components” field:

[
  {
    "source": ".basic-button"
  }
]

This is all that is strictly needed to define any component. Warhol will now

  1. pick all the elements that match the CSS selector .basic-button from the pattern library and read their styles
  2. if step 1 returned more than one element, abort and complain if the styles of the elements are inconsistent (we can't make production look consistent when the pattern library itself is not consistent)
  3. prepare to test all elements that match .basic-button and compare their styles to the .basic-button(s) in the pattern library

But before we get to testing, let's make our lives a little nicer by adding a name to the component definition:

[
  {
    "source": ".basic-button",
    "name": "Basic button"
  }
]

This has no effect on the tests themselves, but makes error messages a little more readable. Your components do not need names, but without names, the source selector will appear in place of the name.

Next, let us assume that you as the pattern library's author do not have final say over the classes and selectors used in production. Maybe you want to introduce a pattern library to a brownfield project where what should be the same button is re-implemented under several names many times over. Or maybe whoever runs production does not care that much about consistent class names. Whatever the reason: when the component selector in production is not the same as in the pattern library, the configuration property target is here to help you:

[
  {
    "source": ".basic-button",
    "target": ".btn, .button",
    "name": "Basic button"
  }
]

You only need to define a target when the component selectors in the production web page do not match the component selectors in the pattern library.

Testing component instances #

With this component definition entered into the “Components” field in the app we click on “Generate snapshot” and change back to our production web page to debug our button implementation over there. Owing to Warhol's relative newness, it to not yet automated enough to automatically re-generate the snapshots when the configuration changes and we must also manually re-download the snapshot data in the browser extension.

After that, we can re-run the tests (or just reload the page) and take a look at the reports:

This looks like there is a lot wrong with the component, but let's focus on the positives first: Warhol did identify the “Basic button” component correctly and it also did find some issues that are not related to the color palette. In fact, all the issues are very straightforward to fix: if we just update our CSS as the reports recommend, we end up with a component that does look exactly like in the pattern library.

Key takeaways #

Creating and debugging components is not really that hard: build the component in your pattern library, add it to Warhol's configuration, re-generate and re-load the snapshots and you are ready for debugging! The only aspect of this process that needs significant attention is choosing selectors, because component selectors must be unambiguous and unique. This is somewhat easier said than done when you start to consider composed component variants...

Join our Slack Community

Any question not answered yet? You want to get the latest information on Warhol and discuss new features? Join our Slack Community.