Introduction

Why a design system?

A design system ensures brand and user experience consistency and solves the development cost problem faced by companies with multiple products. Avalara, for example, has 20+ web apps being built and maintained by a dozen teams in 7 locations. How do we ensure UI development is done in a cost-effective way? By using a design system. How does Avalara ensure these products are on-brand and the experience is consistent? By using a design system.

How do I use the design system?

First, settle one thing in your mind: we use shared components. Need a color value? Use one of the shared CSS Custom Properties. Need your page to be responsive? Use the Grid. If a shared component doesn't meet your needs, open a Jira ticket.

Second, get familiar with this web site. The Doc Site (this web site) is the single source of truth for Avalara designers and UI devs. Do not rely on previously implemented UI, outdated specs, or hallway conversations. Draw directly from the Doc Site Demo and API sections as well as making sure to read the Guidelines section for every component you use (see Badge Guidelines for an example).

And lastly, use it! Let the design system do most the work so your efforts can be focused on your app's unique requirements. Using a design system saves you time and maintenance, ensures consistency, results in a lot less code (which means smaller files, faster downloads, and less code surface that needs testing), and in many cases will automatically improve your app for free as the design system improves.

s- versus aui-

s- and aui- components are built the same (custom HTML tags or Custom Elements using HyperHTML). The difference is that s- components are generic UI elements that have no relation to Avalara or our business domain, whereas aui- components are specific to Avalara. For example, s-alert is a simple UI element meant for communicating important information. That's not unique to Avalara products or taxes or compliance. It could be used for any kind of product and so it belongs in s-. Compare that to aui-footer which is very specific to Avalara - it's content is Avalara content and it links to other Avalara products. It's not Avalara agnostic so it's an aui- component.

Ok, I get that, but why make a distinction? The portability of s- components comes from not being tied to Avalara or the tax domain. This is just a good discipline to have for basic UI elements because it keeps their purpose small and focused, makes them portable, removes dependencies, and opens the possibility to open source them.