Making Design System Adoption More Visible in Live Products
Using custom user stylesheets to visualize component and style usage.
Using custom user stylesheets to visualize component and style usage.
One of the more tedious parts of a design system team’s job is auditing component and token usage in live products. With products often in different states of implementing our design system, part of our job is to find inconsistencies, suggest the use of available components, or offer better uses for design tokens.
While working on Castor (Onfido’s in-house design system), we often ask ourselves: “Is that a Castor select component or a custom component that‘s been *styled* similar to a Castor select?”. We squint at various shades of dark-grey text to try and discern whether they are consistent. We try to recall if that media icon was part of our official icon set or not?
We have many tools and metrics to help us answer questions like: which products are using which components, what % of colors in a product are RGB or Hex values instead of using our design tokens (we call these values orphans)? We also use Figma’s analytics and asset management tools for the design side. The problem with these is they’re either high level or are non-visual. To get the information we need, we frequently have to open a web inspector on a page and hunt for clues (classes, values, CSS variables).
There must be a better way.
The power of systems
Luckily for us, one of the best things about a well-built design system is consistency. When digging in the web inspector, we would look for signs of usage by looking for common patterns in the code.
All the components in Castor have CSS classes which are all prefixed with ods-
(which stands for Onfido Design System):
class="ods-button"
class="ods-select"
class="ods-tooltip"
Similarly, our color tokens are centrally managed in two layers, Theme aliases, and Base colors.
--ods-color-content-main: var(--ods-color-neutral-800), 1;
--ods-color-neutral-800: 59, 167, 32;
The rules to identify these things were relatively simple, so what if we could visualize these things based on those rules?
User style sheets to the rescue
User style sheets are local CSS styles that override existing styles on a page. You write them yourself and typically manage them with a browser extension. I chose Custom Style Script due to its ability to toggle each style on or off using the icon in the “State” column. If you’re not very familiar with CSS/HTML, you may need to bring in a helpful front-end developer to help at this point.
(I wish I had some magic bits of code that you could just copy/paste, and off you go, but each system will be different, and the approaches here may not apply to yours.)
Visualizing components
First, we wanted to see if we could make any components with Castor class prefixes visually obvious. Thanks to some advanced CSS selectors, we can do something like this:
[class^='ods-'], [class*=' ods-'] {
outline: 3px dashed red !important;
}
This rule selects any element that starts with our ods-
(Onfido design system) class prefix and puts a big outline you absolutely can not miss on them.
So this relatively consistent looking UI:
Becomes this:
We can now immediately see that the Creation date filter, the Search field, and the Sandbox toggle are not using our Castor components.
You can add or tweak any selectors as you wish to give you confidence that all your components are visible (we ran this on our Storybook instance to check).
Design Tokens
Components are only one part of a design system. Design tokens for us are equally important, so how do we visualize token use? We’ve focused on color tokens for now, and we want to visualize Theme colors and Base colors independently. To do this, we override the default palettes for these colors with colors well outside our brand palette.
Our theme tokens have content
, border
, and background
variants, so we picked three shades of purple to indicate these.
Our base palettes have up to 11 shades of each color, which we can override with this new green shade. It doesn’t matter if there’s no differentiation between palette colors for our purposes.
Visualizing theme colors
Because our theme colors are defined in a single CSS file, we can copy the CSS rules directly from the web inspector panel.
:root {
--ods-color-content-main: var(--ods-color-neutral-800), 1;
...
In a code editor (I used VSCode) we replace the var()
value with hard-coded RGB values of our purple shades. Darkest for content, middle for borders, lightest for backgrounds.
:root {
--ods-color-content-main: 172, 9, 199, 1;
...
When we paste these rules into a new user style and refresh the page, we get this:
We can now easily see that while Castor’s Field Label components aren’t in use, all the Field Labels use semantic theme colors, which is excellent. However, our “Checks” heading and our search component are not. We can also see that the Creation date component partially uses theme colors, but not for the text content inside. These are all problems we can add to the team’s backlog.
While we strongly encourage theme colors, as they enable dynamic theme switching and are just semantically easy to use, they aren’t required. Designers and engineers are free to use base palette colors if they choose. So let’s visualize those and see what slips through the cracks before we write our tickets.
Visualizing base colors
Base colors are stored in a similar format, except that they just contain straight RGB values. We take our tone scale which ranges from -100
to -900
and simply replace the RGB values with the values of our green shades, from light to dark.
:root {
--ods-color-neutral-900: 40, 160, 10;
--ods-color-neutral-800: 59, 167, 32;
--ods-color-neutral-700: 78, 174, 54;
...
Again, when we paste this into Custom Style Script (as a separate row), and refresh our page, we get this:
We can now see that we have pretty good base color coverage over the UI. However, the Search placeholder text and icon colors are not shades of green, so these are our orphan (RGB/Hex) colors.
Digital superpowers!
We now have a set of 3 style sheets that we can toggle on/off on any web-based product that uses Castor and get similar insights. You could probably do more here with user JS scripts or different combinations of CSS selectors.
I’d love to see what you all come up with to improve these techniques for your design systems.
The immediate work we would suggest for the team’s backlog is now a lot clearer:
Update the search field to use the Castor search component
Update the sandbox toggle to the newly developed Castor component
Update the filter field labels to use Castor components (low priority, as they work OK and are using theme colors)
Update the checks heading color to
content-main
for consistency with the rest of the text on the page
Remember that it’s definitely worth using the web inspector once you spot anomalies visually, as sometimes it can just be your CSS rules misbehaving.
HUGE thanks to Rogier Barendregt, Mark Opland, Luis Ouriach, Andre Rabello, and Marc Obieglo, and Grammarly for helping me improve this piece. 👏
Originally posted on Medium.