Skip to main content
Photography of Alvaro Montoro being a doofus
Alvaro Montoro

HTML Surfer

water color of web design sketches

TEACH: A Practical Hierarchy for Styling Design Systems

A mental model for organizing styles in design systems, starting with the native capabilities of the web platform and progressively building toward more complex abstractions.

webdev css html

When exploring different approaches to organizing styles in design systems, I've noticed that we often lean heavily on class names while overlooking some of the native building blocks already provided by the web platform and the browser.

I have found it really helpful to approach styling through a clear, step-by-step hierarchy, moving naturally from foundational concepts all the way up to complex components. The idea is to start with what the browser already gives us for free, then progressively layer on what we must define ourselves.

I call this approach TEACH. It's an easy-to-remember mental model that helps me organize styles in a progressive order of complexity and foundational importance:

  • Tokens
  • Elements
  • Attributes
  • Classes
  • Hgh-level components

Focusing on these layers in this order can help build cleaner style libraries. By leaning on everything the browser and web platform already offer first, we can create more robust systems before writing custom high-level components.

Layered approaches to CSS architecture aren't new. Harry Roberts' ITCSS organizes styles into layers, moving from generic, low-specificity rules to more explicit, higher-specificity ones. TEACH is my way of organizing the building blocks involved in styling a design system into a single, easy-to-remember order.

Tokens

Tokens are the foundation of the style library. They are custom properties that define the core values of the system, from fonts and colors, to spacing and border radii.

Any customizable value that would be reused should have a token. Reusability is the key part there. We want to have consistent theming that is easy to update and facilitates white labeling.

Some classic examples for tokenization are colors; we may want a primary brand color, a secondary color, and perhaps tertiary or accent colors that are shared across buttons, headings, links, borders, and more.

:root {
  --primary-color: #36c;
  --secondary-color: #444;
  --accent-danger: #d22;
  --text-primary-color: #fff;
  --spacing-0: 0;
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  /* ... */
}

The number of tokens will likely shift while developing the design system as more needs emerge. Do not fear changes at this stage, but be thorough: this is the foundation for everything that follows.

Finding the sweet spot for tokenization is tricky, and it varies from team to team and project to project. I like to view it much like database normalization: too little, and you end up with repetition and redundancy; too much, and you find yourself splitting hairs over tokens that are rarely ever reused.

Elements

Native HTML elements are often overlooked in favor of classes, but in my opinion, they are an essential layer that should be front and center in any style library.

I like to treat this layer as an opinionated normalizer: different browsers apply different default styles to native elements. Use element selectors to normalize those differences while applying basic, library-oriented styles driven by the tokens.

a {
  color: var(--primary-color);
  text-decoration: underline;
  /* ... */
}

button {
  background: var(--primary-color);
  border: 1px solid transparent;
  color: var(--text-primary-color);
  display: inline-block;
  padding: var(--spacing-2);
  /* ... */
}

An obvious advantage of this approach is achieving a more unified experience across browsers. But there is another major benefit that should not be overlooked: as soon as the library is imported into a project, the pages instantly adopt the library's look and feel, without changing any class names or adding extra markup.

At this point, we have built the core of the style library without introducing any custom classes. There are many examples of classless libraries out there. Pico CSS is a great example: a lightweight CSS framework that shows how much you can do by styling native elements directly, with no extra classes required. (I even built a classless library myself!)

We have a foundation that harnesses all of HTML's built-in semantic and accessibility powers before scaling up further. That is the true beauty of TEACH: it is designed to be semantic, accessible, and scalable at its core.

Attributes

Take advantage of the built-in platform features whenever possible:

  • HTML includes many native attributes that can provide semantic information and serve as styling hooks.
  • ARIA states and roles can provide accessibility-related information that can also be used as styling hooks.
  • CSS pseudo-classes and pseudo-elements can target specific states or parts of an element.

Focusing on native features reduces and simplifies code while also helping shift the team's mindset toward clearer, more usable, more semantic, and more accessible patterns.

For example, we could style a custom combo button using a class like .combo-button-menu-expanded, or we could use the aria-expanded HTML attribute alongside the [aria-expanded="true"] CSS selector. The former is fine for humans, but the latter benefits both humans and machines by communicating explicit state information through the browser's accessibility APIs, making it available to assistive technologies. Not to mention, in some cases, this strategy avoids human error by keeping styles automatically in sync with the actual DOM state.

Stop for a second and think, "Do I need a class for this, or is there a native alternative already built in?" Consider some common native patterns:

  • Instead of .accordion-open, use [open],
  • Instead of .input-is-invalid, use :user-invalid,
  • Instead of .checkbox-switch, use [role="switch"],
  • Instead of .menu-expanded, use [aria-expanded="true"]...

At this stage, we still haven't defined a single custom class or component in our style library, yet we've already established a cohesive look-and-feel and leveraged native elements and attributes to style and communicate dynamic states.

Classes

Classes are the fourth layer of this five-layer hierarchy. This placement is not meant to diminish their importance (they are a core pillar of any style library). Rather, it reflects my preference for using classes as an extension mechanism when the underlying HTML and CSS features aren't sufficient. Not the default.

A classic example for using classes is styling anchor links to look like buttons, a common pattern found in most websites. By sharing styles across element selectors and utility classes, we ensure consistent design without repeating code:

button,
.btn-primary {
  background: var(--primary-color);
  border: 1px solid transparent;
  color: var(--text-primary-color);
  display: inline-block;
  padding: var(--spacing-2);
  /* ... */
}

Pure CSS components find their home in this layer. Components such as a layout grid system, flex containers, or utility wrappers. These patterns organize layout rather than style a specific semantic tag or component. Classes provide the ideal mechanism to apply them across the markup.

This eventually leads to a philosophical crossroads: should something be a class or an attribute? Should it be <button class="btn-primary"> or <button data-variant="primary">?

This is not a debate of classes vs. native attributes. This section is about classes and data attributes. Which approach works best for your project in terms of readability, usability, and maintenance is ultimately up to your team to decide.

High-Level Components

High-level components, or simply components (TEACH worked better as an acronym than TEACC), are where the style library stops being just a collection of styles and matures into a true UI architecture. Tokens, elements, attributes, and classes have already done the heavy lifting; this final layer packages everything into reusable, encapsulated building blocks.

A component is typically a custom element or a framework component. A self-contained piece of UI that bundles its own structure, styles, and behavior. I place them at the very top of the TEACH hierarchy because they should build upon the layers below them.

Components are where the design system becomes more portable and easier to adopt. Product teams can simply drop in a <date-picker> or a <user-card> without having to worry about low-level implementation details.

These components still require their own styles, but because we did the work effectively in the previous layers, that custom CSS is considerably reduced. In many cases, we could lean entirely on our underlying native elements and attributes to handle core states and functionality. It is a win-win.

user-card {
  background: var(--secondary-color);
  margin: var(--spacing-2);
  padding: var(--spacing-3);
  /* ... */
}

If we are using web components, these elements may rely on the shadow DOM for encapsulation. Even though it isolates styles from the rest of the page, the TEACH hierarchy would still be a great guide for structuring what goes inside them.

The styling for these components can be implemented in a thousand different ways: vanilla CSS, Tailwind, Sass, or CSS-in-JS... all while continuing to follow the TEACH mental model.

Conclusion

When looking at many design systems, I often see a strong emphasis on design tokens and high-level components, with native HTML elements and attributes treated almost as an afterthought.

There's nothing wrong with that approach, but it reminds me of the classic demonstration of filling a glass jar. If you only pack it with big rocks, you end up with a lot of empty space. You need the smaller gravel and sand to fill the gaps. That is precisely where the Elements and Attributes in TEACH fit in.

This model is not meant to replace what you are already doing. Instead, it offers a complementary mental shift: a way to pursue simplicity and functionality across every layer of web architecture.

  • Tokens
  • Elements (native)
  • Attributes (native)
  • Classes
  • High-level components

While I like this mental model, I know it isn't a one-size-fits-all method for every project or architecture. It may not fit particularly well with a utility-class-first approach, and globally scoped element selectors will make some design system architects cry foul.

This is simply my preference, and I know it won't work for everyone. Take the parts that make sense for your project, adapt them to your needs, or use them as inspiration for your own approach. Whatever direction you choose, make sure to teach your style library to make the most of the semantic, styling, and accessibility features already provided by the web platform.

Article originally published on