Jonathan Dallas

HTML Interfaces For CSS Libraries

Sun, 03 Nov 2024 00:00:00 GMT

I’m using the term “CSS library” to refer to a repository that exists to provide styles for components. Perhaps "component CSS library" would be more accurate? This article is basically a grab bag of loosely held opinions presented as suggestions.

One of the big ideas behind pulling in a CSS library for your components is that the consumer of the library should be able to configure presentation of a component without touching CSS. The developer should be able to name the component configuration they want in HTML and the styling should just work. Let’s talk about some ways that API could be made more intuitive and easier to manage.

Avoid using the class attribute as API

Component configuration from the perspective of a CSS library typically consists of things like component name, variant, size, etc. These are effectively key-value pairs but I often see this type of API being set via the class attribute.

<!-- Don't do this -->
<button class="
  button--default
  button--standard
  button--medium
">

Using the class attribute for this has a number of issues:

All of it is jammed into a single HTML attribute so can be difficult to differentiate one config from another.
There is no indication of which config each value is setting. What are "default", "standard", "medium" referring to? The developer might not know unless they looked at the documentation for the library and even then it might not be obvious.
No clear way to know what library is being used here. If a developer is new to maintaining a project using this CSS library, it may be difficult for them to know where to begin when looking for documentation.

A better approach is to use data-* attributes.

<!-- Do this -->
<button
  data-ln-variant="default"
  data-ln-treatment="standard"
  data-ln-size="medium"
>

Above example uses ln short for "Library Name" as a sample library-specific namespace. A project like Spectrum CSS might use sp, Tailwind tw, etc.

Using data-* attributes for CSS library APIs makes it clear what each config refers to because there is a clear delineation between key and value.

Use library-specific namespacing

Consider adding a brief namespace unique to the library so if someone were to paste any of these API names into a search engine they would have a better chance of quickly finding a docs page for the library. This also helps to avoid potential collisions with existing code.

<!-- Don't do this -->
<button data-variant="large">Launch</button>

/* library styles */
[data-variant="large"] {
  /* These styles might collide if the project
     importing this library already styles
     a `data-variant` attribute. */
}

In the above example, if a project already styles data-variant, or imports another CSS library that does, that would collide with this library’s styles.

<!-- Do this -->
<button data-ln-variant="large">Launch</button>

/* library styles */
[data-ln-variant="large"] {
  /* The library namespacing helps ensure
     that only this CSS library will style
     this attribute. */
}

Requiring a short library-specific sigil on the custom data attributes used by the CSS library reduces the risk of code conflicts and makes the code easier to follow.

Decide if the library will style tag names or only attributes

You may be thinking that putting the data- prefix in front of all these attributes is pretty verbose. That prefix is required for custom attributes on standard HTML but not for custom HTML elements. Additionally, you can drop the library-specific prefix on the custom attribute since it’s already clear from the library prefix in the tag name where this attribute is defined.

<!-- data prefix needed -->
<button data-ln-variant="large">Engage</button>

<!-- data prefix NOT needed -->
<button-ln variant="large">
  <button>Engage</button>
</button-ln>

Above example uses ln short for "Library Name" as a sample library-specific namespace. A project like Spectrum CSS might use sp, Tailwind tw, etc.

While requiring a custom element for every component can be useful for consistency purposes, it will require additional complexity to do that. In the example above, the native <button> element is still desired for accessibility which makes the component a little more complex.

<!-- Native button element hidden in Shadow DOM -->
<button-ln variant="large">Engage</button-ln>

<!-- Shadow DOM declaration -->
<button-ln …>
  <template shadowrootmode="open">
    … <!-- focus management galore -->
    <button><slot></slot></button>
  </template>
</button-ln>

It is worth noting that using data-* attributes gives access to a special dataset API in JavaScript. Not of much use for a CSS library, but something to consider if that would be useful for configuring functionality in JavaScript.

Whether it’s better for a CSS library to style data-* attributes or custom elements with custom attributes may depend on the library’s goals.

If the CSS library exists only to provide styling for a single component library, requiring a custom tag name for every component and custom attributes for every configuration instead of using data-* attributes seems like a better fit.
If the CSS library exists to be more general and support multiple component libraries, using the data-* approach and never styling tag names directly seems like a better fit.

Consider making namespace secondary to API name

Think about the developer user experience of interacting with this library’s API in the web inspector. Ideally information which is repeated should be secondary to information that is unique. To achieve that goal, consider putting API name first and namespace second.

<!-- The eye reads the less significant info first -->
<ln-popover …>
  <ln-toolbar …>
    <ln-button …> … </ln-button>
    <ln-button …> … </ln-button>
    <ln-button …> … </ln-button>
  </ln-toolbar>
</ln-popover>

<!-- The eye reads the more significant info first  -->
<popover-ln …>
  <toolbar-ln …>
    <button-ln …> … </button-ln>
    <button-ln …> … </button-ln>
    <button-ln …> … </button-ln>
  </toolbar-ln>
</popover-ln>

Above example uses ln short for "Library Name" as a sample library-specific namespace. A project like Spectrum CSS might use sp, Tailwind tw, etc.

Wrapping up

There’s a lot more to say on this topic, but I’m going to end here for now. Please feel free to reach out via the links in the footer. I’d love to continue the discussion!

Naming Variables In CSS

Sat, 07 Oct 2023 00:00:00 GMT

“Naming things is hard” goes the software engineering axiom and CSS is no exception. Here are some collected thoughts related to naming CSS Custom Properties. I'm going to use use the terms "variable" and "custom property" interchangeably since they are effectively the same thing for the purposes of what to call them.

Disclaimer: What follows is not gospel. CSS to me is a very poetic language, there are so many different ways to express the same concepts. I like these conventions but do not consider them the one correct way to name variables in CSS. If you disagree with any of my points below, I would love to learn from your perspective.

Casing

In naming variables, the first thing to talk about is what sort of casing to use. The industry seems have settled on kebab-casing (which makes sense) but I think it's worth considering an alternative.

Maybe camelCase isn't so bad

You might be surprised to learn that many of the native values defined within CSS do not use kebab-casing. For example, currentColor and all of the named colors (cadetBlue, rebeccaPurple, antiqueWhite, etc).

Consider mixing kebab-casing with camelCasing

We can use camelCasing mixed with kebab-casing to create variable names that are structurally consistent. The idea is to use hyphens to separate value type and namespace from variable name and then camelCase within each segment. Essentially: namespaceName-valueType-variableName. Let’s call this triptych notation. In my opinion, this convention makes it clearer at a glance what is the actual name of the variable and what is the metadata encoded in the name.

:root {
  /* Harder to scan: */
  --system-control-accent-color: blue;
  --system-focus-ring-color: cadetBlue;
  --system-label-color-quaternary: lightGray;
  --system-heading-title-font-size: 1.5rem;
  --system-subheading-font-size: 1.2rem;
  --system-caption-font-size: 0.65rem;

  /* Easier to scan: */
  --system-color-controlAccent: blue;
  --system-color-focusRing: cadetBlue;
  --system-color-labelQuaternary: lightGray;
  --system-fontSize-headingTitle: 1.5rem;
  --system-fontSize-subheading: 1.2rem;
  --system-fontSize-caption: 0.65rem;
}

With triptych notation, camelCase is used to limit the number of hyphens. This allows the middle segment to consistently be the value type and the last segment to consistently be the specific name of the variable. In my opinion, this consistent placement of hyphens makes custom properties easier to read quickly.

Namespacing

The example above has variable names that are prefixed with ‘system’—short for 'design system'. This is called namespacing. Namespaced variable names can help avoid collisions when CSS is shared by multiple projects. In other words, they help to avoid situations where a developer outside of your project accidentally defines a variable with the same name. Another benefit is that namespacing provides a hint in the web inspector as to which project defined the custom property.

Namespacing your variable names can be important for top level global variable names but I’d argue this type of name scoping is typically not neccesary or useful when a variable is defined below the top level. This is because CSS handles that for you. A custom property is always scoped to the selector in which the property is defined. If you define a custom property with a CSS selector for a custom element called quiz-library that custom property will only exist within DOM nodes that match quiz-library and their children.

:root {
    /* This variable is defined at the root making it shared
       globally so having a namespace is useful. */
    --system-color-labelPrimary: #000;
}

quiz-library {
  /* This variable is defined within quiz-library so it’s not
     shared globally. A namespace of "quizLibrary" would be
     redundant because the variable is only available within
     quiz-library elements and their descendents. */
  --color-questionTitle: var(--system-color-labelPrimary);
}

Value typing

The examples above include the type of the value ('color', 'fontSize', etc) in the custom property name. Consider including value type information in variable names so that maintainers of the code can have a sense of what kind of value the variable holds. This is often referred to as Hungarian notation.

button {
  /* Did they set a font family definition to a font size? */
  font-size: var(--system-elephant);
}

button {
  /* Clear now that the variable sets a font size. */
  font-size: var(--system-fontSize-elephant);
}

Names that are descriptive

There are two fundamental categories of variable names in CSS. Consider these two variables:

--color-icyBlue (value-based)
--color-accent (usage-based)

One of them is labeled as a constant—by name, "Icy Blue" should never hold anything other than a blue color value. The other is more dynamic, the specific color held by "Accent" could be expected to change depending on where it is used; for example, which project the variable is used within.

People call these categories lots of different names. I'm going to to call them value-based: names that describe a value, and usage-based: names that describe a use.

Where to use value-based naming

Variables with value-based names can be useful for restricting the number of values in your interface. As an example, it’s good design to limit your interface to a small set of colors. If every part of your UI uses a slightly different shade of gray, your design will look inconsistent and unconsidered. Requiring every use of color in your interface to be a variable allows you to limit your colors to the set defined as variables. The number of font sizes, font weights, animation durations, panel elevations (defined by the presentation of their shadows) can all be useful things to limit.

/* Value-based variables at the global level */
:root {
  /* Colors */
  --system-color-bondiBlue: rgb(0 58 71);
  --system-color-canaryYellow: rgb(255 239 0);
  --system-color-caribbeanGreen: rgb(0 204 153);
  
  /* Font Sizes */
  --system-fontSize-jumbo: 3.052rem;
  --system-fontSize-large: 1.563rem;
  --system-fontSize-small: 0.8rem;
  
  /* Font Weights */
  --system-fontWeight-bold: 700;
  --system-fontWeight-medium: 400;
  --system-fontWeight-light: 200;
  
  /* Durations */
  --system-duration-presto: 60ms;
  --system-duration-allegro: 125ms;
  --system-duration-andante: 500ms;

  /* Elevation */
  --system-boxShadow-slightlyRaised: 0 1px 2px 0 rgb(0 0 0 / 10%);
  --system-boxShadow-floatingBox: 0 0 30px 0 rgb(0 0 0 / 35%);
}

Color palettes

Many design systems name the colors in their color palette with a numeric suffix to indicate contrast with a base background color. The thinking is that it can be useful for consumers of the palette to be able to easily determine if a particular color will pass WCAG requirements for text color contrast. This is a clever idea but in many projects the colors that are used for text (the only ones which matter for WCAG’s contrast requirements) are very limited so naming the entire color palette that way just for a few colors can be overkill. Additionally I'm unconvinced that these numbers actually make it faster to implement contrast safe UIs. The contrast algorithm used by WCAG is likely going to change and there are a number of ways a color could be transformed in a way that would negate the value of the numeric suffix. If you're going to need to always double-check contrast-ratio in the rendered UI, no time has been saved using these numbers.

That said, these numbers do provide a useful utility of being able to see at a glance whether a color is lighter or darker. Though I feel using words rather than numbers is a nicer more human friendly way to accomplish that. Consider using compound names for color variables. One name that refers to the basic color (“red”, “yellow”, “blue”) and another that acts as a differentiator (“cherry”, "sunflower”, “sky”).

:root {
  /* Not very human friendly */
  --system-color-red400: hsl(0 100% 50%);
  --system-color-yellow200: hsl(48 100% 50%);
  --system-color-blue300: hsl(200 100% 50%);

  /* Friendlier and easier to understand */
  --system-color-cherryRed: hsl(0 100% 50%);
  --system-color-sunflowerYellow: hsl(48 100% 50%);
  --system-color-skyBlue: hsl(200 100% 50%);
}

Keep differentiators analogous to real world things to avoid confusion. Don't use an abstract name like historyBlue because it would be unclear what that color would look like.

The goal is to get to a unique color name format that can support an endless number of tints, shades, and tones but at glance still be clear from the name what the color probably looks like so someone can see if the color was accidentally used in the wrong spot in the code.

button.destructive {
  /* There's a UX bug in our code if this color isn't red
     but the variable name below is somewhat ambiguous. */
  color: var(--system-color-ferrari);
}

button.destructive {
  /* Clearer now at a glance that a red color was correctly set */
  color: var(--system-color-ferrariRed);
}

This naming convention can be expanded to incorporate alpha, though it's a bit of a stretch. Separately from naming, just as general practice, it’s often better to reach non-opaque color values in UI via layered transformations or usage-based named variables than to put them into the static color palette. That said, when I have needed to write a value-based variable name for a non-opaque value using this convention I’ve put that info at the start of the color name using terms analogous to real world transparency.

:root {
  --system-color-semitransparentBondiBlue: rgb(0 58 71 / 10%);
  --system-color-translucentBondiBlue: rgb(0 58 71 / 30%);
  --system-color-frostedBondiBlue: rgb(0 58 71 / 70%);
}

Where to use usage-based naming

Variable names tied to use provide varying levels of abstraction. Put another way, names can communicate different scopes of capability and utility within the project by describing uses that are more specific or more general. Some are very narrow in use because they describe a very specific thing and some are very wide in use because they describe a general category of things.

For a very contrived example, consider naming the font weight used in a button that submits a registration form. That variable could be named something like --fontWeight-regFormSubmitButton but that's very specific. Typically all submit buttons look the same way in which case the concept of a 'submit button font weight' could be abstracted out into a less specific name like --fontWeight-submitButton. That name is more general and as a result at a higher level abstraction because it doesn't refer to a specific form anymore.

It often makes sense to combine variables with multiple levels of abstraction in a project. Here is how that could come into play with control tinting:

:root {
  /* Color palette defined at root */
  --system-color-bondiBlue: rgb(0 58 71);
  --system-color-canaryYellow: rgb(255 239 0);
}

body {
  /* Custom property for custom controls */
  --color-accentColor: var(--system-color-bondiBlue);
  /* Reflect it below for native controls */
  accent-color: var(--color-accentColor);
}

foobar-custom-control {
  /* Define CSS interface allowing the background to be changed */
  --color-background: var(--accentColor);
  /* Implement the above interface */
  background: var(--color-background);
}

form.tinted {
  /* Define CSS interface for applying tint colors to form */
  --color-formTint: var(--system-color-canaryYellow);
}

form.tinted foobar-custom-control {
  /* Utilize the above interface for foobar-custom-control */
  --color-background: var(--color-formTint);
}

Dark mode is simpler with usage-based variables

Consider an implementation of dark mode styling without usage-based variables vs one with them. When using only value-based variables, the code is much more repetitive and verbose.

/* Dark mode WITHOUT usage-based variables… */

:root {
  --system-color-deepBlack: #333;
  --system-color-offWhite: #eee;
  --system-color-skyBlue: lch(33 111 231.17);
  --system-color-deepBlue: lch(14 111 231.17);
}

/* Because the variables above are named in
   a value-based way we can’t reasonably change
   their values. Instead we fork our CSS below
   to use one or the other depending on the
   root appearance. */

[data-appearance="light"] body {
  color: var(--system-color-deepBlack);
  background: var(--system-color-offWhite);
}

[data-appearance="dark"] body {
  color: var(--system-color-offWhite);
  background: var(--system-color-deepBlack);
}

[data-appearance="light"] a {
  color: var(--system-color-deepBlue);
}

[data-appearance="dark"] a {
  color: var(--system-color-skyBlue);
}

With usage-based names you can define color variables as interface concepts that have understood meanings beyond individual UI pieces allowing for those values to be externally changed for dark mode without needing to maintain separate light/dark CSS for each new piece of UI.

/* Dark mode WITH usage-based variables… */

[data-appearance="light"] {
  --system-color-textPrimary: #333;
  --system-color-fillPrimary: #eee;
  --system-color-link: lch(14 111 231.17);
}
[data-appearance="dark"] {
  --system-color-textPrimary: #eee;
  --system-color-fillPrimary: #333;
  --system-color-link: lch(33 111 231.17);
}

/* With usage-specific variable names we can
   change the values for the uses they describe
   at a very high level of abstraction allowing
   the lower level code that uses the variables
   not to need to understand the current
   appearance mode. */

body {
  color: var(--system-color-textPrimary);
  background: var(--system-color-fillPrimary);
}

a {
  color: var(--system-color-link);
}

Levels of hierarchy within usage-based variables

Any time you have a design that references the same value across mulitple pieces of UI, I'd suggest that is an opportunity for abstracting that value into a name that better describes the intention of the value in the design.

For example, if the background color of your sidebar and your info panels are both #eee, relative to the #fff of your main background, perhaps your intent for that color from the design perspective is to convey to the user that UI with that background is of a secondary nature.

:root {
  --system-color-backgroundPrimary: #fff;
  --system-color-backgroundSecondary: #eee;
}

The utility of a usage-based name comes in how it guides a developer or designer in its use. Be careful to avoid using names the are too generic. For example, --system-color-primary is too open-ended in meaning making it unclear where it should be used.

/* Do not do this */

:root {
  /* What is this for? */
  --system-color-box: var(--system-color-neonBlue);
}

:is(a, button, input):focus-visible {
  /* Was this variable used correctly? */
  background: var(--system-color-box);
}

/* Do this instead */

:root {
  /* Clear what this is for */
  --system-color-focusRing: var(--system-color-neonBlue);
}

:is(a, button, input):focus-visible {
  /* Clear it was used correctly */
  outline-color: var(--system-color-focusRing);
}

Be careful to avoid using names that are too specific. For example, --system-color-mainToolbarBackground could only be used in one spot which makes the use of a variable superfluous.

/* Do not do this */

:root {
  /* This can only be used in one place meaning its
     existence needlessly adds complexity to the project */
  --system-color-mainToolbarBackground: #eee;
}

main .toolbar {
  background: var(--system-color-mainToolbarBackground);
}

/* Do this instead */

:root {
  /* This name is general enough in scope that it
     can be used across all UI so it is useful at
     the global level. */
  --system-color-backgroundSecondary: #eee;
}

main .toolbar {
  background: var(--system-color-backgroundSecondary);
}

Wrapping up

There’s a lot more to say on this topic but I'm going to end here for now. Please feel free to reach out, there are links in the footer. I'd love to continue the discussion!

Nested Dark Mode Via CSS Proximity

Sun, 07 Jan 2024 00:00:00 GMT

Note: This might be more accurately titled "Nested Dark Mode via CSS Inheritance" but I'm going with 'proximity' since that term helped me to grok this concept better. "Proximity" isn't a formally defined term in any CSS spec, as far as I can tell. However, there is a related term called "scope proximity" being defined for @scope.

Nested theming

Let's start by defining some terms. For the purposes of this article I’m considering Light/Dark Mode to be a theme. Nested theming is the case where the page is styled in one theme but sub-sections of it use another theme. A practical example of nested theming could be a scrolling product page that has discrete sections, some on a light background and some on a dark background, or maybe a rich editor web app that allows users to preview content in different themes.

CSS selectors don't consider proximity

Let’s look at a basic example of nested theming:

<div data-theme="blue">
  <a>Should be blue</a>
  <div data-theme="red">
    <a>Should be red (but is actually blue)</a>
  </div>
</div>

[data-theme="red"] a {
  color: red;
}

[data-theme="blue"] a {
  color: blue;
}

In the example above, the blue theme link style incorrectly applies within the red theme. This is because CSS is comparing the two selectors in isolation and in isolation both selectors have identical specificity, so last in wins. It is not considering where the component parts of these selectors are in DOM relative to the element targeted by the selector.

One fix would be to duplicate the styles for the nested theme but this adds significant complexity because it requires describing every combination of nested themes in advance.

/* Brute force solution that doesn’t scale */
[data-theme="red"] a,
[data-theme="blue"] [data-theme="red"] a {
  color: red;
}

To find a better solution we need to revisit some CSS fundamentals.

Inheritance

Some CSS properties inherit by default and some don't.

color is an example of a property that inherits. If the color property is set on <body>, all elements within that one will get that color value by default because all elements by default inherit their value for the color property from their parent element.

background is an example of a property that does not inherit. If the background property is set on <body> that value will only apply to the <body> element, not its descendants.

Proximity is a feature of inheritance

This behavior of inheriting the closest set value from ancestors means that the proximity of a given element to an ancestor with a set value determines the resulting value. If two or more ancestor elements have set values, the child element will always use the value from its closest parent. This is exactly the behavior we want for nesting themes. We only want the values from the closest theme container.

With that in mind, there is a much simpler way to fix the example from above:

[data-theme="red"] {
  color: red;
}

[data-theme="blue"] {
  color: blue;
}

<div data-theme="blue">
  <a>Should be blue</a>
  <div data-theme="red">
    <a>Should be red (and now actually is)</a>
  </div>
</div>

Did you spot the difference?

The selectors still have identical specificity but no longer style individual elements within their respective theme contexts. Now anchor tags are inheriting the color style instead of getting it set directly on them. This is the magic concept: CSS inheritance is based on proximity.

Custom properties always inherit by default

Where this gets especially cool with regards to nested theming is that custom property values always inherit by default and they can be set as values on CSS properties that normally do not inherit. In other words, via custom properties, we can make nearly all of CSS proximity-dependent.

Using proximity for nested dark mode

Here is an example that puts all of this together:

<main data-theme="light">
  <article data-theme="dark">
    <figure data-theme="light">…</figure>
  </article>
</main>

[data-theme="light"] {
  --color-backgroundPrimary: white;
  --color-backgroundSecondary: ghostwhite;
}

[data-theme="dark"] {
  --color-backgroundPrimary: black;
  --color-backgroundSecondary: gray;
}

/* Now uses of the custom properties defined above will always
   be correct for the given light/dark context set in DOM */

article {
  background: var(--color-backgroundPrimary);
}

figure {
  background: var(--color-backgroundSecondary);
}

Behold the magic of CSS proximity. Leveraging proximity via inheritance makes it simple to write styles for any number of theme contexts and nest them arbitrarily to any desired depth.

[data-theme="red"] {
  --color-primaryText: red;
}

[data-theme="blue"] {
  --color-primaryText: blue;
}

p {
  color: var(--color-primaryText);
}

<div data-theme="blue">
  <p>Blue</p>
  <div data-theme="red">
    <p>Red</p>
    <div data-theme="blue">
      <p>Blue</p>
      <div data-theme="red">
        <p>Red</p>
        <div data-theme="blue">
          <p>Blue</p>
        </div>
      </div>
    </div>
  </div>
</div>

The inherit keyword

At this point, you might be thinking: What about the inherit keyword? One of the major issues with using something other than a custom property for nested theming is it requires every ancestor element between theme container and target element to have the same value for that property. In many practical applications of nested theming, this is a poor solution because there will often be many elements between the theme container and target element and many of those elements should not have a value for that style. Custom properties are a way around this because, when they inherit, they have no effect on element styling until they are invoked as a property value.

Additionally, for a property like background which does not inherit by default, the inherit keyword would need to be set on that property for every element all the way down the chain; further increasing the code complexity.

Style APIs As A Last Resort

Sat, 15 Mar 2025 00:00:00 GMT

Last Spring I studied a popular CSS library and took a bunch of notes, originally just for my own purposes but, as I push myself to write more, I'm reformatting them into articles. This is the second of those. The first one was on HTML interfaces.

This article attempts to explain why style APIs should be avoided wherever possible, suggests how whole categories of style APIs may be unnecessary, and outlines what makes a good style API.

What is a style API?

I’ve seen others use this term, but I don't believe it has an established definition anywhere. I’ll do my best to explain what I mean when I use it.

A style API is an application programming interface for styling. You know that CSS lets us create systems, but the larger or more complex a web project the more the more we want to be thoughtful about the way we structure this system of styles. This is especially true if we expect the CSS to serve more than one web project. Systems of CSS go by many names—theme, library, framework—but the idea is that the consumers of such a CSS system are freed from worrying about CSS implementation details. They can instead work with CSS at a higher level by using an API to apply styles instead of writing them directly.

The project-owned connection points within CSS systems for controlling how CSS is applied is what I’m attempting to get at with the term "style API." In other words, the parts of a CSS system that are maintained to allow external users to use and configure the system. Examples of style APIs include component style variants, component style modifiers, utility classes, and even base design constants such as color palettes, text styles, shadows, glows, etc.

All APIs have a cost

The number of API entry points directly influences the difficulty of learning and using a system. Each API adds more for a consumer to learn and understand before they have mastered use of the system. Maintaining an API also takes time. As a system adds new API, the risk of regression increases.

If you’re with me on that, you’ll likely agree that any API should provide value that outweighs the burden its existence brings to the system. A style API should provide a utility that would not be possible without it. If the same result can be achieved without a style API, we’re in a stronger position by not having that style API.

Josh Clark’s article Ship Faster by Building Design Systems Slower goes into more depth on how being reluctant to add API is necessary for the success of a design system.

Let’s talk about Shadow DOM

It’s common to see style APIs created using custom properties to work around the style encapsulation of the Shadow DOM. CSS inheritance passes down into the Shadow DOM and all custom properties are, by default, inherited properties making those properties available on both sides of the shadow boundary.

<!-- Web component definition -->
<example-component>
  <template shadowrootmode="open">
    <label>Text</label>
  </template>
</example-component>

/* -- Project using this web component --- */

/* Does not work, cannot reach in
   and style the Shadow DOM like this. */
example-component label {
  background-color: gold;
}

/* Will work if styles inside of
   this web component use this specific
   API to set the label background color. */
example-component {
  --color-labelBackground: gold;
  /* However, this is a poor custom property name
     because it is just aliasing the `background`
     property. I’ll explain a better approach below. */
}

It’s cool that this works, but let’s look at an inherent problem with this pattern of mirroring properties.

Imagine a label element in the shadow DOM needs to be italic in some cases, and bold in others. Should a style API like --fontStyle-label be created?

/* -- Internal web component styles --- */
:host {
  label {
    font-style: var(--fontStyle-label);
  }
}

Consider a label background that grows darker on hover. Should a style API like --fontStyle-labelBackgroundHovered be created to support that usecase?

/* -- Internal web component styles --- */
:host {
  label {
    font-style: var(--fontStyle-label);
  }
  label:hover {
    background: var(--fontStyle-labelBackgroundHovered);
  }
}

What if focus styles need to match? Should another style API like --fontStyle-labelHoveredOrFocused be created for that?

/* -- Internal web component styles --- */
:host {
  label {
    font-style: var(--fontStyle-label);
  }
  label:hover {
    background: var(--fontStyle-labelBackgroundHovered);
  }
  label:hover,
  label:focus-visible {
    background: var(--fontStyle-labelHoveredOrFocused);
  }
}

Where to draw the line?

It’s not hard to imagine that as an API of this sort gets larger and larger it must inevitably recreate a sort of utility-first naming approach (similar to Tailwind) where modifiers for things like pseudo-selectors and media/container queries need to be encoded in the same namespace as CSS property names.

Reconsidering styling across the shadow boundary

Looking a little closer at how the shadow boundary is defined can be helpful in finding some more congruent ways to style across it without the need for creating APIs.

Of particular interest is that the Shadow DOM only shields styles from the shadow children of the web component. In other words, the shadow root element of the component is not style encapsulated. This means internal styles set using :host can be overridden by consumers of the web component.

It follows, then, that a component author can intentionally put styles on that shadow root to make those styles available for customization.

<!-- Web component definition -->
<some-element>
  <template shadowrootmode="open">
    <style>
      :host {
        /* Setting properties on the root of the
           web component enables consumers to
           override and change them. */
        border-radius: 50%;
      }
    </style>
    …
  </template>
</some-element>

/* -- Project using this web component --- */
some-element {
  /* We can change this because the web component author
     offered it on the outer element, which is above
     the shadow boundary */
  border-radius: 16px;
}

In the above example we've exposed the border-radius as style configuration without creating a style API.

I’m sure you can imagine many ways to leverage inheritance and other context-related features in CSS to provide more elegant style configuration across the shadow boundary before resorting to inventing new style API.

Consider these ways that the CSS language has built in:

The `inherit` keyword

Many native CSS properties are inherited by default and other properties can be made to inherit by setting the inherit keyword.

:host {
  text-align: /* This is one of the properties that inherit by default.
                 See the full list of others in the link above. */ ;

  /* This property does not inherit by default but can be told
     to with the inherit keyword */
  background: inherit;
}

The `currentColor` keyword

The color property inherits by default. This unlocks the ability to leverage the currentColor keyword for referencing the value on the color property as a value in any property value. There are many ways this can be used to automatically adapt component colors to an outer color. Gradients, border colors, accent colors, color-mixes, etc., can all be used with currentColor.

:host {
  color: /* This is one of the properties that inherit by default.
            See the full list of others in the link above. */ ;

  /* Using the inherited color */
  border: 1px solid currentColor;
}

Font relative units

The font property is a shorthand. This property and its constituent longhands (font-size, font-family, line-height, etc.) all inherit their values by default. This means that font relative units (em, ex, ch, lh, etc.) are (by default) relative to whatever font properties are set on the outer scope. This unlocks the ability to change any length within the component’s internally scoped CSS based on what font size is present in the component’s outer scope.

:host {
  font-size: /* This is one of the properties that inherit by default.
                See the full list of others in the link above. */ ;
  /* Using the inherited font size */
  height: 4em;
}

Container and media queries

Beyond direct property inheritance, consider how other forms of context can be used to adapt styles. Container queries provide the ability to apply a different style configuration based on the size the parent component is rendered at. This could be used, for example, to automatically change the variant of a component without the need for an API.

:host {
  container-type: size;

  control-group {
    /* Large variant */
    @container (height > 10rem) {
      /* Stack horizontally */
      flex-direction: row;
    }
    /* Small variant */
    @container (height < 10rem) {
      /* Stack vertically */
      flex-direction: column;
    }
  }
}

Bringing it together

Let’s put some of the above ideas together in a practical to example to illustrate how a web component can be style configured without the need for additional API.

<!-- Web component -->
<guitar-knob></guitar-knob>

/*-- Internal guitar-knob styles --*/
:host {
  /* There is a separate element for a focus ring to allow for
     a more fancy animation on focus */
  &:focus-visible {
    …
    .focus-ring {
      …
      /* The focus ring should match the rounded corners of the
         component. This can be achieved in a congruent way by
         inheriting whatever border-radius is on the outer element. */
      border-radius: inherit;
    }
  }

  label {
    /* The label text needs to be a little bit lighter.
       One way to achieve this in a congruent way is by inheriting
       the color of the outer element and then mixing it with white. */
    background: color-mix(in oklch, currentColor 20%, white);

    /* The space for the label needs to be two lines tall.
       A congruent way to do this is to use a font relative
       unit for the sizing. */
    block-size: 2lh;
  }
}

/*-- Project using the guitar-knob component --*/
guitar-knob {
  /* We’ve changed this knob to be a rounded square for a more
     unique look. The custom focus ring deep in the shadow tree
     is inheriting and now using this new border-radius. */
  border-radius: 20%;

  /* We’ve changed the text color on our use of this knob
     and, without any APIs, an element deep in the shadow tree
     is inheriting and now using this new color for the label. */
  color: rebeccapurple;
}

guitar-instrument {
  /* On this parent element we’ve decided to change the font,
     this new font is best with a taller line-height. The label
     deep down in the shadow tree of the guitar-knob is inheriting
     the new font and it’s larger line-height and has increased it’s
     block-size accordingly. */
  font-family: "Fira Sans", sans-serif;
  line-height: 1.6;
}

In the example above, all of the configuration across the shadow boundary is done without creating any style APIs.

When creating style APIs

Let’s switch gears now and talk about how to craft the style APIs that make up a CSS system. There are a few guidelines here that have formed in my head and I’ll go through them below.

Consider again whether the API is still needed

Before adding a style API stop and consider. Is there another way that doesn’t incur the cost of a new API? Before updating a style API, think about just removing the API instead.

CSS is exploding in capability. I wouldn’t be surprised to learn that the changes to CSS since the pandemic now exceed the previous 10 years combined. There are now incredible new features like cascade layers and color-mix both of which obviate large structural pieces of many existing CSS system architectures and both now have over 90% support in global browser usage.

The possibilities and potential for reimagining CSS architecture at scale have never been greater.

Avoid directly aliasing CSS properties

When naming a style API, use a declarative approach rather than an imperative one. Instead of directly aliasing an existing CSS property, look for ways to allow the consumer of the API to express the intent of their configuration. By being less prescriptive of implementation in the naming, the API is less likely to require changes to maintain semantic accuracy as the component internals get updated over time to add new features or adapt to different environments or design languages.

Ideally API names should only be expressing higher-level configuration options.

example-component {
  /* Imperative naming.
     Implies that labels in this
     component will set this value for
     the `background` color property. */
  --color-labelBackground: gold;
}

example-component {
  /* Declarative naming.
     Allows more flexibility in how
     it applies to the component. */
  --color-secondary: gold;
}

Avoid directly aliasing CSS values

Unless the CSS library is fully down the utility-first rabbit hole, my advice is that it’s generally not a good idea to force consumers to use a library API as an alias for plain CSS.

example-component {
  /* Arguably more utility is lost than
     gained by using a library value over
     just writing 0.75rem. */
  font-size: var(--ln-fontSize-0_75rem);
}

example-component {
  /* This API name is more useful because
     it can hold a different value depending
     on context. */
  font-size: var(--ln-fontSize-caption);
}

Above example uses ln short for “Library Name” as a sample library-specific namespace. A project like Spectrum CSS might use sp, Tailwind tw, etc.

Enforce a maximum number of hyphens

An easy way to improve a style API is to make it more readable. We like kebab-casing in CSS names but a long string of kebab-cased words can be difficult to parse at glance, especially when a namespace is involved and the semantics come midway into the name.

In my opinion, custom property APIs are a lot easier to follow with a fixed number of hyphens (and camel-casing in-between) to enforce structure and meaning in predictable places.

:root {
  /* Harder to scan: */
  --ln-control-accent-color: blue;
  --ln-focus-ring-color: cadetBlue;
  --ln-label-color-quaternary: lightGray;
  --ln-heading-title-font-size: 1.5rem;
  --ln-subheading-font-size: 1.2rem;
  --ln-caption-font-size: 0.65rem;

  /* Easier to scan: */
  --ln-color-controlAccent: blue;
  --ln-color-focusRing: cadetBlue;
  --ln-color-labelQuaternary: lightGray;
  --ln-fontSize-headingTitle: 1.5rem;
  --ln-fontSize-subheading: 1.2rem;
  --ln-fontSize-caption: 0.65rem;
}

Above example uses ln short for "Library Name" as a sample library-specific namespace.

Both of these groupings hold the same token name but, in my opinion, one is faster to read than the other.

I’ve been referring to this specific use of two hyphens above (conforming to <namespace>-<valueType>-<valueName>) as triptych notation, which is a riff on Hungarian notation.

Shadow parts

You might have noticed I didn't address shadow parts above. My thoughts on all of this are still evolving and on the ::part pseudo-element especially. I haven’t played with this feature enough yet to have an opinion on how best to use it.

My current thinking is that shadow parts seem best fit for components that are intended to be aggressively restyled, but I wonder how useful it actually is in practice since it seems like you’d run into a similar API scaling problem of 'well if that’s a part, this other thing should be a part also' until the entire component might as well just be in the light DOM.

Wrapping up

Hopefully you found some of my thinking above useful! As always, I'd love to hear from you and continue the discussions using the links in the footer.

If you enjoyed this, check out my previous article on Naming CSS Variables, which explores many of these same topics from a more general perspective, and this one on HTML Interfaces, which gives suggestions around ways component libraries can interact with CSS theming using HTML.

Jonathan Dallas

HTML Interfaces For CSS Libraries

Avoid using the class attribute as API

Use library-specific namespacing

Decide if the library will style tag names or only attributes

Consider making namespace secondary to API name

Wrapping up

Naming Variables In CSS

Casing

Maybe camelCase isn't so bad

Consider mixing kebab-casing with camelCasing

Namespacing

Value typing

Names that are descriptive

Where to use value-based naming

Color palettes

Where to use usage-based naming

Dark mode is simpler with usage-based variables

Levels of hierarchy within usage-based variables

Wrapping up

Nested Dark Mode Via CSS Proximity

Nested theming

CSS selectors don't consider proximity

Inheritance

Proximity is a feature of inheritance

Custom properties always inherit by default

Using proximity for nested dark mode

The inherit keyword

Further reading

Style APIs As A Last Resort

What is a style API?

All APIs have a cost

Let’s talk about Shadow DOM

Reconsidering styling across the shadow boundary

The inherit keyword

The currentColor keyword

Font relative units

Container and media queries

Bringing it together

When creating style APIs

Consider again whether the API is still needed

Avoid directly aliasing CSS properties

Avoid directly aliasing CSS values

Enforce a maximum number of hyphens

Shadow parts

Wrapping up

The `inherit` keyword

The `currentColor` keyword