Lindsay MillerYour website’s look and feel sets it apart from everything else. It can be a real challenge to set up that theme so it’s easy to change and reuse later. But what about opening the doors for anyone to come along and restyle it at will? That’s the magic we set out to create with Web Awesome theming.
The need for speed
Picture this: you’re a web designer, and you’ve just curated a design language you’re really proud of. You’ve established your colors, typography, rhythm, depth…everything that goes into a site’s look and feel. When you implement this design language in your product, each of those design choices is repeated over and over again in your code.
The problem with static values
If all of those design choices are represented as static values, chances are you’re gonna have a bad time when you need to refresh your design or remember those choices as you implement something new. You could end up buried in line after line of CSS for days. Nobody has time for that! But by making those values repeatable variables with CSS custom properties, you can streamline changes to your design language, ensuring consistency with a whole lot less effort.
I’ve seen static values cause loads of trouble for something as simple as brand color. Once upon a time, I worked on a product that used hex code #2097d7, a light blue, throughout the app. This was for links, buttons, borders, and background colors. But, in a valiant push for accessibility, that light blue needed to be replaced by something that afforded greater contrast against white. Finding and replacing all instances of #2097d7 is one thing, but wouldn’t you know that #0099cc, a hex code for a very similar blue, was used interchangeably? Ugh.
Role-based color challenges
To make the matter more challenging, different instances of the same color often served different roles. For some roles, like borders, light blue may have been preferred; it just wasn’t appropriate for text or text backgrounds. With only static values to work from, there’s no choice but to scour every instance of those hex codes and decide whether it should change or remain the same. As a designer, you don’t just choose colors and font families and border widths; you choose how those will be used.
Developing a global theming API for Web Awesome
Let’s peek behind the curtain of the Web Awesome theming shop for a minute. When we set out to develop theming for Web Awesome, we knew we needed something comprehensive enough to support the near boundless range of design choices available to us. However, we needed something simple enough to change the look and feel of an entire project with just a few tweaks. That’s a tough balance to strike. Our objective was to establish a collection of CSS custom properties — an API, if you will — for creating full, cohesive themes with minimal effort.
Balancing simplicity and customization
Part of this balance between comprehensive and simple is ensuring you only need to change one or some properties to see results, but you can drill down for further customization.
Shoelace offers global custom properties to define values like --sl-color-primary-100 and --sl-font-serif in addition to CSS parts for granular customization. In Web Awesome, we’ve extended these theming options with role-based custom properties, multipliers to scale groups of related properties at once, and component-level custom properties for hooks into common qualities of each component. At the highest level, you have “dials” you can turn that affect many properties at once — say, how much space your design has or how round your components are — and at the lowest level, you can still target CSS parts to write your own styles from scratch.
Implementation and examples
Now, here’s where the rubber meets the road. Let’s say you want a more spacious design. With our Web Awesome theming API, you simply adjust the --wa-space-multiplier property, and voila, everything on your site breathes a little bit more.
:root {
--wa-space-multiplier: 1.2;
}Customizing specific components
How about changing the appearance of a specific component, like a badge? We could add a quiet variation to our badge component by introducing another class that leverages the custom properties in our theme to maintain consistency. It taps into the custom properties offered by the badge component to pierce through the component’s shadow DOM.
wa-badge[variant="danger"].quiet {
--background-color: var(--wa-color-danger-fill-quiet);
--content-color: var(--wa-color-danger-on-quiet);
}Best practices and tips
Creating a theming API for any design system, no matter how small, is challenging. Here are some things we’ve taken to heart that might help:
Avoid arbitrary abbreviations
The key to a good API is readability. --br may have fewer characters than --border-radius, but if it isn’t immediately recognizable in all contexts in which it might be used, prefer the longform name.
In Web Awesome, we spell out every word in our custom properties with two exceptions: 1) the Web Awesome namespace (wa) and 2) the t-shirt size scale we use for groups of custom properties (xs, s, m, l, xl, etc.). In both cases, we decided that the shortened version benefits readability.
Make names easy to guess
Using clever names or unique scales, like round – rounder – roundest, can be tempting (believe me, I know). But forcing users of your API to refer back to the documentation every time they need to use a custom property isn’t kind to them.
In Web Awesome, as much as possible, we named our custom properties to match the standard CSS properties they relate to and used a t-shirt size scale. Both t-shirt sizes and proportions (1x, 2x, 3x, etc.) are wonderfully predictable. (Need something larger than XL? Try 2XL.)
Don’t skimp on documentation
Even if your property names are descriptive and guessable, don’t assume that all the rules for their usage are indisputably clear. Thoughtful documentation can help bring everyone on the same page (so to speak). Your future self will thank you, too.
Start with only what you need
It’s easier to add to an API than to take away. If you think you might someday share styles between, say, an existing dialog and a future drawer, keep your styles scoped to the dialog for now. Promote those choices to the global API only when you know the drawer will use them, too. Projecting design choices onto use cases that haven’t been realized can lead to bloat and misuse of properties prematurely added to the global space.
Conclusion
In the world of web design, a global theming API is like a Swiss Army knife – versatile, reliable, and indispensable. By incorporating repeatable variables, clear naming conventions, and thoughtful documentation, Web Awesome theming makes it easy to achieve a cohesive and dynamic look and feel for any project. Whether you’re a designer or a developer, our theming API gives you the power to create and customize with unparalleled ease and efficiency. Ready to transform your designs with Web Awesome theming? Let’s get theming!
Oh! And for those experiencing Kickstarter FOMO, you can still do Late Pledges for WA Pro discounts and access to the WA Free alpha!
