Declarative Custom Elements in a nutshell

As of yesterday, the Declarative Shadow DOM is now available in all browsers with its addition to Firefox. This is great. The Shadow DOM is no longer restricted to JavaScript. This declarative form is still quite limited. It mostly serves as a way to either avoid the dreaded flash of unstyled content and to do less work with JavaScript. It does nothing to actually define a custom element and further if you were to use this to server render all of your custom elements that use the Shadow DOM, it would mean you need to include all the CSS in each tag (or use a <link> tag which can be problematic, or so I’ve heard).

Enter Declarative Custom Elements. It’s a proposed way to declaratively define a custom element without JavaScript in your HTML. This would ultimately mean that you could use your custom elements without needing to server render their individual content and they would work in a limited way. You would still need JavaScript for a whole lot of functionality, but a lot of the work you might do to set up a custom element’s shadow root (i.e. the markup and styles) would be taken care of.

I’m not going to get into how this relates to HTML modules or anything like that—I don’t fully understand it and it’s not relevant. What I want to focus on is syntax we use to spell out these definitions.

Do we use an HTML/XML like syntax to do this?

When we think declarative and custom elements, immediately we jump to using HTML (or an XML-like) syntax to achieve this. This would require a significant extension of HTML. Further, are the ergonomics of HTML or XML up to the task? Are we selling what we could do with a JavaScript-free solution short?

Now, before someone brings up XSLT—yes, I know that exists, but please try to entertain what I’m saying, otherwise, close this tab.

Let’s talk about styling

Wait, what does styling have to do with this? Well, nothing really. I do think it’s worth exploring how CSS solved issues of styling HTML.

As the kids say, in the late 20th century, you could style your HTML was with attributes and even elements. There was a <font> element. There was a <center> element. There were color, bgcolor, align, rightmargin attributes. All deprecated now, but when I was first learning web development in the mid-2000s some of these were still in use and as a beginner reading outdated resources, I even used some until I realized the power of CSS (and browsers deprecated them).

Anyway, using attributes and elements for styling was very limiting. CSS changed that by separating the concern of styling which meant that you could use the same rules for different markup without modifying the markup in every place it was used.

What If we used a different declarative option?

I think that a CSS-like syntax (read: not for styling) could be useful for creating element definitions as the problem that CSS solves for styling HTML seems strikingly similar to the problem of setting up a shadow root for a custom element. Yes, CSS can’t create elements. What CSS is great at matching selectors to a list of properties, which makes it helpful for solving the issue of setting the values of attributes in a dynamic way.

What this could look like? An Example…

Something I always test when using a templating language is how easy it is to create a navigation link that can indicate it’s the current page. I usually don’t create custom elements for these, since I don’t want them to require JavaScript. But if there were a way to do that declaratively, then I might entertain using an API like this:

<nav-link to="/">Home</nav-link>
<nav-link to="/about">About</nav-link>
<nav-link to="/contact">Contact</nav-link>

Underneath, I’d want these to translate to something like:

<a href="/" aria-current="page" part="link">Home</a>

And give me a declarative selector to style it with:

nav-link:state(current)::part(link) {
	background-color: DeepPink;
	color: Black;
}

Here’s how I think this could look:

<!-- This builds off the existing declarative shadow DOM syntax -->
<template defines="nav-link" shadowrootmode="open">
	<!-- Our template’s base markup. -->
	<a part="link"><slot></slot></a>

	<!--
		I want to indicate that these styles should be an adopted stylesheet
		rather than included along with the markup of every shadow root.
	-->
	<style adopted>
		a[aria-current="page"] {
			text-decoration: none;
			color: inherit;
		}
	</style>

	<!--
		I’m using a style tag here for *just* syntax highlighting.
		For the love all things good: this is not for styling though.
	-->
	<style internals>
		/* The syntax is still CSS-like though even though its not for styling */

		@attribute to {
			syntax: "<url>";
			initial-value: none;
			observed: true;
      /* Perhaps there could be a global registery for attributes these too that works with a custom attributes registry. */
		}

		a {
			/* Since the `to` attribute is observed, this is now bound. */
			href: host-attribute(to);
		}

		/* This works like a container style query */
		@host attribute(to: location.path) {
			:host {
				/* Maybe you could set element’s custom state (i.e. `nav-link:state(current)`)  */
				state-set: current;
			}

			/* Most importantly, you could use this to set attributes for other elements in your shadow root */
			a {
				aria-current: page;
			}
		}

    /*
      Perhaps you could even use `@media` here too to have media query
      specific rules (it maps to `window.matchMedia`, right?)
    */
	</style>
</template>

As you can see, the idea is to use an additional tag, perhaps <internals> to declaratively bind the host element’s attributes to attributes for elements within the shadow root and the element’s custom state (i.e. CSS Custom State also known by its JavaScript API name CustomStateSet). Since CSS has a number of features like media queries or container queries, some form of these could be helpful for describing what should happen when an custom element is in a particular state.

Why?

You might wonder, why do this with a CSS-like language? Isn’t the point of not using JS so that we can do this HTML? If we’re going to do it with a CSS-like language, why don’t we just use JavaScript?

The main reason is that there are a lot more API overlaps between CSS and JavaScript. I don’t think it makes sense to recreate all of those in HTML. Our declarative custom elements aren’t going to be expressive as they could otherwise be, but why limit ourselves to what can be expressed with HTML or XML.

CSS syntax is already familiar and developers already understand its selectors. They even use them with their JavaScript.

CSS has limits that JavaScript does not. It can’t do quite as much as JavaScript can do. This makes it more ideal than running JavaScript.

So, why not fork off of something that’s already declarative, albeit limited in what it can do (that’s a positive for this situation, because JavaScript is heavy and can maybe do too much). The two languages: this custom element defintion language and CSS could be mutually beneficial to each other as well as each grows as well.

Closing words

Anyway, that’s my two cents. Let me know what you think. Or don’t.

This small, personal website is the farthest thing from a large product. I intentionally embrace its nature as something that’s small in scale. This manifests itself in a few ways:

• As of writing this, there is no JavaScript. Not because I don’t want there to be or because I hate JavaScript or something. While I certainly am a bonafide member of the Anti-JavaScript JavaScript Club, that means I like to use it when I need it. So far I haven’t found a use for it, but that doesn’t mean that I won’t. I do know that when I do, I will have am equitable alternative for those who do not have JavaScript enabled.
• I don’t use a CSS build process or any pre-processor or any framework for that matter. If you look close, you’ll realize that sometimes there actually no rhyme or reason to the way that I’ve organized my CSS, in some places it’s messy, and there’s likely some dead code. My younger self would be grimacing.
• I often hold off on implementing features that might seem relatively easy to implement (namely with JavaScript alone) as I don’t see them as absolutely necessary or I’m not interested in doing a half-assed job.

So, if I’ve embraced being small, why am I using a larger product pattern like feature flags? Well, it’s actually because I am small.

I often don’t have tonne of time to work on this website. That can make more ambitious projects harder to tackle. Sometimes, I’ll be in the middle of working on something, then life happens and I can’t return to it for a week or even longer. It can be really easy to forget what I was doing or sometimes I’ll have something pressing that I need to change or do. In those latter situations, I’ll stash or revert those working changes into oblivion.

Since this website isn’t just a home for the words I write, but is something that I use to learn and refine my skills as a web developer, I’m generally not working with deadlines and am more willing to take the time to get things right. The balance between being a perfectionist, but also someone who explores is hard to navigate—it can easily lead to accomplishing nothing. Something else to balance is keeping this thing working so that I can write.

A few months ago I realized I could use a “development flag” to maintain my progress on features I was working on and while continuing to push the website forward in other ways. After doing this for a little while, I realized that it might be beneficial to expose some of those work-in-progress bits to others for feedback and as a way of working in public.

Doing this allows me to take some risks I usually wouldn’t for the sake of preserving a working mainline experience. I can still preserve the that experience while exploring new features that won’t diverge from each other through stale branches or forgotten stashes. In some cases, I can explore techniques or web platform features that won’t be ready for a few years.

So, if you’re interested, I only have a couple small features at the moment. Any feedback on their implementation is appreciated. I’ll be adding some more experimental features in the future.

I’m wondering if the “burden of HTML structure” is greatly exaggerated due to practices like BEM.

In my opinion, it’s not so much writing the HTML, it’s wiring up all the classes correctly that makes it burdensome. The class names aren’t there so much to tell you what things are—that’s a nice benefit—but since they are technically necessary to tame the cascade. When the technical need for those class names is removed (i.e. using @scope) is the apparent need for templating still as strong?

Don’t get me wrong, I think templating is great, I’m just wondering if we overplay its need when some of the underlying problems are being solved by other means.

1. Elements within a shadow tree are isolated and cannot be selected by styles set outside of the tree.

2. Styles set for the shadow tree are scoped to the elements within the tree.

How can styles cross the shadow boundary?

Now, there are a few ways that styles can cross the boundary between the shadow tree and its outside context (known as the host’s context):

1. Inheritance: the host element of the shadow tree is not within the tree (surprise!). This means that it can be selected from the outside and be styled in that way. The shadow tree inherits its styles from the host element. This means that any property that inherits will inherit from the outside context. Some properties such as font-family or color inherit by default for many elements. Unregistered custom properties do this as well. People often refer to this as “piercing the Shadow DOM.”

2. The :host pseudo-class and :host() pseudo-class function can be used to select the host element from inside the shadow tree. You can use the function to conditionally apply styles to elements within the tree when the host matches a particular selector.

3. This selector is likely being dropped from the spec: the :host-context() pseudo-class can be used to apply styles to the host element or to elements within the tree when the host is used in a specific context. The function matches an ancestor with a simple selector.

4. The ::slotted() pseudo-element function allows us to select slotted elements from the host element’s light tree. Those elements are still subject to the styles of the host’s context. The shadow tree’s styles are cascaded before the host context’s styles and so any styles set with ::slotted() will be weaker than those other styles. The only way to “win” this fight is !important and that completely blocks styling from outside the shadow tree for whatever property it’s applied to.

   • Instead of inheriting directly from the host, slotted elements inherit from the slot element they are assigned to. That slot element being a part of the shadow tree, eventually does inherit from the host element, but this is just one thing to keep in mind.

5. The ::part() pseudo-element function allows the host’s context to select elements denoted as CSS parts using the part attribute in the shadow tree. Again, since the shadow tree’s styles are cascaded before the host’s context, the host’s context styles will win unless the !important flag is used on the styles within the shadow tree.

   • Again, remember inheritance: since a part is what its children inherit from, applying styles with the ::part() selector is one way you can indirectly style elements within a shadow tree.

Limitations of styling the Shadow DOM

Due to their nature of being cascaded before the host context’s styles, (which is directly after the user agent and user styles), styles set for a shadow tree cannot share styles with other shadow trees. This can be quite frustrating as it’s often desirable to reset elements or to provide some default elements for a document that one might want to be used even within the shadow tree.

Another apparent limitation is the the weakness of Shadow DOM styles in situations where styles are allowed to cross the boundary. For better or for worse, we have a generation of web developers who have to conditioned to think !important is bad (and often, rightly so) which causes them to miss out on its usefulness in this scenario.

Lastly, for slotted elements and for parts, the corresponding selectors only allow selecting the elements themselves and not their descendants. This can be extremely limiting, especially for form related elements which often require certain nested structures.

So, what do we do? The Shadow DOM is our only avenue for style encapsulation, right?

Style encapsulation without the Shadow DOM

While there have always been ways of “encapsulating styles” in CSS, none of them have been quite the same as how the Shadow DOM works. Complex selectors can be used to “scope styles” to an ancestor. That falls short when multiple ancestors target the same elements: it becomes a battle of the cascade and specificity.

Using cascade layers to isolate our styles

Cascade layers can be used to effectively isolate our styles from the rest of the document’s styles. Remember, a shadow root’s styles are cascaded right after the user-agent and user styles. If we put our component’s styles in the first cascade layer of a document, then we’ve got the same environment for our styles.

@layer components;

@layer components {
	icon-button button {
		/* Button styles */
	}
}

But, that’s not quite all since styles in subsequent layers can still select our elements. Remember, how !important works in the Shadow DOM? We can use that the same way here. Using !important in a layer will prevent subsequent layers from styling whatever property of the element we apply it to.

@layer components;

@layer components {
	icon-button button {
		color: DeepPink !important;
	}
}

icon-button button {
	color: Wheat !important; /* important for good measure */
}

Now it can be quite tedious to apply this to every single property we’ve set a value for. We can make use of a sub-layer to effectively make the child element of our component work as if they were an element in a shadow tree.

@layer components;

@layer components {
	icon-button button {
		@layer styles {
			color: DeepPink;
		}

		all: revert-layer !important;
	}
}

icon-button button {
	font-family: Comic Sans;
	color: Wheat !important; /* important for good measure */
}

What’s happening here is that we are reverting the “unlayered” styles of the components layer back to the previous layer. Unlayered styles come after layers, so in this case the previous layer of the “unlayered” styles of the components layer is its styles sub-layer (i.e. components.styles). That’s all a bit hard to understand without a visual, so here’s the order of the layers in our example:

1. components

   1. styles
      • This is the previous layer (i.e. what the styles are being reverted to).
   2. unlayered
      • revert-layer is applied on this sub-layer.

2. unlayered

Using !important in tandem with revert-layer prevents all subsequent layers from styling whatever property it was set on. And since we used the all selector, that means everything except custom properties and some internationalization related properties.

Now that might seem heavy handed, but what we’ve got the basis for is practically the same as what we get with the Shadow DOM. Use all: revert-layer !important for any element that you want to consider “within the shadow tree” and therefore isolated from selection outside the tree. Elements without the rule will work the same as slotted or CSS part elements work. The only difference is that we have one tree and not two, which honestly is easier to reckon with.

Improving our scoping with @scope

Since we are still partly encapsulating our styles with a complex selector, we still have the cascade and specificity to deal with in the components layer. In practice this means we might have difficulty composing two components that target the same descendant. Whatever comes later in the cascade—provided they have equal specificity—will win.

The @scope rule is still being implemented in browsers. As I write this, Chromium browsers are the only browsers which have it in stable and it is available through a flag in Safari Technology Preview.

@layer components {
	@scope (icon-button) {
		button {
			@layer styles {
				aspect-ratio: 1;
				border-radius: 9999px;
			}

			all: revert-layer !important;
		}
	}

	@scope (toggle-button) {
		button {
			@layer styles {
				border-radius: 0.5rem;
			}

			all: revert-layer !important;
		}
	}
}

Now whichever element is closer in scope to the shared descendant will have its styles take precedent. For example, here the shape of the button will be a circle and not a squre with rounded corners since icon-button is closer in scope:

<toggle-button>
	<icon-button>
		<button aria-label="Dark Mode" type="button" aria-pressed="false">
			<darkmode-icon></darkmode-icon>
		</button>
	</icon-button>
</toggle-button>

Solving the shortcomings of Shadow DOM styles

Earlier, we listed some issues we had with Shadow DOM styling. So far, since we’re using a single tree for our elements, we don’t have the problem of not being able to select the descendants of slots or parts.

The problem of “weak” styles still remain for our new “slotted” or “part” elements (i.e. those which aren’t heavy-handedly preventing styling from subsequent layers), however, there is something we can do which might make that a non-issue—and which could make you consider applying that heavy handed approach to all the elements within these types of components. We have control over which layer we’ve set these styles in, so we can include a layer of shared styles which can serve as a basis for all our components. So instead of setting these styles in the first layer, we could include a reset or defaults layer before that.

How to remain extensible

In the past, I’ve written that when you write web components, you should do so in an extensible manner and that means leveraging slots and parts as a default. What I am suggesting here seems to run against that advice.

The difference here is that since we are in the “Light DOM”, the need for slots/parts to remain extensible doesn’t exist because we’re not working with a tree that is off limits.

Further, since we can allow layers before our components layer to style elements in our component’s tree, we have a new door to allow our elements to be extensible that doesn’t currently exist with the Shadow DOM (see the “open-stylable” proposal to see a discussion about changing this).

There’s one more way that we can allow for modification.

Declarative custom property APIs

With the advent of Cascade Layers, we can use !important to narrow down the available CSS API for elements. Doing so feels kind of wrong—like you are taking something away—but there is an opportunity to be generous. That generosity comes in the form of custom properties.

We can use custom properties to provide a constrained way of modifying our components. Design system implementors can set the rules for modification.

Styling through custom attributes

Another way we can allow for modification is with custom attributes. This technique is nothing new. It allows consumers to be more declarative with saying what they want.

@layer components {
	@scope (icon-button) {
		:where(&) {
			--shape: circle;
		}

		:scope {
			container: icon-button;
		}

		button {
			@layer styles {
				aspect-ratio: 1;
				border-radius: 9999px; /* Defaults to a circle */

				:where([shape="circle"]) & {
					border-radius: 9999px;
				}
				:where([shape="square"]) & {
					border-radius: 0;
				}
			}

			all: revert-layer !important;
		}
	}
}

The downside here is that this is an HTML API and not a CSS API. Some might prefer that, but I personally think that a CSS API is more powerful since it allows other elements to change the styling of your element without the help of JS.

Better custom properties with style queries

Style queries allow us to query a custom property value set on a container. Currently, this is only available in Chromium (in stable). We can use style queries to provide even better custom properties—custom properties that are more declarative in regard to their values. (And we can keep the HTML API too!)

@layer components {
	@scope (icon-button) {
		:scope { container: icon-button; }

		/* We need to set these values weakly so other elements can override them their own CSS */
		:where(&) { --shape: circle; }
		:where([shape="square"]) { --shape: square; }

		button {
			@layer styles {
				aspect-ratio: 1;

				/* Set the shape */
				@container icon-button style(--shape: circle) {
					border-radius: 9999px;
				}
				@container icon-button style(--shape: square) {
					border-radius: 0;
				}
			}

			all: revert-layer !important;
		}
	}
}

What should this be used for?

You might be looking at this code and be thinking: “that all seems impractical” or that’s a lot of boilerplate. I agree and I disagree. I don’t think this is how you should write all of your styles. It does however work quite well for a design system or for shared components. You probably aren’t introducing new components every day and so the amount of times you’d need to employ this pattern are few and far between.

If you wanted to colocate these styles with a web component, you can easy do so with document.adoptedStyleSheets. The nice thing about the scoped rule is that it doesn’t matter so much the order you insert the styles into your components layer. You could even make the layer the styles get inserted into configurable.

Could this be the future of encapsulated component styles?

By not using the Shadow DOM, we actually have a better styling experience for our components when we leverage Cascade Layers, the forthcoming @scope rule, and style queries. And we might need to rethink our relationship with the notorious !important flag.

Yes, the Shadow DOM allows for templating and that’s not something we can do in the Light DOM yet, but it could still be on the horizon. If you’re already building Web Components that already don’t use the Shadow DOM, this approach can fill the desire you might have for encapsulated styling.

Again, this technique uses features that aren’t available broadly yet, but could this be the future?

In 2024, I’d love to see the following implemented in all browsers:

1. Style queries for custom properties

These are going to revolutionize how we write component styles. One significant use-case is allowing you to create your own custom-CSS-API for a component—I’ll write more on this in the future.

2. text-box-trim and margin-trim

These aren’t the same, but I’ve grouped them together because they are just so useful for typography. I recently created a printed document and I used Safari Technology Preview just so I could use both of these. They seem like low hanging fruit for implementation.

3. The @scope rule

So much of the styles we write are candidate for the CSS @scope rule. Miriam Suzanne has a fantastic article about this. Also, scope proximity is fascinating!

4. Scroll-driven animations

I work on websites that use scroll animations all over the place. Being able to do these all with CSS would be awesome and there are so many other use cases for them beyond just your typical scrolly-telling sites.

5. Types for attr()

Using attribute values for properties other than content would be great. This goes hand-in-hand with style queries and will greatly improve how we write component styles.

6. Anchor positioning

While I haven’t been following this too closely, the fact that there is work being done here is fantastic and makes me excited for its implementation across browsers. I’m elated to see all that we can now achieve without JS that is also accessible.

7. View transitions

View transitions are magical and I really do hope we see more progress here towards stable implementation.

Thank you CSS wish fulfillers

I want to end this by expressing gratitude for everyone involved in the process of making these CSS wishes come true. Whether you are working on specifications, research, implementation, experimenting, or offering feedback—I am so grateful for you and your work. You make the web a better place. Thank you!

Shadow DOM styles are cascaded before the document styles

Crucial to writing styles for the Shadow DOM is understanding where they fit in the cascade. It’s common to understand Shadow DOM styles as something that gets cascaded after a document’s styles, but that’s not the case. Styles written for the Shadow DOM are cascaded after the user agent and user styles. Document styles or those in the custom element’s host context override the styles you set in the Shadow DOM—not the other way around. This is why Shadow DOM styles appear to be weak which makes them similar to user agent styles. Here’s a simplified ordering of the cascade:

1. User agent styles
2. User styles (i.e. styles which relate to user preferences like font size, etc.)
3. Shadow context styles (including layers)
4. Document or light context styles (including layers)
5. Inline styles

For a more in-depth overview of the cascade, I recommend reading Miriam Suzanne’s “A Complete Guide to CSS Cascade Layers.”

The apparent weakness of shadow styles is actually their strength—it’s what allows your custom element to remain extensible. With that being said, there are cases where one might need their shadow styles to prevail over those of the document. Let’s revisit a friend whose got a bad reputation.

Using !important for its actual purpose

The !important flag has a long history of abuse, so much so that we would never consider using it a good practice, would we? This is something that we need to rethink as we become the authors of custom elements.

!important allows us to denote what styles are so important about our custom element’s shadow styles that they should not be changed by consumers. Using !important with a shadow CSS rule for the shadow host, a slotted element, or CSS parts will prevent that rule from being changed in the host’s context.

Once we understand that our shadow styles act more like a user agent stylesheet where their weakness is a strength and that we can reclaim !important for its proper use, we’re ready to write Shadow DOM styles for our custom elements.

Set good defaults and embrace extensibility

I’ve often seen the advice to not write styles for slotted elements at all (i.e. using the ::slotted() selector) and I don’t think that’s good advice. With this mental model I’ve presented above, I hope you can see your shadow styles are more about providing a good usable default that is designed to be overridden or extended. Embrace the use of slots and parts in your custom element designs, and don’t be afraid to style them.

Great styles will help communicate what affordances a custom element provides. For example, if you have a custom element that decorates a <button> element as a toggle button using the aria-pressed attribute, provide shadow styles for both of those states:

::slotted(button[aria-pressed="true"]) {
  /* Styles for when the button is pressed */
}

::slotted(button[aria-pressed="false"]) {
  /* Styles for when the button isn’t pressed */
}

If there’s only one ways an affordance can be visually communicated, you can use !important to ensure that isn’t overridden. You can even use !important on a rule, but use custom properties to allow for more constrained modification of the rule.

Resetting a custom element’s shadow styles is very easy

Maybe you think these default styles just introduce extra work for the consumer to override? Well, it’s actually not very difficult to revert all of the shadow styles for an element.

Say we have a slotted button that has some default styles from the Shadow DOM. We can target the element and set all: revert and sure enough we’re back to the user agent styles for that element. The one exception is those styles that we’ve deemed important with the !important flag. I hope you can see this as a positive. We’ve got an incredible way of resetting an element while still respecting what’s vital to it. Reset without fear! Check out this pen of resetting shadow styles in action or see a reduced example of it below:

<style>
	toggle-button button {
		all: revert;
	}
</style>
<toggle-button>
	<!-- Using the Declarative Shadow DOM for visualizing the example -->>
	<template shadowrootmode="open">
		<style>
			::slotted(button) {
				/* Will be overridden by revert */
				font-family: system-ui;
				font-weight: 600;
				font-size: 1em;
				padding: 0.5em;
				border-radius: 0.5em;
			}

			/* The following will not be overridden by revert (but provides some ability to be modified) */

			::slotted(button) {
				border: 0.125em solid var(--color-foreground) !important;

				/* Custom properties are not included in `all`, so these are safe. */
				--color-foreground: DeepPink;
				--color-background: White;
			}

			::slotted(button[aria-pressed="true"]) {
				background-color: var(--color-foreground) !important;
				color: var(--color-background) !important;
			}

			::slotted(button[aria-pressed="false"]) {
				background-color: var(--color-background) !important;
				color: var(--color-foreground) !important;
			}
		</style>
		<slot name="button"></slot>
	</template>
	<button slot="button" type="button" aria-pressed="true">Dark Mode</button>
</toggle-button>

But what about design system components?

A popular use case for custom elements is implementing a library of design system components. The mental model I’ve presented above works really well for introducing new UI primitives where extensibility is vital for reusability. Design system components don’t allow for such free-handed extensibility: visual design constraints are crucial. Is this use case at odds with the mental model? I don’t think so.

If you’re using the Shadow DOM at all, understanding it how I’ve explained will serve you. It might even help you identify when you’ve got a bad expectation of it and steer you towards a more appropriate solution. I’ve got some techniques that I’ll share in a future post for how to use the Shadow DOM to enforce design constraints while allowing the use of slots and parts—and what’s even greater news is that some of the techniques don’t even require the Shadow DOM at all. You can have Shadow DOM like isolation in the Light DOM. Stay tuned…

It doesn’t take long for the euphoria to wear off. Often it’s replaced with confusion when people begin to introduce features like slots into their components. “What do you mean, the Light DOM styles take precedence over the Shadow DOM styles? I thought it was supposed to be the opposite?” It’s also scandalizing for some to discover that, yes, CSS properties do inherit through a shadow root boundary and this is true for (unregistered) custom properties whose default behaviour is to inherit their value. This only ends up coming across that the Shadow DOM isn’t real encapsulation. Something with our mental model of Web Components isn’t quite right.

Starting with styling the Shadow DOM is a misstep

As I was watching and participating in numerous conversations about Web Components take place over the last few days, when Robin Rendle pointed out that “Folks start with styles first[…]” it made me realize the starting with styles is indicative of our misunderstanding of what Web Components are and where to start when we build them.

The focus on isolated, scoped styles creates a sense that Web Components are meant to be closed off as a default. To be frank, this is against the grain they were built. We might as drop the “Web” from Web Components if this is what we expect.

In reality, the way that features like slots work (i.e. the CSS ::slotted() selector used for styling slotted Light DOM content from the Shadow DOM), having less precedence over the styles for the actual slotted Light DOM content, and the same for CSS Parts used to expose elements from the Shadow DOM for styling outside, show us that Web Components were designed for extension.

The web is extensible

Extensibility is an underlying principle of the web. Web Components do not deviate from this principle. Features like slots and CSS parts should be embraced when using the Shadow DOM. Why? Because they empower the extension of what is already there and they allow the extension of what they introduce.

Often, the impulse I see in people (myself included) in building Web Components is to move chunks of their markup and styles to the Shadow DOM. Doing this closes off that markup and those styles from extension. This is a choice that will get us in loads of trouble. Not only is that content inaccessible without the use of JavaScript, potentially fraught with technical and accessibility bugs, but now we’ve limited its ability to extend the existing Light DOM and to be extended with CSS.

Our approach to Web Components should be one that is open by default. We should embrace extensibility in our designs and build with the rule of least power in mind. I think in practice this means adopting approaches like progressive enhancement. When this is our approach, we realize that the Light DOM is where we should start and that it serves as valuable foundation to extend.

Conclusion

Now, I hope that I haven’t come across as being dismissive of the Shadow DOM. I actually think it’s pretty great, but what I hope I’ve done, is highlight that when it’s the first and only thing we focus on for Web Components, we actually misunderstand how to use it and it’s purpose.

In the future, I’ll expand on my thoughts of how to best understand writing styles for the Shadow DOM that lead to a more extensible web. I think understanding Web Components as being extensible makes styling the Shadow DOM make a lot of sense.

Today, I encourage you to get started with Web Components. Start with the most humble and least powerful thing: a custom element—no CSS or JavaScript required (though, a different display property might be a good idea).

At the end of the day, it’s just me using this thing, so why does it matter that I build this according to such a high standard? I don’t need assistive technology to use the web. I am also privileged with fast Internet and usage limits that I generally don’t exceed. I could do so much more and so much faster if I just built for myself and my own needs today.

But who I am today is not promised for tomorrow. I don’t know who I am tomorrow. I don’t want what I build to be bound to who I am today. My life could radically change between today and tomorrow.

I hope the me of tomorrow whether that be (literally) the day after today or decades from now appreciates how I chose to build today. That is why I strive for such high ideals.

A little backstory behind these musings: I recently built a CLI for publishing and updating posts on this website. It’s very geared towards my current workflow and what I currently like to use. Right now, I’m quite at home in the terminal and I love using Neovim for writing and editing text. This tool is quite effective and it made me question my whole endeavour of building a CMS especially one with such high standards.

I’ve had enough times in my life that have completely altered how I did things—if not forever, then just for a season. There were things that I left behind as they could no longer serve me where I found myself. Some of those things were great things.

I don’t want that to be the case for this website. The beauty of the web is that it isn’t static. It’s flexible and it adapts to whatever situation it finds itself in. I love this about it and I want to tap into that for this website. Embracing this is how I build for myself tomorrow: the me that I don’t know (yet).

The first stage is expanding your vocabulary beyond using <div>, <span>, and other special elements (e.g. <a>, <button>, <input>, etc.). Often at this stage, HTML authors will tap into a wider vocabulary of elements, but use them as it makes sense to them. For example, I’ve seen card elements created like this:

<section class="card">
	<header></header>
	<main></main>
	<footer></footer>
</section>

While this might make a bit more sense to the person who wrote the code—this is a misuse of semantics, which leads me to the second stage…

The second stage is understanding the semantics of the elements beyond their tag name. This means understanding what ARIA role they map to. For example, while some are straightforward like the <main> element having the role of main, others are a bit different, like the <header> element mapping to the banner role or the <footer> element mapping to the contentinfo role.

The third is similar to the second and perhaps could be understood as the second learned correctly. The third stage is understanding that the context an element is used in affects its meaning. So for that last example: the <header> element maps to the banner role and the <footer> element maps to the contentinfo role—that is only true if they’re used in a specific context.

The following are two common examples where the <header> and <footer> elements would not have any corresponding ARIA role since they’re being used as a descendant of the <main> element or a sectioning content element (i.e. article, section, nav, aside).

<body>
	<main>
		<header></header>
		<footer></footer>
	</main>
</body>

<body>
	<article>
		<header></header>
		<footer></footer>
	</article>
</body>

In the next example, the <header> and <footer> elements are direct descendants of the <body> element and therefore have their respective banner and contentinfo roles.

<body>
	<header></header>
	<main></main>
	<footer></footer>
</body>

This doesn’t mean that your <header> or <footer> elements must be at the top-level as direct descedants of the <body> element. You can wrap them in a <div> element (or layers of <div> elements).

<body>
	<div>
		<header></header>
		<main></main>
		<footer></footer>
	</div>
</body>

Also, this doesn’t mean that you shouldn’t use <header> or <footer> within sectioning elements. Just make sure you’re not expecting them to do anymore than be a slight improvement of the developer experience over using <div>. Their more forgiving nature lends them to be helpful for that use unlike an element like <main> which you should only use in its appropriate context.

Personally, I tend to avoid using those element outside of contexts where they have more semantic meaning, because I think it makes the HTML source more clear and it means I can be less specific when writing CSS (i.e. if there’s only one <header> element on the page, there isn’t going to be any conflict if I use a simple selector like the header type selector). Instead of using <div>, I might use a custom element name like article-header. If you do this, just keep in mind that you’ll likely want to assign a different CSS display value to these elements since the default is inline.

There’s a lot more that can be said on this topic, like if there is more than one <nav> element on a page they should have different accessible names or that <section> doesn’t really do much on its own (see Todd Libby’s article, “<section> is the new <div>” or Scott O’Hara’s article, “Accessibility of the section element”). I guess this is my invitation to you to look deeper into the meaning behind the elements we use and understand the real effects they have on people consuming the HTML documents we author.