Mixins

I want to be able to create presentational abstractions that only exist in CSS. “Wait,” you might say, “isn’t that how CSS already works?” While, yes, we do use CSS to create rules for various selectors, which can be seen as their own abstraction, those are dependant on the matching HTML. Today, there’s no real way to create a ruleset abstraction in CSS, unless you want to abuse @keyframes.

CSS Mixins would allow me to create a presentational abstraction, then apply it to multiple selectors throughout my stylesheet.

<style>
@mixin --button() {
	/* Button styles */
}

button {
	@apply --button();
}

.button {
	@apply --button();
}
</style>
<button>A real button</button>
<a href>A link that looks like a button</a>
<my-button>
	<template shadowrootmode=open>
		<style>
			:host {
				@apply --button();
			}
		</style>
	</template>
</my-button>

Currently, spec work for CSS Mixins has already begun and they have an early prototype in Chromium-based browsers.

Functions

I want to be able to include the algorithms that I use to create typescales, colour palettes, etc. directly in my CSS. I don’t want to need to use static custom properties for this. I want to be able to get the fifth step of my typescale with my own custom CSS function.

@function --my-typescale(--step <integer>) returns <length> {
	result: calc(var(--step) * 0.25rem);
}

@function --my-palette(
	--color type(indigo | blue | green),
	--step <integer>
) returns <color> {
	/* Complex colour palette logic */
}

.component {
	font-size: --my-typescale(5);
	color: --my-palette(indigo, 500);
}

Today, CSS functions are available in Chromium-based browsers.

The if() function

I want to be able to colocate all of the variations for a single property in one declaration rather than in different selectors, at-rules, etc.

@mixin --component() {
	font-size: --my-typescale(if(
		style(--component-size, large): 7;
		style(--component-size, small): 3;
		else: 5;
	));
	color: --my-palette(indigo, if(
		style(--component-state, hover): 300;
		style(--component-state, active): 700;
		else: 500;
	));
}

.component {
	@apply --component();

	&:hover {
		--component-state: hover;
	}

	&:active {
		--component-state: active;
	}
}

Today, the if() function is available in Chromium-based browsers.

A CSS-powered DSL for design systems

Features like these allow us to effectively create our own DSL (domain-specific language) for a design system.

Functions allow us to encode some of the algorithms behind our design decisions into our stylesheets. They ultimately can reduce the amount of custom properties that are necessary since they allow us to generate values using parameters.

Mixins allow us to create presentational abstractions that can be flexibly applied to many framework implementations and can even be used by consumers in ad hoc way where they previously might have either misapplied a component in a semantically inappropriate scenario or even fork styles to work for their own non-matching markup.

The if() function allows us to more powerfully leverage an element’s own custom properties and colocate similar rules, avoiding needing to deal with various selectors with differing specificity along the way.

A renewed separation of concerns

Empowering CSS in these ways makes it easier to keep markup concerns separate from presentational concerns. There will always need to be an implemenetation layer where presentation is matched to markup using selectors, but with these features, that layer will become much clearer and descriptive.

button {
	@apply --button();

	&[aria-expanded="true"] {
		--button-state: open;
	}
}

cta-button {
	@apply --button(large);

	&:state(open) {
		--button-state: open;
	}
}

Features that we have today, such as @scope reduce the need for complicated selector naming conventions or even highly specific complex/compound selectors. Paired with these new features, we can easily avoid needing to touch our markup to apply the styles, yet have maintainable styles that are descriptive.

@scope (body) to (main) {
	header :any-link {
		@apply --pill();
	}
}

With features like these, separation of concerns becomes much easier to achieve. Markup can describe our content’s semantics and CSS can describe presentation. We don’t need to endlessly come up with new class name conventions (whether human or machine readable) or tweak our favourite utility class generator with every new CSS feature that’s introduced.

Optimism and gratitude

It’s an exciting time to be writing CSS. It’s come a very long way from when I made my first web page twenty years ago. I’m grateful for those behind the scenes doing the hard work of both slugging away at bugs, optimizing performance, and coming up with new features. Cheers!

Top five albums

This year, I’ll just go through my top five, counting down. Beyond that is really hard to make up my mind.

5. Life is Violence by Idle Heirs

I love the dynamics and textures of this record. From the walls of sound to the slow western-y guitar bits—it’s a musical sweet spot for me. I returned to it a lot and I’m glad they released an instrumental version which was a staple for my writing sessions.

Favourite track: “Lemonade Stands”

4. I Don’t Want to See You in Heaven by The Callous Daoboys

What can I say? Ugga-ugga-boo, ugga-boo-boo-ugga?

Favourite track: “Idiot Temptation Force”

3. Are We All Angels by Scowl

This would be number one by a longshot if it were up to playtime alone. Indigo (6 years old) and I had this album on repeat constantly, singing along. It’s one of those special albums that will always remind me of this time in her life.

Favourite track: “B.A.B.E.”

2. SPINNER by EYES

I knew this album would be my favourite hardcore album of the year as soon as I heard it. Definitely darker than their previous two albums. I love how the album is both driving, but makes room to breathe. A certified spinner.

Favourite track: “Beelzebub, the Hypocrite”

1. Lonely People With Power by Deafheaven

For record that runs just over an hour, this one has me captivated the entire time and gives me chills throughout.

Favourite track: “Winona”

Honourable mentions

• Stray from the Path’s Clockworked
• Dying Wish’s Flesh Stays Together
• Rolo Tomassi’s In The Echoes Of All Dreams (EP)
• Counterparts’ Heaven Let Them Die (EP)
• Agriculture’s The Spiritual Sound
• Turnstile’s NEVER ENOUGH
• La Dispute’s No One Was Driving the Car
• Pile’s Sunshine and Balance Beams
• The Armed’s THE FUTURE IS HERE AND EVERYTHING NEEDS TO BE DESTROYED
• Between the Buried and Me’s The Blue Nowhere

Live shows

In February, I saw Meantime, Cancer Bats, Orthodox, and Comeback Kid for the latter’s 25th anniversary show in Winnipeg. This was Indigo’s first show. She had a blast, but we were playing Echoes of Wisdom on the Switch for all of the openers which was a very strange experience for me—also, sitting in a balcony at a hardcore show was weird, but comfortable. Then, shortly after, at the start of March, I travelled to Calgary to see Gouge Away and Chat Pile. I’m so happy Gouge Away played “Uproar.”.

In May, I saw Juice, Trench, Whispers, and SPEED in Winnipeg.

In October, as a way to celebrate my 30th birthday, I travelled to Birmingham, Alabama, to Furnace Fest where I saw Gideon, Pig Pen, Madball, Microwave, SPEED (again), Comeback Kid (again), DRAIN, Mom Jeans, Kublai Khan, Jimmy Eat World, Meadows, BIG ASS TRUCK I.E., As Cities Burn, Anberlin, Rolo Tomassi, Zao, Counterparts, Johnny Booth, Boundaries, XweaponX, Stray from the Path, Many Eyes, The Tony Danza Tapdance Extravaganza, Terror, Norma Jean, Converge, Emery, The Dillinger Escape Plan, and Knocked Loose. So… pretty much all of my favourite bands. It was amazing. Then a week later I saw 156/Silence, thrown, and Counterparts (again) in Winnipeg.

2026

I’m really looking forward to Converge’s new album, Love Is Not Enough. After seeing them at Furnace Fest and since they announced the new album, I’ve been listening to them non-stop. Outside of that, I’m actually not super aware of what else is coming in 2026. Maybe new Silent Planet? Norma Jean?

Caution: there is a significant bug in Safari and VoiceOver which make this pattern worth avoiding until it’s fixed. See the “Update: June 26, 2026” for more details.

Recently, I found myself needing to implement collapsible sections. For this particular use case, using <details> and <summary> elements was too much of a hassle because the CMS did not recognize them as elements and I don’t particularly like nesting headings within a <summary> element, since it makes discovering the expand and collapse trigger more difficult for those navigating by headings. So, I’m turning to the tried and true “Collapsible Sections” pattern.

I’ve used this pattern for accordion components in design systems, built custom elements with it, and used it for cases like this. Here’s what the markup generally looks like:

<section>
	<h2>
		<button id="section-0-trigger" aria-expanded="false" aria-controls="section-0-content">
			Hello, World!
		</button>
	</h2>
	<div id="section-0-content" hidden>Hideable content…</div>
</section>

The JavaScript for it is pretty simple as well:

// Simplified
button.addEventListener("click", () => {
	content.hidden = !content.hidden;
	button.ariaExpanded = content.hidden ? "false" : "true";
});

While implementing the pattern, I realized that rather than just using hidden as a boolean attribute on its own, I can use the newer until-found attribute-value, so that I could allow the contents of the disclosures to be searchable.

As of writing this, hidden=until-found is only available in Chrome and Firefox. Safari will likely include it in an upcoming release as it is currently available in their latest Technology Preview.

I’ve written on how to polyfill hidden=until-found earlier this year, but unfortunately that doesn’t work in Safari since there’s no good way to observe its “find-in-page” feature. I can still use hidden=until-found though, because it was designed with progressive enhancement in mind.

Unsupporting browsers will hide content visibly and accessibly for any value provided to the hidden attribute (bear in mind that the element property works differently when given boolean values). For those cases, hidden=until-found will work like hidden on its own, since the attribute is present.

Here’s our updated markup:

<section>
	<h2>
		<button id="section-0-trigger" aria-expanded="false" aria-controls="section-0-content">
			Hello, World!
		</button>
	</h2>
	<div id="section-0-content" hidden="until-found">Hideable, but searchable content…</div>
</section>

We’ll need to slightly adjust the JS to use until-found as the value for the attribute when collapsing. Since "until-found" is a truthy value in JavaScript, we’re relying on that both in the condition and when setting the property which sets a boolean in unsupported browsers.

button.addEventListener("click", () => {
	content.hidden = content.hidden ? false : "until-found";
	button.ariaExpanded = content.hidden ? "false" : "true";
});

Since the content can be expanded when it contains a match for a find-in-page query, I’ll need to listen for the beforematch event for the content, so that I can update the <button> element’s aria-expanded attribute value to reflect when the content is no longer hidden.

content.addEventListener("beforematch", () => {
	button.ariaExpanded = "true";
});

So, there you go: with not a whole lot of changes your collapsible sections are now searchable as a progressive enhancement.

Again, if <details> and <summary> elements are suitable use those instead — this is the first rule of ARIA usage. They have the same searchable benefit as hidden=until-found and you don’t need any extra HTML or JavaScript to get them working.

Demo

You can check out a live demo of a searchable, collapsible section below, but it likely will work better on a standalone page to avoid searching this parent document.

Update: June 26, 2026

I’ve become aware of a Safari/VoiceOver bug (Bug 310623) where if you programmatically remove hidden=until-found from an element the accessibility tree doesn’t seem to update to include the content. When content is matched with find-in-page, this doesn’t seem to be an issue. I don’t believe this would have been an issue when I wrote this article as I usually test pretty thoroughly with screen readers. Anyway, either avoid this pattern until that’s fixed or hopefully pressure WebKit to fix it, as the bug was opened three months ago and still doesn’t have a fix.

This reduces the boilerplate required by those using a custom element and it helps reduce its API which makes it more maintainable since the entire DOM tree isn’t public by default.

I’ve written about <slot> elements before focusing how the Web platform’s slotting works differently from other forms of slotting and pointing out that the <slot> element itself can be styled despite its user agent styles (i.e. display: contents). In this post, I’m going to talk about slot assignment and explore a lesser known feature of it.

The default named slot assignment

The default named slot assignment behaviour of a shadow tree is to assign an element’s child nodes (i.e. elements and text nodes) to a corresponding <slot> element.

Text nodes and element nodes without a slot attribute are assigned to the first unnamed slot.

<div>
	<!-- Declarative shadow DOM for visualization purposes only. Often this is set inside of the custom element definition. -->
	<template shadowrootmode=open>
		<slot></slot>
	</template>
	<span>I appear within the unnamed slot</span>
	I also appear within the unnamed slot.
</div>

Element nodes with a slot attribute are assigned to the corresponding named slots (i.e. <slot> elements with a name attribute).

<my-article>
	<!-- Declarative shadow DOM for visualization purposes only. Often this is set inside of the custom element definition. -->
	<template shadowrootmode=open>
		<hgroup>
			<slot name=title></slot>
			<slot name=subtitle></slot>
		</hgroup>
		<div class=article-content>
			<slot></slot>
		</div>
	</template>
	<h1 slot=title>Article title appears within the title slot</h1>
	<p slot=subtitle>Article subtitle appears within the subtitle slot</p>
	<p>Article content appears in the unnamed slot.</p>
	I also appear within the unnamed slot.
</my-article>

Nodes that do not have a corresponding slot whether named or unnamed are ignored.

<div>
	<!-- Declarative shadow DOM for visualization purposes only. Often this is set inside of the custom element definition. -->
	<template shadowrootmode=open>
		<slot name=content></slot>
	</template>
	<span slot=content>I appear within the named slot</span>
	I don’t appear anywhere.
</div>

As you can see, slots are very powerful. They enable composition. They allow for mixed-order rendering which is incredibly useful for HTML streaming (e.g. for an app use case you could send the “app shell” in the first chunk and then chunk over content as it becomes available).

Named slot assignment works well for many simple use cases.

What if you want to wrap each individual slotted node with an element within the shadow tree? What if you only want to accept certain types of nodes or elements? You might think this is impossible or maybe even a design flaw of the Shadow DOM, but it does provide a method to do this.

Enter manual slot assignment

Manual slot assignment allows you to decide how an element’s child nodes get slotted.

You enable this when first attaching the shadow tree:

element.attachShadow({
	mode: "open",
	slotAssignment: "manual",
});

Once enabled, child nodes will not be auto-assigned to any <slot> element inside of the the shadow tree. That responsibility is all yours.

Assigning to slots

Nodes are assigned to slot elements using the assign() method of the HTMLSlotElement interface. Only nodes that are direct children of a shadow host, can be assigned to slots within its shadow tree.

The assign() method takes an ordered list of nodes and will unassign any node previously assigned to the slot when called.

// 0. Attach the open shadow root with manual slot assignment enabled
element.attachShadow({ mode: "open", slotAssignment: "manual" });

// 1. Create a slot element and append it to the shadow root. 
const slot = document.createElement("slot");
element.shadowRoot.append(slot);

// 2. Find slottable nodes — must be either text or element nodes.
const slottables = Array.from(element.childNodes).filter(
	node => node.nodeType === Node.ELEMENT_NODE || node.nodeType === Node.TEXT_NODE
);

// 3. Assign the slottable nodes to the slot.
slot.assign(...slottables);

That’s the gist of how to assign nodes to a slot manually.

Accessing slotted nodes

There are two methods to accessing what’s assigned to a slot:

1. The assignedNodes() method which includes all assignable nodes (i.e. text and element nodes).
2. The assignedElements() method which only includes the element nodes.

Both of these methods also take an optional object of options with flatten as the only option currently available. This option defaults to false, but when set to true it will return the slot element’s children (i.e. the fallback content of the slot) if there is nothing assigned to it.

slot.assignedNodes({ flatten: true });

Practical use case: wrapping slotted elements

Say you have an element called <fruit-bowl>. This takes a list of fruit as direct child elements.

<fruit-bowl>
	<span>Apple</span>
	<span>Cherry</span>
	<span>Apricot</span>
	<span>Banana</span>
</fruit-bowl>

In the shadow tree, we have an <ul> element:

<!-- shadow tree content -->
<ul></ul>

Within that, each slotted fruit should be wrapped with an <li> element:

<li><slot></slot></li>

The resulting “composed tree” should look like this:

<!-- This is a composed tree: it does not represent the real DOM structure -->
<fruit-bowl>
	<ul>
		<li><slot><span>Apple</span></slot></li>
		<li><slot><span>Cherry</span></slot></li>
		<li><slot><span>Apricot</span></slot></li>
		<li><slot><span>Banana</span></slot></li>
	</ul>
</fruit-bowl>

When using manual slot assignment, MutationObservers are generally what you use to watch for changes of what’s slottable.

Generally, you’ll at least want a mutation observer that’s observing the shadow host’s light DOM children. In some cases, you might want an observer for the shadow tree as well.

It’s also important to be aware of at what point in the lifecycle of the document that the mutation observer has started. If it’s guaranteed that the observer has started early enough either as soon as the element is created or before its contents can be parsed, then there will be no need to check for existing slottable nodes. In other cases, it is necessary to check for existing slottable nodes when the element is connected (i.e. in custom elements check in the connectedCallback()).

To keep things simple, let’s assume the <fruit-bowl>’s custom element registration took place in a parser blocking way within the document’s <head>, so we don’t need to deal with any existing children. We’ll also only assume that the mutation observer is handling one entry at a time.

const slottableObserver = new MutationObserver((entries) => {
	const { childNodes, shadowRoot } = entries[0].target;

	// Reset the shadow root with an unordered list element.
	shadowRoot.innerHTML = "<ul>";
	const list = shadowRoot.querySelector("ul");

	for (const node of childNodes) {
		// Filter out non-elements
		if (node.nodeType !== Node.ELEMENT_NODE) continue;
		// Stub out the list item.
		const listItem = document.createElement("li");
		// Create and append a slot element within the list item.
		const slot = document.createElement("slot");
		listItem.append(slot);
		// Append to the connected list, so we can assign to it.
		list.append(listItem);
		// Assign the corresponding light DOM child element.
		slot.assign(node);
	}
});

customElements.define("fruit-bowl", class extends HTMLElement {
	constructor() {
		super();
		this.attachShadow({
			mode: "open",
			slotAssignment: "manual",
		});
		slottableObserver.observe(this, { childList: true });
	}
});

Now, whenever the element’s light DOM children change, our custom element will wrap any child elements within a list item within the shadow root — neat! Give it a try:

Obviously, this is incredibly unoptimized — and we’re not going to get into improving it — but it demonstrates the kind of composition that manual slot assignment allows.

Beyond simply wrapping nodes, manual slot assignment can be a great way to further reduce boilerplate in your custom element APIs, especially when dealing with sub-component relationships (e.g. consumers don’t need to explicitly assign elements with the slot attribute; optional wrapping elements can be omitted). You can implicitly assign elements to slots based on their DOM position or even use DOM position to provide different templates. You can filter out unsupported content.

Manual slot assignment is just another way that Web Components APIs and the Shadow DOM allow you to create custom elements that are like those already included in the platform.

content-visibility: hidden vs. hidden=until-found

On its own, content-visibility: hidden will cause an element’s content to be completely hidden. This means it’s skipped for rendering, ignored by assistive technologies, and not findable using “find-in-page” browser features. The until-found value of the hidden attribute keeps the content findable which makes sense given its name, but otherwise it works the same.

Something I’d like to underscore is that it’s the hidden=until-found attribute-value pairing that makes content findable — not content-visibility: hidden. This means that in browsers that don’t support hidden=until-found yet, we can’t use content-visibility: hidden as a part of a polyfill. So, how would one polyfill this feature?

Hiding content while remaining findable

Now, while content-visibility: hidden does not keep content findable, content-visibility: auto does and reflecting on this got me thinking: could it be possible to polyfill hidden=until-found using content-visibility: auto?

Some differences between the auto and hidden values for the content-visibility property:

1. auto keeps content accessible whether or not the content is skipped for rendering. hidden always ignores the content in the accessibility tree.
2. auto skips rendering while the content isn’t relevant. This means that if the content is in the viewport, it will be visible.
3. Both auto and hidden apply size, layout, paint, and style containment when the content is hidden. auto drops size containment when the content is visible.
4. auto keeps content selectable.

So, we’ve got our grocery list of differences to address by using content-visibility: auto:

1. We need the content ignored in the accessibility tree, but the element itself should still be accessible. This means we can’t set aria-hidden=true directly on the element itself.
2. We need to visually hide both elements and text nodes.
3. We need to ensure size containment is applied while the content is hidden.
4. We need to make the content unselectable.
5. We need to ensure elements cannot be clicked or focused.

We can address almost all but the first of these concerns with the following CSS:

[hidden="until-found"] {
	display: revert;
	content-visibility: auto;
	contain: size;
	user-select: none;
	color: transparent;

	> * {
		opacity: 0;
		pointer-events: none;
	}
}

You’ll notice we’re setting display: revert. Wouldn’t that revert back to the user agent style for the hidden attribute which would be display: none? Nope — the hidden attribute is what’s called a presentational hint and the revert keyword reverts presentational hints (as well as non-user agent styles). While this is usually why you’d need to exercise caution when using the revert keyword, perhaps even opt-ing for revert-layer instead, this is the perfect use case: we want to revert back to the element’s user agent styles.

Now, we’re not done yet. And there are improvements to be made.

Setting color: transparent on the element itself is problematic as it affects currentColor which could be used by other properties of the element (e.g. like its border). Instead it would be great if we could set it on an inner element that wrapped the contents.

Finally, we want to make some of these styles easy to override. Others should not be an easy override. With the current styles, we need to be very specific about where and when they needed to be loaded to avoid cascading issues.

To make these improvements and to address the issue of accessibility, we’ll be going into the shadows…

Into the Shadow DOM

We can use a shadow root to address both our styling and accessibility concerns — not a phrase you might have expected someone to say about the Shadow DOM.

First, inside the shadow tree we’ll use a <slot> element to hide any slotted content from the accessibility tree and we’ll take that content out of the tab order, since <slot> elements are what’s called a focus navigation scope owner.

<slot aria-hidden=true tabindex=-1></slot>

Why tabindex=-1 and aria-hidden=true instead of the inert attribute? The inert attribute does do everything we need: it makes an element and all of its content hidden from the accessibility tree, makes the content unselectable, removes content from the tab order, and prevents content from being clicked or focused. It also does something undesirable for our purposes: it makes content hidden for “find-in-page” features. So, unfortunately, we’ll need to settle with a deconstructed version of it.

Now, another great advantage of using a <slot> element is that it’s an encapsulated element inside the tree that with its default styles of display: contents just visually displays all of the contents: text and elements. This is great because we still want the host element to be exposed to the accessibility tree and potentially a part of the tab order. We can also use it to fix some of our styling problems.

In a stylesheet for our shadow root, we move the color: transparent rule from the host element to the <slot> element. This means that color and currentColor can be used on the host element, but all slotted content will be transparent.

Here’s what the stylesheet looks like once we introduce the <slot> element and adapt it for the shadow DOM:

:host([hidden="until-found"]) {
	display: revert;
	content-visibility: auto;
	contain: size;
	user-select: none;
	background-clip: initial !important;

	slot {
		color: transparent;
		pointer-events: none;
	}

	::slotted(*) {
		opacity: 0 !important;
	}
}

A few notes:

• In order to use the attribute selector for the host element, we need to wrap with the :host() functional pseudo-class. This selector allows us to select the shadow host which in our case will be the element with hidden=until-found set on it. This element is not in the shadow tree, it’s the light DOM element that the shadow tree is attached to. That’s why we need a special selector to target it.
• We’ve moved both the color and pointer-events properties to the <slot> element. This reduces the restrictions we have on the host element.
• We’re preventing the transparent text from being clipped by setting background-clip: initial !important on the host. This likely isn’t common, but since we’re using color: transparent on a descendant using background-clip: text on the parent with a background-color could expose the content visually.
• Since the slotted content is in the light DOM, we need to use the ::slotted() pseudo-element function with the universal selector to apply to all of the slotted elements. We’ve also made the opacity: 0 rule important as shadow DOM styles can be too weak to ensure this applies otherwise, since they’re cascaded before the document styles.

Now that we have our styles finalized, we can start implementing the polyfilling logic to apply this to any element.

Revealing the content when found

Unfortunately, this is where we have to leave Safari by the wayside, as there’s no good way to observe its “find-in-page” feature. This means that we’re effectively only targeting Firefox.

While we’re preventing user selection with user-select: none, the “find-in-page” feature in Firefox selects the found text. This means that we can observe if our hidden content has been found with the selectionchange event on the document (or window).

document.addEventListener("selectionchange", event => {
	const selection = document.getSelection();
	const foundElement = selection.anchorNode?.parentElement.closest("[hidden=until-found]");

	if (foundElement) {
		const cancelled = !foundElement.dispatchEvent(
			new Event("beforematch", { bubbles: true });
		);
		if (cancelled) return;

		foundElement.removeAttribute("hidden");
		const slot = foundElement.shadowRoot.querySelector("slot");
		slot.removeAttribute("tabindex");
		slot.removeAttribute("aria-hidden");
	}
});

When the selection changes, we check if the selected content is within an element with hidden=until-found, the beforematch event isn’t cancelled, and if we’re clear, then we start its teardown:

• Removing the hidden attribute (like the actual hidden=until-found feature works), removes all of our styles.
• Then we need to tear down the tabindex and aria-hidden attributes.

Afterward there is the shadow root leftover and while we can remove that if we replace the host with a shadow-less clone, we’ll lose the selection, which isn’t terribly hard to resolve, but it causes issues with the “find-in-page” feature which put me off from that approach.

Applying the polyfill

If we start a mutation observer early enough, we can both catch elements as they initially are parsed and later if there are any programmatic changes to the document. We can use this to polyfill the value for the global hidden attribute.

Here’s the configuration of our observer:

const hiddenUntilFoundObserver = new MutationObserver(callback);

hiddenUntilFoundObserver.observe(document, {
	subtree: tree,
	childList: true,
	attributeFilter: ["hidden"],
});

Since we’re observing prior to the <body> element being parsed or constructed, we’ll just observe the document itself. We want to both observe every element mutation and hidden attribute mutations.

Before we get into the the observer callback, since we’re covering two types of mutations, we’ll need to abstract our shadow root setup code:

const sheet = new CSSStyleSheet();
sheet.replaceSync(`
	:host([hidden="until-found"]) {
		display: revert;
		content-visibility: auto;
		contain: size;
		user-select: none;
		background-clip: initial !important;
	
		slot {
			color: transparent;
			pointer-events: none;
		}
	
		::slotted(*) {
			opacity: 0 !important;
		}
	}
`);

function addShadow(element) {
	if (element.shadowRoot) return;
	element.attachShadow({ mode: "open" });
	element.shadowRoot.innerHTML = "<slot aria-hidden=true tabindex=-1></slot>";
	element.shadowRoot.adoptedStyleSheets = [sheet];
}

If the element already has a shadow root attached this bail early. This is a limitation of making this a generalized approach. It’s not an unsurmountable problem.

We’re also using the same constructed stylesheet between elements. This is fine since we’re not modifying the stylesheet.

Now for our callback…

const hiddenUntilFoundObserver = new MutationObserver(entries => {
	for (const entry of entries) {
		if (entry.type === "attributes" && entry.target.getAttribute("hidden") === "until-found") addShadow(entry.target);
		else if (entry.type === "childList")
			for (const node of entry.addedNodes)
				if (node.getAttribute?.("hidden") === "until-found") addShadow(node);
	}
});

For attributes mutation records, we only need to worry about one element which makes it straightforward to check the value of the hidden attribute. For childList mutation records, the addedNodes could be text nodes, so we need to optionally call the getAttribute() in our check.

Now, all of the polyfill’s code is written and we just need to feature check if we need the polyfill. In browsers that support the feature we can check if onbeforematch is in the document. We’ll also want to filter out Safari which we’ll just have to do a bit inelgantly just using a supports-check for user-select: none since there’s no way to feature-check “find-in-page.”

if ("onbeforematch" in document || !CSS.supports("(user-select: none)")) return;

Once that’s in place we’ve got our entire polyfill:

(function() {
	if ("onbeforematch" in document || !CSS.supports("(user-select: none)")) return;

	const sheet = new CSSStyleSheet();
	sheet.replaceSync(`
		:host([hidden="until-found"]) {
			display: revert;
			content-visibility: auto;
			contain: size;
			user-select: none;
			background-clip: initial !important;
		
			slot {
				color: transparent;
				pointer-events: none;
			}
		
			::slotted(*) {
				opacity: 0 !important;
			}
		}
	`);

	const hiddenUntilFoundObserver = new MutationObserver(entries => {
		for (const entry of entries) {
			if (entry.type === "attributes" && entry.target.getAttribute("hidden") === "until-found") addShadow(entry.target);
			else if (entry.type === "childList")
				for (const node of entry.addedNodes)
					if (node.getAttribute?.("hidden") === "until-found") addShadow(node);
		}
	});
	
	hiddenUntilFoundObserver.observe(document, {
		subtree: tree,
		childList: true,
		attributeFilter: ["hidden"],
	});

	document.addEventListener("selectionchange", event => {
		const selection = document.getSelection();
		const foundElement = selection.anchorNode?.parentElement.closest("[hidden=until-found]");
	
		if (foundElement) {
			const cancelled = !foundElement.dispatchEvent(
				new Event("beforematch", { bubbles: true });
			);
			if (cancelled) return;
	
			foundElement.removeAttribute("hidden");
			const slot = foundElement.shadowRoot.querySelector("slot");
			slot.removeAttribute("tabindex");
			slot.removeAttribute("aria-hidden");
		}
	});

	function addShadow(element) {
		if (element.shadowRoot) return;
		element.attachShadow({ mode: "open" });
		element.shadowRoot.innerHTML = "<slot aria-hidden=true tabindex=-1></slot>";
		element.shadowRoot.adoptedStyleSheets = [sheet];
	}
})();

And here it is in action:

Summary of limitations

As mentioned, this does not work in Safari and you don’t need it in Chrome.

Due to issues with observing selection within shadow roots in Firefox, there’s no way we can make the polyfill work inside shadow roots.

And again, this also doesn’t work for elements that already have a shadow root.

Why even?

Given the limitations and especially the fact that this polyfill only applies to one browser, why bother polyfilling this? Well, to be completely honest I don’t find it worth polyfilling — especially since it would be quite easy to progressively enhance hidden=until-found usage. This was an interesting exercise in exploring findability in the browser. It’s something that authors don’t have direct control over. It takes a very thought out concoction of CSS and shadow DOM to even mimic something that is based on it. Perhaps this could be something that authors had greater control over in the future. Another part of browsers to unearth in making the platform extensible?

Contribute

If you want to use the final polyfill or contribute, you can do so on GitHub at knowler/hidden-until-found-polyfill.

Why I need a non-traditional browser

I imagine that I have some kind of neurodivergence. I haven’t formally explored it and I don’t really know enough to put a label on it. Context switching is very difficult for me and I get distracted so easily, which isn’t helpful when my mind is constantly drawing connections between seemingly disparate things. I can become very obsessive on topics and often lose track of time when I get lost diving into details and making a terrible mess of my workspace making it unapproachable for myself if I return to it.

Anyway, I should probably talk to a mental health specialist about all of that, the point I’m trying to make is that Arc is shaped in a way that has been tremendously helpful for my ability to work and focus. Being able to eliminate distractions, separate extremely focused contexts, switch between contexts in a non-overwhelming way, tame my tab hoarding tendencies or at least create meaningful structures for those tabs, all have been incredible for me.

Before Arc, I was jumping between browsers because I couldn’t use Firefox, my previous daily driver, for work since the proprietary SSO extension required for that job didn’t support it — IYKYK. What I loved about Firefox was its container tabs. They allowed me to have separate isolated sessions in the same window. They weren’t perfect as all of those container tabs were still mixed together in the tab list, so I had joked that I wanted Firefox’s container tabs and Chrome’s tab groups to have a baby.

Arc was even better than that.

My forever browser?

In Arc, there are profiles which is very similar to profiles in other Chromium browsers: they have their own session and extensions. A major difference is that in Arc profiles all live in the same window.

A core feature of Arc is spaces which are effectively separate tab lists (almost like tab groups) which are visually isolated from each other. Multiple spaces can use the same profile and when they do, they can share some favourites which are like a super pinned tab. Within spaces, regular pinned tabs can be organized and renamed like bookmarks inside folders. Using the same hotkey to close a tab on a pinned tab will reset it to its initial URL which is helpful when I make a mess of my pins.

A very important feature for a browser like this is being able to route incoming URLs into the correct space. For this, Arc has a feature called “Air Traffic Control” which allows you to set up those routing rules. I found it works exceptionally well.

A more controversial feature that I’ve come to really love is the default to clear tabs after a certain period of time. The default of 24 hours might be too short for some, but that’s why it’s configurable. Left unchecked, I am a major tab hoarder. Sometimes I’d have hundreds of tabs hoarded on my phone, but I’ve since taken advantage of a feature like this in Safari. Since Arc makes it pretty easy to meaningfully organize tabs, I’d treat the regular tabs like an inbox and the pinned tabs would become longer-term storage.

Now, don’t get me wrong, there are features of Arc that I really do not like — their quote feature which I think is a recipe for widespread link rot and the Arc Max AI bullshit — but Arc worked overwhelming well for me and I used it almost exclusively for two years.

Getting off the Arc

I made plans to stop using Arc, when I realized the team was more interested in AI and “disrupting” traditional web search than iterating on the user experience of the browser. Sadly, that probably hasn’t changed and I’ll address that later.

But it took months to stop using Arc because I had really leaned into many features like folders and renaming tabs. Whenever I started a new project at work, I’d scaffold out a new folder with renamed tabs for each environment of the site I was working on, sometimes even tabs for my own PRs or the ones I was reviewing. I’d collect important links which I’d give more relevant names.

First stop on the Safari

Initially, I jumped to Safari and made use of its profile feature and tab groups. Tab groups were the closest thing I could get to renaming tabs, so sometimes I’d just have a single tab in a group or I’d get creative with how I organized groups. Safari’s Reading List feature replaced how I sometimes used pinned tabs in Arc — almost in a better way, since I use the Reading List on my iPhone a fair bit either to queue up articles to listen to while I wash dishes or to read if I’m ever offline. Ultimately, I still struggled with funnelling tabs into the correct contexts, keeping those contexts focused and in tact, and dealing with some frustrating bugs in Web Inspector.

I evaluated a number of other browsers, like Vivaldi and Orion, and though they had many features that I liked, I just couldn’t find one that worked with how I now worked.

Once my previous job ended, I sought to make the return to Firefox or a Firefox-based browser. I tried a few, even Firefox Nightly which has an experimental vertical tabs features, but I ultimately landed on Zen browser for a few months.

Zen: the closest browser to Arc

Zen was the closest to Arc that I’ve found. Zen not only has container tabs since it’s Firefox based, it has its own Space-like feature called Workspaces which effectively works the same. You can even set a default container tab to use for a space. Container tabs already do have a routing feature to open matching URLs in the correct container, so it was very close to Arc’s “Air Traffic Control.”

Now while Zen is really shaping up to be effectively an Arc-clone in Firefox, I found it to be too unstable and slow for my day-to-day work. Sometimes an update would completely break my workspaces. There were times when I’d need to research a topic and I just knew that I could do it more effectively in Arc itself.

Firefox’s Web Developer Tools also has a terrible bug where constructed stylesheets sometimes won’t display at all in the style panel which would require a full reload and re-opening of the dev tools panel. It was oddly reminiscent of the bug I was dealing with in Safari’s Web Inspector which required the same solution.

Despite this, I am optimistic for Zen browser. I truly loved being back in a Firefox-based browser. I also loved having my vertical tabs on the right side instead of the left — am I the only person in the world that’s bothered when you toggle a left sidebar and my left-to-right content shifts substantially? I digress.

Once I realized that Zen could not sustain my day to day work, I knew I had to go back to what I knew worked: Arc.

There and back again

So, I am somewhat reluctantly back using Arc and it’s made a noticeable difference already. I’m disheartened that the company is still obsessed with AI. I have mixed feelings about them deciding to not work on another major version of Arc: they are leaving Arc alone to channel that AI-fixation elsewhere, but at the same time, despite what they said, I hope this isn’t Arc’s death-knell.

I thought Arc could be my forever browser, but I’m really not sure that’s a thing. I expect that I’ll adventure elsewhere at some point. If I could steal an ounce of the Browser Company team’s AI-consumed attention for Arc to ask one selfish thing:

Can I please but my sidebar on the right-hand side? That would truly make Arc complete to me.

Personally, I still think that as a custom element author, I want to give my consumers the most flexibility for how to use a custom element I’ve created:

• I want to do what I can to help them avoid name collisions.
• I don’t want to assume their conditions for defining a custom element.
• I want to support consumers who want to use scoped custom element registeries in the future.

However, I began to wonder how I could add the convenience offered by a single script solution.

I could just include an additional file that handles the definition:

import { BlehBlehBlehElement } from "./bleh-bleh-bleh-element.js";

customElements.define("bleh-bleh-bleh", BlehBlehBlehElement);

But this really is such an insignificant amount of code and it introduces nested imports. The latter is resolvable with a preload, but it still creates complexity and a potential footgun for consumers.

I also could create a bundle for that file… but I like to not use build tools whenever I can since I don’t want the complexity myself.

This got me thinking about import.meta. For modules, import.meta includes the URL used to load the module. This means we can create an additional API for the module using its URL’s search params.

So in our case, we can just conditionally define the element when the ?define search param is set:

// Export the class so the consumer can register the element with greater flexibility
export class BlehBlehBlehElement extends HTMLElement {
	constructor() {
		super();
		if (!this.shadowRoot) this.attachShadow({ mode: "open" });
		this.shadowRoot.innerHTML = "🧛";
	}
}

// Check if `?define` is set and if so, define it in the default registry
if (new URL(import.meta.url).searchParams.has("define")) {
	customElements.define("bleh-bleh-bleh", BlehBlehBlehElement);
}

Here’s how a consumer of the custom element would use it:

<!doctype html>
<title>Bleh bleh bleh – Drac</title>
<script type=module src=./bleh-bleh-bleh-element.js?define></script>

<bleh-bleh-bleh></bleh-bleh-bleh>

Is this a bad idea? Sure, the script must be a module now (i.e. you must set type=module on its <script> element), but that’s likely a good thing.

Anyway, I thought this was a pretty neat way to keep things simple for both a custom element author and consumer. Let me know what you think.

So, a great smoke test for custom elements is to try to create it programmatically:

document.createElement("my-element");

There’s a couple of exceptions this might throw:

DOMException: Failed to construct 'CustomElement': The result must not have children

In this case, you’re adding children to your custom element inside its constructor.

DOMException: Failed to construct 'CustomElement': The result must not have attributes

In this case, you’re setting attributes on your custom element inside its constructor.

The HTML parser isn’t going to surface these issues for you and so if that’s all your testing with (i.e. you’re just writing plain text HTML), then you could end up shipping something that’s broken.

An important principle emerges from these cases: don’t do light DOM operations inside of the constructor.

A digression on sciopobia

If you write “HTML Web Components” — sciophobic custom elements that avoid using the Shadow DOM — you are likely going to be more prone to this sort of issue as you’re creating elements against the grain of HTML. It might seem easy enough to just not do stuff in the constructor, however, using the light DOM to express the make up of a custom element is naturally going to be more prone to these issues in general which is why I avoid it if I can. When you ditch encapsulation this is what you get. The promise of “framework agnostic” components does not look very promising with such an approach, since frameworks expect custom elements to behave as HTML elements do.

How to participate

1. Follow the hashtag #ReadThePlatform in the fediverse. Feel free to lurk or to secondhand read.
2. Read books or content about the Web Platform at your own pace. Sync up with others if you’d like.
3. Share about that content using the hashtag. Feel free to share anything you write about it on your website too.

There’s no formal meet up times, but don’t let that stop you from organizing meetups to discuss with others.

My own reading list

I’m no authority here — you can read whatever you’d like, but here is my own initial, tentative reading plan if you’d like to follow along with me:

1. Idiosyncrasies of the HTML parser by Simon Pieters
2. Web Browser Engineering by Pavel Panchekha & Chris Harrelson
3. Web Platform Contribution Guide by various authors

All of these books are free to read online, open source, and in the case of the first two, you can support the writers as they continue to write their respective books. Those details can be found in the links above.

Why I’m doing this?

My own personal motivation for reading books and other content about the Web Platform is not only to deepen my understanding of the medium as it affects my work, but so that I can contribute in more ways. I’ve been inspired by individuals involved in moving the Web forward and I believe that the Web is ours and not just the product of large companies. I believe in the Web and so I am reading to ensure the Web continues to have a future, because the Web is not inevitable.

Note: I wrote this a number of years ago and had it on my site at a different path. I noticed it was linked from another one of my pages, so I figured I’d re-publish it here on my blog. Ironically, I haven’t touched my dotfiles for a few years, but that’s because I had to fork them for work to store them privately and that’s what I now maintain.

When it comes to maintaining anything that serves a sort of background function for more important things, it is vital to ensure that the maintainence process is simple, otherwise, there will be stagnation and that thing won’t be serving its purpose. When it comes to dotfiles, I don’t believe there is necessarily a best way to maintain them, however, your maintainence methods should suit your strengths.

Mine is Git.

I’ve used Git for a number of years and it is a tool that I use every day. For many developers, I am sure this is also the case, though I expect that many might not feel adequately strong at using Git. I still think that a maintainence workflow that favours Git is the best route for most of these developers, because the main alternative is a workflow that, while it does use Git, primarily depends on a shell’s linking capabilities (i.e. ln), and from my observation and experience, most developers are much less confident here.

That was the case with myself. I found myself spending a long time writing shell scripts for linking files or using scripts that required a tendious degree of maintainence in order to add new files or simply to move files, along with a lot of time spent on trial and error — which is scary to do when you just need your system to work for more important tasks. This usually resulted a stale dotfiles repository and a lot less care for my local dotfiles or even fear towards modifying (or fixing) different configurations.

In 2020, after a number of issues with my computer hardware which required me to setup at least 3 different fresh OS installs for my work, I decided that I needed to find a solution for my dotfiles so that I could reduce how much time it was taking me to get to work.

The Bare Repository Method

I stumbled upon an article by Atlassian called “The best way to store your dotfiles: A bare Git repository.” I had never heard of a bare Git respository and since I had been digging deep into Git, I was curious. After reading the article, I gave the setup a try in a new respository on my GitHub and very quickly realized that this was a much easier way to manage dotfiles, and I converted my main repo over.

A bare repository is essentially just the .git directory without a checked out worktree. A setup looks like cloning your dotfiles as a bare repo. Usually it is advisable to use something other than .git, I use .dotfiles in my home directory. Then you create checkout a worktree in your home directory. Now, you might wonder, wouldn’t that display everything as potential files to track when I run git status? Yes, it does, however, this is easily solvable, by turning off untracked files in your status config for the repository.

Clone the repo

git clone <repo> <git-dir-path> --bare

Do not show untracked files in git status for the repo

git --git-dir=<git-dir-path> config status.showUntrackedFiles no

Checkout the worktree in your $HOME

git --git-dir=<git-dir-path> --work-tree=$HOME checkout

Manage dotfiles using Git

You will need to prefix your Git commands with the path to the Git directory and the worktree path:

git --git-dir=<git-dir-path> --work-tree=$HOME <command>

It is best to create an alias for this.

alias dots="git --git-dir=<git-dir-path> --work-tree=$HOME"

Now, you can use this alias however you would use Git.

dots add ~/.config/nvim/init.vim

dots commit -m "Add Neovim config"

dots push