When performing a WCAG evaluation (or review or audit), it’s easy to get caught up in the intent versus meaning of a particular Success Criterion. Especially when that SC was written before the interface pattern you’re poking was conceived.

Until, and even when, you have built your own (potentially localized) references for how to apply an SC to whatever situation, it’s best to have a plan for how to interpret the uninterpretable.

Steps

This is my progressive series of steps for getting the W3C’s most current (and soon-to-be-current) position on any SC.

1. Read the W3C’s normative text (the “official” requirements) in the WCAG spec.
   • Always look at the latest, which is WCAG 2.2 at the time of this writing.
   • Make sure you’re at a w3.org site, not some scammy wcag.com or similar domain.
2. Read the W3C Understanding document (the supporting material) for the SC you’re evaluating.
   • These often have linked references in the form of…
3. W3C Techniques documents collect known failures along with passing and bonus methods.
   • Some are out of date or refer to technologies that have been superseded or failed to work as hoped, so be cautious.
   • A single Technique document might apply to multiple SCs.
4. Look at WCAG GitHub issues.
   • Pay attention to dates, linked issues & PRs, embedded meeting minutes, and decisions.
   • Look for the closed issues, as those are often decided answers (the issues that aren’t from spambots).
5. Look at WCAG GitHub pull requests, even if they never merge.
   • Pay attention to dates, linked issues & PRs, and embedded meeting minutes.
   • Look for the closed PRs, as the ones that didn’t merge often have good discussions
6. Look at GitHub WCAG discussions, few though there are.
   • If you find an unanswered one that maps to your question, maybe comment.
7. Look at personal blogs of trusted experts, some of whom are often those working on the specs and who give their own insights.
   • Be cautious of blogs promoting an agenda or arguing for an SC interpretation without supporting evidence. Pat goes into detail in a 2025 talk and more recent slides.
   • This applies to those justifying the bare minimum to pass an SC via loopholes or gaps, in some cases as adversarial or malicious conformance. I have a few posts on that.

No matter what outcome you find, test everything anyway. New releases are constant, regressions common, new support happens, and user expectations shift.

It’s possible you find that a W3C answer to a failure condition creates a worse experience when remediated (orange). At which point, all the research you’ve done will make it easier to justify if you need to break from the W3C position.

I’ve been doing more front-end coding this year than I have in a while and every time I come back to write markup and CSS, it feels like there are new tricks. We’re closing in on the 30th anniversary of CSS (already a little past 30 years since Håkon Wium Lie proposed it) and it still feels like actual magic.

When I was first making websites (I’m just skipping over the part where I put a year on that, thanks), I used tables for layout and a pile of spacer gifs. Then I would make them look nice with the little CSS I knew. I was mostly slapping things together back then, not fully understanding semantics, page weight, or the cascade. In time I learned how to do things properly from Eric Meyer’s Definitive Guide, and multiple CSS books by Dan Cederholm. I typed color: red; and a thing turned red. No compiling or build steps. It was declarative and made me feel like a wizard (it was a much lower bar for wizardry back then).

Over the years since then, and especially in the last decade-ish, CSS has exploded! Flexbox, grid, many kinds of viewport units, variables, and on and on. So many things we used to patch in to extend CSS or turn to Javascript for are now just part of the spec. The ease with which you can create a flexible type scale or size elements and spacing responsively with clamp… the screen has really matured into its own unique design medium with tailored affordances that aren’t just translations from another medium (print). CSS finally gave the web its own grain.

And the real crazy part is that my bad decades-old code still renders fine in today’s latest web browsers! I would be sad if it didn’t, but I also wouldn’t be surprised. How is this stuff still backwards compatible!?

How much of your software from 20 years ago runs on your devices today? I realize CSS is actually “software”, but it is a kind of user interface for making stuff. Most things in tech get worse as time goes on, filled with upsells and ads, or sparkle icons to try out some rad new agent surreptitiously shoved into an app. CSS gets better with age and as more features are added. That’s bananas!

Of course this is because of wonderful people continually making it better. Like Rachel Andrew, Miriam Suzanne, Jen Simmons, Lea Verou, and folks on the CSS Working Group who continue refining and expanding the CSS spec, and many others at companies making the browsers that run our code.

Though, I’ve got my eye on some browsers blithely bellyflopping into enshittification. I know many things are shit in the world right now, and there is a lot in tech making outsized contributions to that. But CSS continues to be a surprising light to me, and I want to celebrate something incredible that keeps improving because people care. CSS is a goddamned marvel.

Reply to this post via email

This is the second of two parts on media creation. You can find the first part over here: Creating media with an uncooperative mind

Infinite negatives #

In trying to figure out what I should write and talk about, I could spend the rest of my life outlining all the topics I don’t care about. The world is larger than our attention can encompass.

Even if I limited myself to going over the topics you might expect somebody like me – based on the public image I’ve chosen to project online – to reasonably cover but won’t, that’d still require me to write more words on subjects I dislike than on the ones I like.

This blog has always been a practical venue. I had blogs before – I’ve been writing online in one place or another since the mid- to late nineties – but this was the first place I specifically used to position myself for a chosen career.

I’d focused on ebooks for my PhD, given up on them after graduation because they seemed dead in the water in 2006.

Then as soon as I settled into a web dev job, ebooks finally became a thing with the Kindle, iPhone, and competitors all popping into the market from 2007 onwards. So, after waffling about for a couple of years, watching from the outside as the topic I’d studied for my PhD finally took off, I decided to make a venue where I could, effectively, put up a sign saying:

“Are you interested in ebooks and publishing? I know a bunch of stuff about that! Have degrees and everything.”

This website was born. First as a straight website, as I was mostly blogging on Tumblr in those days, but later I turned it into proper blog, with an RSS feed and everything.

As the ebook side of the publishing industry went through its own bubble and bust, with the inevitable fraud, collusion, and antitrust convictions (because this was back when cheating the public occasionally had consequences) I tried to reposition myself more on the crossroads between publishing and web development.

As I became a senior web developer, the gap between the understanding of most managers I’d dealt with and the realities of software development became more and more obvious and acute. I figured I might be able to help bridge that gap by writing specifically to try and explain how uniquely software development interacts with management practices and theory. That way I could target two different audiences with a single topic:

1. Software developers who both needed to explain to their managers how their work, well, worked and needed to better understand what their managers were dealing with.
2. Managers who found themselves managing software projects but didn’t necessarily have visibility into some of the unique problems with software development.

That led to the book Out of the Software Crisis and related blog posts.

The book was both a product designed to help people do their jobs and a tool to help me position myself as a freelance consultant beyond the more narrow publishing and media space where I’d previously planted my software development flag.

It did result in a number of contract leads, but fewer than you’d expect. Next to none of those leads survived the first “weeding”. Most managers who exhibited an interest in the problem of managing software development seemed to be major fans of extremely distasteful people with very poor judgement and warped priorities.

Somebody who keeps praising people like the 37 Signals manager who led their company into repeated crises by prioritising extremist politics over good management is unlikely to be a pleasant person to work with, even if you naively disregard their likely politics.

Once I weeded out the “37 Signals are great managers” sympathisers and related crowd – they seemed thick on the ground in software even after that company’s first “racism is good, actually” implosion – the remaining leads were old contacts from the publishing industry who had gone “oh, this means Baldur is a freelancer now” and got in touch. A significant portion, though not a majority, of these projects turned out to be related to corporate web developer education and training, which I enjoyed.

I did consider trying to turn the “momentum” of the book into other products – a course, mentorship, or the like – but, while I had experience as a lead dev, I’d left all of my ambitions of becoming a manager of some sort behind and I think there’s a limit to what somebody who has never been a manager can teach people with ambitions in that direction.

I didn’t feel I could teach a field that I wasn’t interested in practicing myself, especially since I was still deep in my Long COVID brain fog that had hit me just before I began work on the book.

Then, as the worst of fog began to inch away, the “AI” Bubble happened.

I never intended to write about “AI” #

I’ve had an on and off interest in “AI” and Machine Learning for most of my career so, when Copilot and ChatGPT started to get traction, looking into it was a logical move.

What I discovered appalled me. All of those management principles I’d been trying to teach in my work and writing, all the development practices I’d been trying to promote, weren’t just being disregarded by these tools.

They were, and still are, the antithesis of sound software development and good management.

They are broken by design, all the way from the fractured ground up to the wobbly top.

• The error rates are unacceptable.
• The variability and volatility is unacceptable.
• The copyright ambiguity they create in the generated code is unacceptable.
• The disregard of consent, regarding both the personal data and creative works they derive their models from, is unacceptable.
• The abuses they enable are unacceptable.
• The environmental impact is unacceptable.
• Their political collusion with extremists is unacceptable.
• The sheer scale of destruction they inflict on the knowledge ecosystem and creative industries is unacceptable.

And, fundamentally, they make good management impossible. The way they function is incompatible with organisation, structure, quality, and variation control.

Any form of integration with your work will compromise your work, irrespective of the costs, origin, point of execution, or ethics of creation. The damage may not be apparent at first, but these systems, due to their design, will hurt you in the long run.

I and others have compared it with asbestos – a miracle material with genuinely amazing properties that is so incredibly harmful that it has even been banned in the United States. For the most part. That final attempt to close the gap on an asbestos ban took place in 2024, with the preceding debate coinciding with the initial growth of the “AI” Bubble.

It isn’t a coincidence that the asbestos analogy has been popular among those who criticise “AI”. It was at the top of the mind of pretty much anybody who was concerned about safety and consumer protection while ChatGPT was blowing up.

But I now prefer to compare generative models to leaded petrol:

It poisons everything, increases crime, harms your brain, makes the world genuinely worse in multiple ways, and could have been replaced with safer and more effective solutions at pretty much any point in its history.

The only reason people didn’t – why they chose to knowingly poison their children and their own societies – was to save a little bit of money in amounts that never came even remotely close to outweighing the immense costs to society.

This is a technology that should never ever have been shipped.

I’m genuinely disappointed in every single person who keeps promoting it in their blog posts, videos, or social media.

The Intelligence Illusion, where I wrote about the risks generative models create for businesses, was motivated by how appalled I became as I researched the technology and how it interacted with the theory and practice of management.

This both worked and backfired in ways that I never expected.

No freelance career yet #

I did get a couple of interviews in the early days, as I was one of the first to push out a book on the topic, but once I got quoted out of context in a fairly awful New York Times piece I began to deny interview requests that were specific to “AI”. (There are a couple of outlets I’d decided in advance I’d say yes to if they asked, but they never asked.) I’d recommend people, and I offered to speak on background, helping the reporter understand what they were covering.

Only one took me up on that offer, which was a lot of fun, and the interview requests stopped after a while. Once reporters stop seeing your name in the venues they keep an eye on, they drop you from their list.

There was never any chance of the book leading to freelance opportunities. Every time I’ve received queries from companies on helping them form an “AI” strategy or policy, I replied with a short message saying that my advice is simple:

Avoid the tech until the bubble pops, then reassess. Most of the biggest web companies in the world today got into it or were founded after the dot-com bubble popped. Being late is a strategic advantage. If you want, I could help you outline how that strategy would work in detail – how to prepare for when the bubble pops – but otherwise my advice is simple: Wait.

I always thought this was a nice and neutral reply. Focused on the strategic benefit to the company. No mention of pesky ethics or environmentalism that might scare the punters off or disturb the unholy soulless inner workings of an MBA.

But the communications always ended at that point.

Almost all of my freelance clients continued to come from former publishing industry contacts.

The other problem was that the book itself and the associated blog posts arguably backfired.

Be careful in explaining your adversary’s mistakes; they might learn from it #

The book helped the right people. But it also helped the wrong people.

The best way to explain it is to put it in the context of a different societal and economic transformation: the deindustrialisation of the US with outsourcing.

Companies all over the US were destroying local jobs, closing factories, and deindustrialising their country by shifting work abroad. If you believed that outsourcing weakened society, led to the downfall of the economy, and exposed the companies to hard-to-manage risks, one of the worst things you could do would be to focus on the risks to the companies.

If you were living in that era and had the skills and interest to tackle the issue, you could take the humanities and social sciences approach and outline the effects on the social fabric, local communities, education, and public health. If you were an academic or a journalist, this would be the approach that made the most sense and your position would give you enough standing to make people listen.

Or, you could have put on your policymaker or economist hat and dug into the fractures this created in your economy and the sociopolitical risks to the state. Anybody who had the ear of the lawmakers would have been a fool not to take this tack on the topic.

If your skill sets were management theory, systems-thinking, and the organisation and structure of work, you might have be tempted to cover how outsourcing specifically harmed the companies themselves, their function and ability to operate, in an attempt to talk them out of it.

This would have been a mistake.

These companies were deliberately setting out to weaken the bargaining power of the workforce. They already felt that the risks were worth it. All you could have accomplished by going over the specific risks of outsourcing they themselves were facing – the communications, the longer iterations, the disconnect between teams, etc. – would have been to help them mitigate the impact of those risks and further their goal of destroying labour.

Offshoring – despite being on a macro level one of the more catastrophic strategic errors in US history since the end of the Cold War – happened nonetheless. It made the companies and their owners richer even as it rotted their countries from within.

“AI” is flowing into those same dried riverbeds. It’s the same social, economic, and strategic mistake except at an even larger scale and putting even more at risk.

My book was helpful to many readers. I still occasionally get emails thanking me for getting their defences against LLMs up in the early days of the bubble. Not often, but occasionally.

But to some readers it was helpful in ways that I, the writer, did not enjoy or appreciate.

Many of the glowing recommendations and positive buzz around the first edition of the book came from consultants who then used it as a playbook for furthering “AI” adoption in business by managing the risks deemed important by the business. I even got an email from a Scandinavian VC and “AI entrepreneur” thanking me effusively for the book.

If you ever wondered why I stopped covering specific organisational and work-related issues caused by “AI” – the flaws specific to the tech and how they interacted with work – now you know.

If you wondered why I published a second edition despite the risks being fundamentally unchanged and most of the research continuing to come to the same conclusions, this is why. I wanted to reposition the book to make it untenable to the consultancy crowd.

This worked, I think. At least I don’t get emails from management consultants or VCs any more.

My writing here shifted mostly to three topics:

• Tech scepticism. That is, advocating the idea that you should be careful about trusting the tech industry and its products.
• The personal impact of “AI”.
• Web development.

(Also photography, but that’s just for fun. Nothing practical about it.)

My tech scepticism netted me what you could describe as a “backbencher” position in the online tech scepticism community. Not one of the frontbencher who gets called on for interviews and the like, but I occasionally get to write a polemic that rouses and motivates other backbenchers.

There isn’t much more to it than that at the moment, and that’s fine.

But when I turned back to writing about web development, I discovered that the field was gone. Web dev training, specifically, has been wiped out by “AI”.

Where did everybody go? #

While I was busy pushing the “AI” book I’d failed to notice that all my training and education projects had dropped off one by one. Most of my peers who had been selling courses and training were shutting down their businesses. The demand for web dev ebooks had cratered.

So, my attempt to shift away from the “AI” book back to web dev training was a bit like exiting a bunker with a hot dog cart in tow and try to sell a nice juicy hot dog in a blasted post-apocalyptic landscape full of ash and radiation.

Software developers haven’t all switched to using agents for their coding, but they do seem to have all switched to error-prone, backwards-facing, nondeterministic chatbots for what now passes as web dev “education”.

Every time I thought to myself “maybe it isn’t that bad, those two are still selling their courses and ebooks so there obviously continues to be a market for this” I’d find out a while later that their business had indeed collapsed and that they had been coasting on fumes. Then they would give up as well and quit the industry.

Moreover, the field of web development has regressed overall. React and framework-oriented development is back in full force. Novelty and research now focuses exclusively on some variation of getting a Large Language Model to regurgitate some old thing into the gutted, hollowed-out skinsuit of some other old thing. “Let’s use an agent to port it to Rust! Let’s make a WordPress replacement in JavaScript! Let’s port this project to a more convenient license!”

Dependencies are getting less and less reliable as everybody’s toolchain gets rotted open with insecure coding agents and bad practices are automated into petrification.

Design is nonexistent.

User research is nonexistent.

Product development is nonexistent.

I don’t enjoy my field any more because the field is gone. Assuming that there’s still something there is a mistake. That feeling you have isn’t a frustration with changes to your chosen field. It’s nostalgia for a field that disappeared overnight. What passes as web dev today at large bears no resemblance to the field we built over the years. Everything we learned has been abandoned because companies assume it’s all been encoded into their chosen Large Language Model.

I’m still doing web development work, but navigating the flood of misguided pull requests and nonsense “documentation” is getting harder, not easier. I love the work when I get to do it without dealing with nonsense, but I don’t think finding those opportunities is going to get any easier from now on.

It’s frustrating and depressing and the more I experience the “new world order” of web development the less I want to have to do with any of it.

Employment in tech seems done. All the major employers have revealed their hand and that hand is just one “fire more; hire less” card after another.

You could stay and fight for your survival, but it would be foolish to expect those who remain to have a glorious career. You’re basically in the same position as a non-union factory worker in a post-outsourcing, deindustrialised economy. You might be one of the few who gets to keep your job but what little bargaining power you had against your employers is gone. That never ends well for the worker.

With web dev gone and tech scepticism not being anything that resembles a career path – you’re a Patreon- and book-subsidised commentator at best, not nothing, but still not a long-term career – it’s hard to figure out where I should position myself.

This blog has been a personal journal, a venue for hashing out my thoughts and ideas. It’s also played a big role in developing my career.

Software development and tech have been where I positioned myself, for most of the past decade or so. Everything else has fallen into the “personal” category. Stuff that I cover because I needed a venue for the thoughts, but never represented the brunt of this site.

Outside and downplayed #

A necessary part of surviving having an online presence is artful omission. Parts of your life get to be visible online. Other parts are downplayed. The rest is offline.

The part of my life I’ve constantly downplayed online is my work, education, and experience in media and publishing.

I’ve worked in radio, TV (vision mixer), did a short stint in Iceland’s then brand-new film school, wrote and self-published novellas, and helped a number of people publish their books both digitally and in print. I’ve helped artists put together their art books and assisted with their installations. My first degree was in comparative literature. The rest were at an Art, Media, and Design faculty. For years, I worked just as much in After Effects and Premiere as I did in Director, Flash, or web dev. I taught both at an art, media, and design faculty in Bristol and design and photography students at a junior college level here in Iceland. I published a graphic novel a few months ago.

It’s the part of my career that I’ve enjoyed the most and, for a while, spent the most time on.

But it came with two problems:

1. It generally doesn’t pay. At least not compared to web dev work.
2. I always felt like an outsider in those fields.

As I’ve grown older I’ve come to realise just how much the second issue affected me.

For example, one memory that still sits with me and played a big role in driving me away from fiction writing was as I sat listening to a friend of mine struggle to say something positive about a novella I had written. He settled on “the typography is excellent.”

The typography of an ebook. This, coming from a British publishing professional, if you know what they’re like you know what that means, felt devastating.

I completely gave up on writing fiction shortly afterwards, and I’m only now coming to terms with how much of that came from how rejected I felt by my friends and acquaintances in the publishing and media industries. At the time it felt like the people who I thought would cheer me on unprompted just all fell silent. I always assumed it was because they couldn’t think of anything nice to say.

That I worked at the crossroads between tech and publishing – ebooks, content management systems, reading systems, and the like – also seemed to mark me as an outsider.

Another defining memory from that period was sitting in the Unbound offices (this is before we all found out what was going on there) and chatting with others around the lunch table about our jobs. As you do. When I mentioned something I was working on, one of my coworkers turned to me and said something along the lines of “I’ve never read an ebook and never will” and that was the end of that. In the end, the only topic of conversation that seemed tenable for me to the rank and file of Unbound was to answer questions about Iceland and tourism in Iceland.

On more than one occasion, I had people at publishing conferences immediately turn away and leave the conversation as soon as I mentioned that I was working on the tech side of things.

Seeking approval from people who were never going to approve of you is never healthy.

Some people were great – still are – but those also tended to be treated like outsiders by the rest of the industry.

Over the past decade I’ve actively downplayed the scope of my media and publishing career because I’ve always assumed that your average person in tech would be at least as big a dick as the average publishing person and would be just as dismissive of anybody with a hybrid skill set.

I don’t think I was wrong about that – “we’re major dicks!” seems to be a point of pride for many in tech – but I do think I underestimated the potential of connecting with other outsiders. People with hybrid skill sets, expertise and experience in both print or media and in tech – or even just experience in one and a dream of another – and who feel alienated from both sides of the crossroads they work at.

I think I underestimated how many of us there are and, now that the “AI” Bubble has managed to alienate big swathes of society, I think there are more of us than ever before.

So, more than a topic, I have a feeling I want to capture. A spark of an emotion I want to keep alive:

I don’t want any of us who stand at the crossroads between fields to feel like outsiders any more. With the world heading where it’s heading, us outsiders need to band together.

The actual topics, I think, should be more defined by what this ad hoc group of people – wherever I find them – need solving than anything predefined, but I think there might be a few broad areas I could tackle.

• Creative processes. Specifically coming from one process to another and how you adapt your thinking and approach when transitioning to a new venue or field.
• Getting over the hurdles of doubt and worries about the ugliness of your work.
• Getting things done and productivity are not the same thing. In fact, I’d say they were close to opposites.
• Discovering yourself is a key requirement for sustainable achievements in any creative field.
• Appreciating the ugliness of both creative and tech work.
• Understanding the context of media and how tech affects it.
• How to deal with the way tech affects our work and media.
• Understanding how the grammar and structure of social media affects what you can say and how you can say it.
• Working with the hybrid media landscape we live in.

The topics are endless, but the feeling defines the worldview and angle of approach.

I think I can figure out a way to be useful for this audience.

And the next step is pretty much just to go ahead and try it.

At least, that’s the theory. We’ll have to see how it turns out in practice.

Fewer lines of code is always a good thing, but it’s the permission prompt that’s key here. When using the aging Geolocation JavaScript API, denying permission at any point can lock the user out with no way to recover unless they change the browser or operating system permissions manually. This can be a painful experience, especially for users that aren’t tech-savvy. Plus, as developers, we have to get the Permissions API involved.

Whereas, the <geolocation> element offers:

• Better error handling, and where applicable, recovery handholding
• User-controlled permission prompting, even if the user denied permission previously
• Auto-location if the user granted permission previously
• A styleable granted state via the :granted CSS pseudo-class

<geolocation> is better in every way except browser support (it requires Chrome 144+), so in this article, I’ll explain how to use it alongside the older current Geolocation JavaScript API so that users get the better experience, if the new element is available.

Requesting the user’s location using <geolocation>

The <geolocation> element accepts several attributes that largely correspond to the options of the getCurrentPosition() and watchPosition() methods of the aging Geolocation API.

Firstly, the accuracymode attribute accepts two values — approximate (which is the default value) and precise.

accuracymode=approximate is equivalent to the enableHighAccuracy: false option (again, the default) from the Geolocation API, whereas accuracymode=precise is equivalent to enableHighAccuracy: true, which provides a more accurate location if the device is able to get one.

The autolocate boolean attribute attempts to get the user’s location automatically, assuming that they’ve granted the website permission previously.

The watch boolean attribute is equivalent to calling the watchPosition() method instead of the getCurrentPosition() method. getCurrentPosition() fetches the user’s location once, whereas watchPosition() tracks their location over time. Like accuracymode=precise and enableHighAccuracy: true, this drains the battery faster.

The onlocation event handler attribute can be used to execute JavaScript whenever location data or error information is passed to the browser.

What the <geolocation> element doesn’t offer, though, is the ability to specify the timeout (how long the browser should wait for a response) or maximumAge (how old a cached location can be). Instead the browser handles these as it sees fit, which is actually a good thing, because choosing the right values on a case-by-case basis is a complexity that we just don’t need.

In practice, this is how you might use <geolocation>:

<!-- Precisely autolocate and follow the user -->
<geolocation accuracymode="precise" autolocate watch>
  <!-- Render this when <geolocation> is unsupported -->
  <button id="fallbackButton">Use precise location</button>
</geolocation>

That is, of course, not including the JavaScript side of <geolocation> nor the Geolocation (JavaScript) API fallback. If you just want the full code then you’re looking for the getCurrentPosition() version and watchPosition() version. Note that geolocation doesn’t work in insecure contexts, so while the logic is sound, the CodePen demos won’t actually work. They’re raw-logic templates anyway, not fully working demonstrations.

Anyway, let’s get into the JavaScript of it all, starting with the JavaScript that sits on the other side of that <geolocation> markup.

Handling the <geolocation> data with JavaScript

First, we want to make sure that <geolocation> is supported with if ("HTMLGeolocationElement" in window). If it is, then we select it with const geoElement = document.querySelector("geolocation").

Unfortunately, we then have to dive into the most complex part of <geolocation> — it’s validity — where the isValid property returns true or false and the invalidReason property returns "" (an empty string) or an enumerated value stating the reason.

These reasons mostly come down to developer oversight, so users shouldn’t encounter these ‘blockers’, but if they do, the <geolocation> button will be disabled. Here are the scenarios in which that can happen (note that the blockers are ordered by severity, and that invalidReason only returns the most severe one):

• illegal_subframe: the <geolocation> element is nested within a <fencedframe> or insecure <iframe> (the latter of which is why the CodePen demos don’t work)
• unsuccessful_registration: the page has more than three <geolocation> elements
• recently_attached: the <geolocation> element has only recently been attached to the DOM (this blocker expires fairly quickly)
• intersection_changed: the <geolocation> element is moving
• intersection_out_of_viewport_or_clipped : the <geolocation> element isn’t within the viewport fully
• intersection_occluded_or_distorted: something is obscuring the <geolocation> element
• style_invalid: the <geolocation> element is styled in a way that isn’t allowed (more on this later)

As you can see, these blockers are permanently avoidable as long as we catch and fix them. Let’s have a proper look at how invalidReason reports these blockers, though.

As the JavaScript comment below describes, isValid always returns false at first, while invalidReason returns recently_attached. This basically disables the <geolocation> button for a fraction of a second to prevent clickjacking. That is, unless a blocker of higher severity applies. We don’t actually need the line below, it’s there just to show you how <geolocation> will never be valid when the page loads.

/* At first, isValid === false and invalidReason === "recently_attached"
unless isValid === false and invalidReason === "a reason of higher severity" */
console.warn(`isValid: ${geoElement.isValid}, invalidReason: ${geoElement.invalidReason}`);

If <geolocation> then becomes invalid for a more permanent reason, isValid will obviously remain false, so we can’t use the validationstatuschange event listener here. However, we can wrap the line in setTimeout() (as below). This will either log a new blocker into the console, or log that isValid is true (in which case invalidReason will be an empty string).

/* After ~300ms, when <geolocation> is no longer ‘recently attached’ (to the DOM)
either isValid === true and invalidReason === "" (an empty string)
or isValid === false and invalidReason === "the reason with the highest severity" */
setTimeout(() => {
  console.log(`isValid: ${geoElement.isValid}, invalidReason: ${geoElement.invalidReason}`);
}, 300);

If the validation status changes later, then we can use the validationstatuschange event listener (again, as below). Note that if there are no persistent blockers, this will fire almost immediately as invalidReason switches from recently_attached to an empty string.

/* If the validity of <geolocation> changes */
geoElement.addEventListener("validationstatuschange", () => {
  if (geoElement.isValid) {
    /* <geolocation> is valid (if there aren’t any blockers,
    it will become valid after it’s no longer ‘recently attached’ */
  } else {
    console.error(`<geolocation> invalid: ${geoElement.invalidReason}`);
  }
});

Now that you know how to debug the validation status and permanently fix any persistent blockers, let’s talk about the permission status.

We’re given a few properties and events to work with:

• initialPermissionStatus: a property that returns denied, granted, or prompt (i.e., neither) based on the permission status when the page first loaded
• permissionStatus: the current permission status
• promptaction: an event that fires when the user denies or grants permission from the <geolocation> permission prompt dialog
• promptdismiss: fires when the user dismisses the dialog, in which case the permissionStatus remains unchanged

/* Determine the initial permission status */
if (geoElement.initialPermissionStatus === "denied") {
  /* The user previously denied permission */
} else if (geoElement.initialPermissionStatus === "granted") {
  /* The user previously granted permission */
} else if (geoElement.initialPermissionStatus === "prompt") {
  /* The user hasn’t made a choice */
}

/* If the user denies or grants permission */
geoElement.addEventListener("promptaction", () => {
  if (geoElement.permissionStatus === "denied") {
    /* The user denied permission */
  } else if (geoElement.permissionStatus === "granted") {
    /* The user granted permission */
  }
});

/* If the user dismisses the prompt */
geoElement.addEventListener("promptdismiss", () => {
  if (geoElement.permissionStatus === "denied") {
    /* The permission state remained denied */
  } else if (geoElement.permissionStatus === "granted") {
    /* The permission state remained granted */
  } else if (geoElement.permissionStatus === "prompt") {
    /* The permission state remained prompt */
  }
});

That being said, I honestly don’t know what we’d need any of that for. If the user previously denied permission, for example, the <geolocation> permission prompt dialog would enable the user to recover from that automatically:

This is in contrast to the older Geolocation API, which is unlikely to help users recover. In this case we need to read the permission status, manage the state of the component accordingly, and provide recovery instructions so that users can grant access manually, but <geolocation> takes care of all of that.

What you will need is the new location event, which fires whenever the browser passes location data (geoElement.position in this case) or error information (geoElement.error) to us.

Then, in the event listener callback, assuming that geoElement.position is truthy, we can access position.coords and position.timestamp, synthesizing the location data like this:

/* If the browser passes location data or error information */
geoElement.addEventListener("location", () => {
  /* If location data */
  if (geoElement.position) {
    /* Synthesize the data */
    const {
      latitude,
      longitude,
      altitude,
      accuracy,
      altitudeAccuracy,
      heading,
      speed
    } = geoElement.position.coords;

    const timestamp = geoElement.position.timestamp;
  } else if (geoElement.error) {
    /* If error information */
  }
});

However, if geoElement.error is truthy, we can access error.message (that’s for us to log into the console) and error.code, which is much more suitable for error handling.

In short, there are three possible error codes, each with an associated constant so that we don’t need to remember what each error code represents. So 1 represents PERMISSION_DENIED, 2 represents POSITION_UNAVAILABLE, and finally, 3 represents TIMEOUT, and then we just evaluate them like this:

/* If the browser passes location data or error information */
geoElement.addEventListener("location", () => {
  if (geoElement.position) {
    /* If location data */
  } else if (geoElement.error) {
    /* If error information */
    console.error(`<geolocation> error: ${geoElement.error.message}`);

    if (geoElement.error.code === geoElement.error.PERMISSION_DENIED) {
      /* No HTTPS or server misconfiguration */
    } else if (geoElement.error.code === geoElement.error.POSITION_UNAVAILABLE) {
      /* No location source (GPS satellite or nearby Wi-Fi network/cellular tower) */
    } else if (geoElement.error.code === geoElement.error.TIMEOUT) {
      /* Location source detection or hardware took too long */
    }
  }
});

PERMISSION_DENIED means that the website isn’t being served over HTTPS (the browser denied permission), or that there’s some kind of server misconfiguration (the server denied permission), but those two errors are permanently fixable and shouldn’t occur in production.

The only way to deny permission (as far as I’m aware) is to block location access from the browser settings, then click on the <geolocation> button, then choose to continue denying. In my opinion, that’s not likely to happen and doesn’t warrant an error message anyway. There isn’t a denial mechanism for OS-level blocks so as not to make the impression that the browser can enforce one. In short, I don’t think we need to do anything for PERMISSION_DENIED.

And to clarify, because <geolocation> is user-invoked, <geolocation> itself never sets the permission status to denied (again, as far as I know).

POSITION_UNAVAILABLE means that the device can’t detect a location source (nearby Wi-Fi networks and cellular towers as well as GPS satellites) to determine the location. Using a VPN or visiting the website via an in-app browser could cause this error too, so this is the trickiest error to convey to users.

TIMEOUT means that the location source detection or hardware took too long, and that users should try again.

How you communicate errors to users is totally up to you.

Falling back to the Geolocation JavaScript API

Ready for round two? Now we’re going to do the same thing but with the aging Geolocation API, which is supported in every browser, but kind of a headache.

This is where we’re at currently:

/* If <geolocation> is supported */
if ("HTMLGeolocationElement" in window) {
  /* What we covered in the previous section */
} else {
  /* What we’re focusing on now (the fallback) */
}

Within that else block, which runs when <geolocation> isn’t supported, we start off by selecting the fallback button (const fallbackButton = document.querySelector("#fallbackButton")). If you recall, this is nested within <geolocation> so that it’s ignored when <geolocation> is supported.

After that we create a function (updateState()) that manages the component state and provides recovery instructions. As arguments we supply the state as a string (‌granted, ‌prompt, or ‌denied, corresponding with the permissionStatus), and optionally, statusMessage, which’ll be used to convey status messages to the user. I don’t want to make any assumptions about your component, so how you convey the statusMessage and expand upon updateState() is up to you.

If state === "denied", we disable the button with fallbackButton.disabled = true and provide some kind of recovery instruction of which should be passed as the second argument of the function. The reason why we disable the button is that this Geolocation API isn’t user-invoked, so to protect the user from spam requests, the browser can suppress requests and send the API straight to jail without passing go, triggering PERMISSION_DENIED. Additionally, if we make the API user-invoked (as we have), users can spam the button themselves and basically shadowblock themselves, but disabling the button fixes that.

If state === "granted" or state === "prompt", we can enable the button (fallbackButton.disabled = false).

Now is a good time to mention that the earlier JavaScript code for the <geolocation> element works regardless of whether the element has the watch attribute or not. However, when using this older Geolocation API, there are two additional things that we need to take care of when trying to keep track of the user’s location continuously. The first thing is the watcher ID, which is returned by the watchPosition() method. Knowing this ID enables us to clear the watcher before registering a new one, which is a must-do for performance reasons.

So we let watcherID = null for now, and then we create the function that attempts to get the location (getLocation()), and the first thing that we do within that function, assuming that watcherID !== null (meaning that it’s been set before), is clear the watcher using navigator.geolocation.clearWatch(watcherID) and make watcherID = null again:

/* A function for getting the location */
const getLocation = () => {
  /* If a watcher has already been registered */
  if (watcherID !== null) {
    /* Unregister it */
    navigator.geolocation.clearWatch(watcherID);
    watcherID = null;
  }
}

Then we disable the button using fallbackButton.disabled = true to, again, prevent spam clicks. If you want to bake some kind of loading indicator in, feel free to, but <geolocation> doesn’t.

After that we call navigator.geolocation.watchPosition(), setting watcherID to the returned watcher ID. This method has three parameters — success, error, and options.

watcherID = navigator.geolocation.watchPosition(
  (position) => {
    /* Success */
  },
  (error) => {
    /* Error */
  },
  {
    /* Options */
  }
);

For the success callback function we synthesize the location data similarly to last time, then call updateState("granted").

For the error callback function (optional but highly recommended) we clear the watcher and, again, make watcherID = null, but otherwise run the same error handling logic that <geolocation> runs. However, there are more circumstances in which the errors can occur.

For example, because watchPosition() and getCurrentPosition() aren’t necessarily user-invoked, there are more scenarios in which users are able to deny access, triggering the PERMISSION_DENIED error. Accordingly, we should call updateState("denied", "Permission denied (try this or that)"), offering a useful status message and clear recovery instructions.

Similarly, POSITION_UNAVAILABLE can also be triggered by an OS-level block, since not all web browsers catch this during the permission prompt dialog. updateState("prompt", "Position unavailable (try this or that)") is what we’re looking for this time.

Finally, another scenario that doesn’t occur with <geolocation> but does with this Geolocation API, is that if the browser prompts the user to grant permission at the OS-level, but then the user cancels their request, that can trigger the TIMEOUT error. Either way, call updateState("prompt", "Request timed out (try this or that)”), once again tweaking it to your liking.

As you can see, the error reporting isn’t the best. Sometimes the error isn’t identified correctly, and even when it is, the error can occur for various reasons, which makes it difficult for us to convey a useful status message and clear recovery instructions. <geolocation> handles this better — the errors are identified correctly, and the nature of <geolocation> ensures that certain errors never occur to begin with. But why the error categories? Why not tell us exactly what went wrong?

Well, the reason is to make fingerprinting more difficult, and while we can totally put in the extra work to pinpoint the exact problem, simply stating what happened and what the user should do next is perfectly fine. Of course, error.message tells us more than error.code does, but the messages can be a bit vague and differ in every web browser, so we can’t read them or even output them reliably.

Anyway, the optional third parameter expects an object where we can set:

• enableHighAccuracy: true or false
• timeout: 20000 (20 seconds) is reasonable if enableHighAccuracy: true, 3000 - 5000 otherwise
• maximumAge: 0 for turn-by-turn navigation, 5000 - 10000 (5-10 seconds) for live tracking, 300000 - 600000 (5-10 minutes) for frequent updates (e.g., weather)

I’d rather that the web browser choose the timeout and maximumAge for us, especially considering the impact that they have on the TIMEOUT error and device battery, but of course, that’s exactly what <geolocation> does.

/* Attempt to get the location and store the returned ID */
watcherID = navigator.geolocation.watchPosition(
  /* If location data is passed (like before) */
  (position) => {
    /* Synthesize the data (again, like before) */
    const {
      latitude,
      longitude,
      altitude,
      accuracy,
      altitudeAccuracy,
      heading,
      speed
    } = position.coords;

    const timestamp = position.timestamp;

    /* And update the state */
    updateState("granted");
  },

  /* If error information is passed (yep, like before) */
  (error) => {
    console.error(`Geolocation error: ${error.message}`);

    /* Again, unregister the watcher (if necessary) */
    if (watcherID !== null) {
      navigator.geolocation.clearWatch(watcherID);
      watcherID = null;
    }

    if (error.code === error.PERMISSION_DENIED) {
      /* No HTTPS, server misconfiguration, or the user denied access */
      updateState("denied", "Permission denied (try this or that)");
    } else if (error.code === error.POSITION_UNAVAILABLE) {
      /* No location source (GPS satellite or nearby Wi-Fi network/cellular tower) or OS-level access */
      updateState("prompt", "Position unavailable (try this or that)");
    } else if (error.code === error.TIMEOUT) {
      /* Location source detection or hardware took too long, or the user canceled their request */
      updateState("prompt", "Request timed out (try this or that)");
    }
  },
  {
    enableHighAccuracy: true,
    timeout: 20000 /* 20 seconds because enableHighAccuracy: true */,
    maximumAge: 0 /* 0 seconds because we’re demanding high accuracy */
  }
);

After that we need to query the permission status using the Permissions API (navigator.permissions.query({ name: "geolocation" }).then((permissionStatus) => { /* ... */ })), and then execute all of the aforementioned logic based on that.

If permissionStatus.state === "granted", we call getLocation(), which is essentially what the autolocate attribute does. If you don’t want autolocation, simply delete this part. If it’s anything else, we basically determine the initial state by calling updateState(permissionStatus.state).

/* Query the permission status */
navigator.permissions.query({ name: "geolocation" }).then((permissionStatus) => {
  /* Equivalent to the autolocate attribute */
  if (permissionStatus.state === "granted") {
    getLocation();
  } else {
    /* React accordingly */
    updateState(permissionStatus.state);
  }
});

Finally, make the button respond to clicks:

/* If the user clicks the fallback button */
fallbackButton.addEventListener("click", () => {
  getLocation();
});

If we only want to get the user’s location once (rather than watch it continuously), these are the modifications that we need to make:

• Remove everything related to the watcherID
• Swap watchPosition() for getCurrentPosition()
• Provide different settings for the options parameter

Note that the change event, which could help us update the state whenever the user changes their browser-level permission status, doesn’t fire in Safari. Besides, the standard browser behavior is to ask users to refresh the page, so let’s stick with that.

One more thing — I wanted the button to say “Refresh precise location” and “Getting precise location…” at certain points, but <geolocation> doesn’t do this, so I didn’t either. That’s up to you, though.

Styling the <geolocation> element

<geolocation> has a :granted pseudo-class. If we throw :not(:granted) into the mix, we can target the prompt/denied states too:

geolocation {
  &:granted {
    /* Permission granted */
  }

  &:not(:granted) {
    /* Permission not granted */
  }
}

With the Geolocation API, we can toggle classes as needed to achieve the same effect, but honestly, I’ve never felt compeled to style such a button in this way. Personally, I’d like to be able to change the icon and text (maybe this is something that you can bake into the updateState() function), but this is one of the things that the <geolocation> element outright forbids.

Before we dive into all that, here’s a rundown of <geolocation> rules stated by Google’s explainer and Mozilla’s explainer:

• There must be sufficient color contrast
• The alpha channel must resolve to 1 (so no transparency)
• The minimum and maximum width, height, and font size must be respected
• Negative margins and outline offsets aren’t allowed either
• Distortion effects — including linear gradients — are banned

It’s also worth noting that some of these rules function like guardrails (for example, you physically can’t style the height above 50px), whereas others cause invalidReason to return style_invalid and the <geolocation> button to be disabled.

Some of the rules seem to have changed (or are currently bugged). <geolocation> doesn’t respect prefers-color-scheme either, but it’s a developing feature, so I’m not going to comment on all of that too much. I’ll just state what I do and don’t like:

• I don’t like that the button becomes disabled because of a style (guardrails are better, but I don’t really like either)
• I don’t like the forced icon and text, and I’m also not too happy about not being able to use gradients or corner-shape
• I can make peace with everything else because I’d normally design within those guardrails anyway
• The text being localized into different languages is very cool, but it’s a first for web standards and I don’t currently enjoy that it’s a thing for only these permission buttons

While I obviously support preventing web authors from tricking users into giving away their location, I think it’d be better if <geolocation> were fully styleable and the permission prompt dialog be ultra clear about what the user is about to commit to.

Even though I can style the background, color, border, border radius, and box shadow how I’d want them (as in the image below, which is most of what I’d want), this feels like a step back towards unstyleable controls. Having said that, this approach means well (extremely well), so I can’t wait to see where this goes (and frankly, to be able to throw the aging Geolocation API in the bin).

What now? What else?

When all web browsers support <geolocation>, the user experience and developer experience will improve dramatically.

But that’s not all!

What was once the <permission> element is now the <geolocation> element, <install> element (which facilitates the installation of Progressive Web Apps), <usermedia> element (which facilitates access to the user’s camera and/or microphone), and <camera> and <microphone> elements (which facilitates access to them individually).

All of these are being trialed in Chrome as part of a larger initiative to improve the process and experience of requesting permission, which is bloody great, in my opinion.

On the web, text highlights are a good way to lay emphasis on text fragments through good ol’ CSS. From ::selection for styling selected text to ::target-text which styles highlighted text from Google searches, and in my opinion, CSS’ most powerful pseudo-element for highlighting: ::highlight() which applies a custom highlight to a text fragment.

In this article, we will look into how the ::highlight() pseudo-element works, the API behind this pseudo-element, and explore a fallback feature for this technology because it relies heavily on JavaScript (JS).

See the Pen ::highlight() demo: pure text-shadows by Andy Bell (@piccalilli) on CodePen.

The CSS Custom Highlight API

Typically, a highlight or highlighted text is what you’d see during web searches or when you what to select a text fragment to copy, or even when you make a mistake in a word processor (the squiggly red underlines). In CSS, you can achieve these through the highlight pseudo-elements like::search-text, ::selection, ::spelling-error , and ::grammar-error . But, what about plain highlights like the demo above? That’s where the CSS Custom Highlight API comes in.

The CSS Custom Highlight API is an API for text highlighting on a range of text using JavaScript and CSS. It extends the pseudo-elements for highlighting (::search-text , ::selection, ::spelling-error ) and lets you customize text fragments with ::highlight() and JavaScript. ::highlight() is what will be our focus for this article, and how we can programmatically highlight text and its fragments using JavaScript and CSS.

How ::highlight() works

To create highlighted text like in the initial example, you need to know 4 total steps, which include:

1. Creating the highlight buckets by creating instances of the Highlight() class
2. Register each highlight instance into CSS.highlights
3. Create Range() objects each with different points on the text for highlighting and add Range() objects to its highlight instances
4. Style with ::highlight() pseudo-element

Before we move on with an example, let me explain something because this is where it might get tricky. What we do around here is build with progressive enhancement in mind first. So the first question you should ask before anything is “what happens when JS fails?”. Well, I’m glad you asked.

Let’s say, for our example, we want to create two highlight objects and use that to style a simple poetic text that reads “fire and ice live inside every word.” Because we care about our users, we set each text for highlight with the <mark> HTML tag setting the class attribute to either gold or ice , depending on the highlighting style we wish the text to have. This acts as a fallback highlight style in case our JavaScript fails or the browser doesn’t support custom highlighting.

We also apply an id to them in case JS is available too for our CSS Custom Highlight API. With all that in mind, our HTML would look like this:

<main>
  <h1>Two Highlights Demo</h1>
  <p id="line">
    <mark id="fire" class="gold">fire</mark> and
    <mark id="ice" class="ice">ice</mark> live inside 
    <mark id="every" class="ice">every</mark> 
    <mark id="word" class="gold">word</mark>
  </p>
</main>

Then, we proceed to query each tagged word in our JS applying the firstChild property to each of them of get the element’s first child node which we will use later:

const fireNode = document.querySelector("#fire").firstChild;
const everyNode = document.querySelector("#every").firstChild;
const iceNode = document.querySelector("#ice").firstChild;
const wordNode = document.querySelector("#word").firstChild;

Finally, we can proceed with the steps on creating a custom highlight in CSS.

Create instances of Highlight() class

In order to create a custom highlight, the first step is to create an instance of the Highlight() class which will house the highlight styling we want a text or text fragment to have. For our demo, we’ll be creating two highlight objects named using the Highlight() class. One to give a golden color representing fire and the other to give a blue color representing ice:

const goldHL = new Highlight();
const iceHL = new Highlight();

Register each highlight instance in CSS.highlights

Next, we register the created highlight instances in the HighlightRegistry via CSS.highlights set() method. We map a valid CSS identifier to the instance for CSS styling later.

CSS.highlights.set("hl-gold", goldHL);
CSS.highlights.set("hl-ice", iceHL);

Create Range() objects each with different points on the text for highlighting

In this step, we will be creating a Range() object for each text fragment we queried earlier for highlighting. We will then apply the highlight we want on each selected text. For the first word “fire”, we create a Range() object called r1 , and we set the start node to the first letter “f” using setStart on r1 . setStart() accepts two values. It accepts the node we’re targeting (in our case for “fire”, its fireNode ) and the index of the text on the node.

Now, because we want to target the whole text “fire”, we have to also set where the range will stop. And this will be set using setEnd() . setEnd() accepts two values like setStart() on the range object (r1). It accepts the node we’re targeting (fireNode ) and the index of the end text “e” (as in the “e” in “fire”) using fireNode.textContent.length - 1 which gives us the last index of the text.

Finally, we add the range object into the set instance.

const r1 = new Range();
r1.setStart(fireNode, 0);
r1.setEnd(fireNode, fireNode.textContent.length - 1);
goldHL.add(r1);

This step is repeated for everyNode, iceNode, and wordNode. Typically, you’d want to use a loop for this, but because this is really small, writing it in a specific manner will suffice, especially to help you understand how this works too.

const r2 = new Range();
r2.setStart(wordNode, 0);
r2.setEnd(wordNode, wordNode.textContent.length - 1);
goldHL.add(r2);

const r3 = new Range();
r3.setStart(iceNode, 0);
r3.setEnd(iceNode, iceNode.textContent.length - 1);
iceHL.add(r3);

const r4 = new Range();
r4.setStart(everyNode, 0);
r4.setEnd(everyNode, everyNode.textContent.length - 1);
iceHL.add(r4);

Style with ::highlight() pseudo-element

Remember how we said we should think progressive enhancement first? Well, in order to achieve that for this demo in particular, we need to style the <mark>ed highlighted text first, then, we style the ::highlight() pseudo-element. For that to work, we styled text marked with the gold class to be golden in oklch() with a glowy text shadow of similar color. We style text <mark> ed with the ice class to be blueish in oklch() with a glowy text shadow of similar color:

mark {
  background: none;
}

mark.gold {
  color: oklch(88% 0.16 75);
  text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
}

mark.ice {
  color: oklch(82% 0.1 215);
  text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
}

See the Pen ::highlight() demo: two highlights without `::highlight()` by Andy Bell (@piccalilli) on CodePen.

Viola! (or how do they say it?) It looks amazing! 🤩

Even without the styled ::highlight() , it works out pretty well. But, that’s not our only aim though. We still need to add the styling for both our highlight objects.

::highlight(hl-gold) {
  color: oklch(88% 0.16 75);
  text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
}

::highlight(hl-ice) {
  color: oklch(82% 0.1 215);
  text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
}

Done! It’s pretty much the same styling we did for our <mark> tag classes and in case JS fails or the browser doesn’t support it, we wrap the ::higlight() pseudo-elements in a @supports container:

@supports selector(::highlight(h1-gold)) {
  ::highlight(hl-gold) {
    color: oklch(88% 0.16 75);
    text-shadow: 0 0 40px oklch(65% 0.22 75 / 0.4);
  }

  ::highlight(hl-ice) {
    color: oklch(82% 0.1 215);
    text-shadow: 0 0 40px oklch(60% 0.18 215 / 0.4);
  }
}

See the Pen ::highlight() demo: two highlights with fallback by Andy Bell (@piccalilli) on CodePen.

Will you be using ::highlight()?

I know for sure I will be using this feature in my work. This article explained highlighting in CSS, the CSS Custom Highlight API, and how ::higlight() works in CSS with a fallback provision, for when JavaScript isn’t available or the browser doesn’t support it.

If you’re looking to read up more about the CSS Custom Highlight API, MDN has a good guide on the topic for you.

• Zero-dependencies
• ~2kb minifed+gzipped
• Uses CSS ::highlight(token-name), not spans
• Leverages Textmate’s language grammars
• Human-readable light-dark() themes
• All languages/grammars loaded on-demand
• Moves all non-highlight functionality to a <micro-lighter> custom element

At some point I broke syntax highlighting on my Jekyll blog. I’ve used a handful of syntax highlighters over the years (Highlight.js, PrismJS, Rouge, Shiki, etc, etc) and I’ve felt the trade-offs between different client-side and server-side implementations. Faced with picking another, I knew I wanted to explore Bramus’s technique of syntax highlighting with the CSS Custom Highlights API.

There’s some limitations with the CSS ::highlight() pseudo; no italics, no bold, no font swapping – but otherwise it’s pretty cool syntax to idiomatically express “I want to highlight this token” via CSS instead of injecting spans everywhere. Using the Highlight API means I avoid any DOM mutation and the scope of the library shrinks down to: scan code blocks using regex patterns and send CSS.highlights.set(category, textRanges) to highlight the code blocks.

I don’t need much syntax highlighting on this site. Not all posts have code and my code samples are a whole fifteen lines long at best. My struggle is that I swap languages often. I’ll do HTML, CSS, and JavaScript all in the same post. A little bash here, a little ruby there, some markdown as a treat. Using so all those languages grew the complexity beyond the limits of my regex-fu, so I decided to lean on Textmate’s established collections of patterns used by VS Code. And before I knew it, my little highlighter could do almost any language.

Knowing I use different languages often, one principle I established was that all language grammars should be auto-loaded on-demand to reduce configuration and bundle size. That way you only pay for what you use.

Inspired by PrismJS’s simplified token categories I flattened down Textmate’s granular token categories to a more human-friendly set, making it easier to style. In addition to that, one enormous nit-pick I have with codeblock styling is that light and dark themes are separate entities, so I merged them into one theme using light-dark().

The last big opinion I baked in was that I wanted the syntax highlighter to do one job: infer language and highlight code in that language. With that a guideline, I moved all extra functionality (like line-numbers, etc) over to a web component. The vanilla web component adds about ~1 KiB in size, but co-locating UI into a UI primitive like native custom elements feels right and the ShadowDOM encapsulation makes it easy to separate the code from the presentational UI.

Obviously, I’m a web component pervert but it feels like a great separation of concerns versus trying to cram everything into core library.

Try it out

To get started on your site, I’d use the self-initializing minified bundle, but I’m also shipping ESM and a web component.

npm install microlighter

<script type="module" src="path/to/microlighter/microlighter.min.js"></script>

Like I said above, not all my posts have syntax highlighting, so I even wait to import the script unless I know there’s a page with code on it.

if(document.querySelector('pre>code').length) {
	import('path/to/microlighter/microlighter.min.js');
}

You can use the ESM version if you’re going to do something fancy yourself:

import { highlightAll } from 'microlighter'

highlightAll({
	selector: 'pre.onlyTheseGetHighlights'
})

And you can also use the web component if you want those extra features I talked about:

<micro-lighter data-syntax-theme="github" line-numbers controls="copy">
  <pre><code>Code goes here</code></pre>
</micro-lighter>

Web component classes are pretty extendible too so if I don’t support something you need, you can “fork” it by extending the base class and adding your own features.

Lastly, you can use one of the pre-supplied themes or roll your own. The basic structure is:

/**
 * Setup semantic `--syntax-*` tokens 
 * @value background | foreground | comment | keyword | 
 * operator |string | constant | function | type | variable |
 * property | tag | selector | inserted | deleted
 */
[data-syntax-theme="my-theme-name"] {
  color-scheme: light dark;

  /* Code block tokens */
  --syntax-background: light-dark(#f8f8f8, #3a3a3a);
  --syntax-foreground: light-dark(#3a3a3a, #f8f8f8);
  
  /* Highlight tokens */
  --syntax-comment: light-dark(#6e7781, #8b949e);
	--syntax-function: light-dark(#8250df, #d2a8ff);
  /* ...etc... */
}

[data-syntax-theme="my-theme-name"] pre:has(code) {
	background-color:var(--syntax-background);
	color:var(--syntax-foreground)
}

::highlight(comment) { color: var(--syntax-comment) }
::highlight(function) { color: var(--syntax-function) }
/* ...etc... */

And that’s MicroLighter. If you end up using it and trying it out, let me know what you think.

Five years ago, I shared the HTML boilerplate I use for most of my projects. Since then, a lot has happened in HTML. It's time to give it an update.

My boilerplate

This is the final document. Scroll down for details.

<!DOCTYPE html>
<html lang="en" class="no-js">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width">
  <meta name="text-scale" content="scale">

  <title>Unique page title - My Site</title>

  <script src="/js/render-blocking-scripts.js"></script>
  <script>
    document.documentElement.classList.replace('no-js', 'js');
  </script>

  <link rel="stylesheet" href="/css/styles.css">
  <link rel="stylesheet" href="/css/print.css" media="print">

  <script src="/js/non-render-blocking-script.js" type="module"></script>

  <link rel="icon" href="/favicon.ico">
  <link rel="icon" href="/favicon.svg" type="image/svg+xml">
  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
  <link rel="manifest" href="/site.webmanifest">

  <link rel="canonical" href="https://web.site/page">
  <link rel="alternate" type="text/markdown" href="https://web.site/page.md">
  <link rel="me" href="https://mastodon.social/@username">
  <link rel="site.standard.publication" href="at://[DID]/site.standard.publication/[RKEY]">

  <meta name="description" content="Page description">
  <meta property="og:image" content="https://web.site/sm.jpg">
  <meta property="og:url" content="https://web.site/page">
  <meta name="theme-color" content="#FF5302">
  <meta property="fediverse:creator" content="@user@mastodon.social" >
</head>

<body>
  <!-- Content -->
  <script src="/js/non-render-blocking-script.js"></script>
</body>
</html>

Line by line explanation

Doctype required

<!DOCTYPE html>

Since HTML is a living standard, we no longer need different doctypes, but we still have to define one for compatibility.

Natural language required

<html lang="en">

The lang attribute is one of the most important attributes in HTML, because it’s powerful and responsible for many things. You can read more about it in On Use of the Lang Attribute and The lang attribute: browsers telling lies, telling sweet little lies. Applied to the html element, it defines page's natural language. It contains a single “language tag” in the format defined in Tags for Identifying Languages (BCP47), for example, en for English, de for German, or fr for French.

• lang Language tag syntax MDN

Selector for no JavaScript environments optional

<html class="no-js">

I use the no-js class in case I want to apply styling to specific components in browsers that don’t support JavaScript or in browsers where the user has disabled JavaScript. This class will be removed in browsers that support and execute JavaScript. Even if you don't believe that websites should work without JavaScript in 2026, this class can still be useful for optimizing the rendering of web components before they're defined.

Character encoding required

<meta charset="UTF-8">

This attribute declares the document’s character encoding. Leaving it off might cause specific characters to display incorrectly in some browsers.

It must come before the <title> element to avoid faulty characters in the page title.

Viewport essential

<meta name="viewport" content="width=device-width">

The viewport meta tag allows us to adjust the viewport width, which is necessary for responsive web design. width=device-width sets the viewport width to the device's width. (That's a simplified explanation. For details, see the MDN page for this meta tag.)

Setting initial-scale=1, which controls the zoom level when the page is first loaded, shouldn't be necessary anymore. We only needed it for older versions of iOS and Android. The thing is, though, people keep telling me they think there are still edge cases where it's needed, but they don't remember which ones. Anyway, I don't think it's necessary, but if you want to play it safe, it doesn't hurt to add it.

<meta name="viewport" content="width=device-width, initial-scale=1">

The viewport meta tag should come as early as possible in the document to ensure proper document rendering.

Text scaling optional

<meta name="text-scale" content="scale">

By default, mobile browsers don't respect the text size set in the operating system. This new meta tag changes that.

Don't just copy and paste this line. It might break your layouts. You have to test whether the content still looks okay when you increase the text size on your mobile operating system.

• Try text scaling support in Chrome Canary - Josh Tumath
• A new meta tag for respecting text scaling on mobile

The page title required

<title>Unique page title - My Site</title>

The unique title of the page. It’s displayed in many places, for example, on the browser tab, in search engine results, when you save a page as a bookmark, etc.

• Provide informative, unique page titles
• Accessible page titles in a Single Page App

General render-blocking JS optional

<script src="/js/render-blocking-scripts.js"></script>

Render-blocking JavaScript for the site. It comes before synchronous CSS because CSS blocks loading of the JavaScript. Put JavaScript without async, defer, or type="module" only in the head if you need the JavaScript parsed and ready before the rest of the page loads.

JavaScript support optional

<script>
  document.documentElement.classList.replace('no-js', 'js');
</script>

As mentioned earlier, I use this technique to create a dedicated class for the page state when JavaScript is disabled or unsupported. This solution is more reliable than the scripting meta tag and can be used alongside <noscript>.

General CSS optional

<link rel="stylesheet" href="/css/styles.css">

Render-blocking CSS for the site.

Print CSS optional

<link rel="stylesheet" href="/css/print.css" media="print">

People still print web pages, and I consider serving a print style sheet good UX. A good print stylesheet also saves paper and ink.

• I totally forgot about print style sheets

General non-render-blocking JS optional

<script src="/js/non-render-blocking-script.js" type="module"></script>

type=module implicitly defers the execution of the script after the document has been parsed, but before firing DOMContentLoaded event. For good performace try to default to this instead of adding render-blocking scripts.

Favicon essential

<link rel="icon" href="/favicon.ico">

A 32×32px favicon for legacy browsers (Safari supports SVG favicons starting with 26.0). The favicon.ico should be located at the root of your website. Usually that's enough for browsers to pick it up automatically. You don't need the link element, but based on my tests with iOS 18, as soon as you define an SVG icon, the browser no longer falls back to the favicon.ico file in the root; it just doesn't display any icon. If you want to ensure that older browsers still show the ICO file while newer browsers get the SVG, you have to define both link elements. If you don't care about older versions of Safari, it's fine to just link the SVG.

<link rel="icon" href="/favicon.svg" type="image/svg+xml">

Most modern browser support SVG favicons. The benefits of the favicon.svg are that it looks better when it’s scaled, because it’s a vector and not raster image, and we can add HTML and CSS to the SVG, which means that we can support dark mode.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80">
  <style>
    path {
      --fill: #153a51;
      fill: var(--fill);

      @media (prefers-color-scheme: dark) {
        --fill: #FFFFFF;
      }
    }
  </style>
  <path d="…"/>
</svg>

<link rel="apple-touch-icon" href="/apple-touch-icon.png">

The 180×180px icon Apple devices will use if you add the page to your home screen. According to my tests, simply having a file named apple-touch-icon.png at the root of your project is enough. You don't need the link element, but I've only tested this with a simulated iOS 18 and a real device running iOS 26. I don't know about other operating systems and devices. So it's probably best to just keep it in your HTML.

• How to Favicon in 2026: Three files that fit most needs

Manifest essential

<link rel="manifest" href="/site.webmanifest">

For Android devices we need a .webmanifest file, which provides browsers with the information where the icons needed for the home screen, dialogs, and the splash screen for PWAs or regular sites added to the home screen are located.

{
    "name": "My Website",
    "icons": [
        { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192" },
        { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512" },
        { "src": "/icon-512_maskable.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
    ]
}

The maskable variation of the icon is used when the icon is not displayed in a rectangular shape but, for example, in a circular one. The rule here is that your icon lives in a centered safe zone, which is approximately 80% of the size.

Canonical URL essential

<link rel="canonical" href="https://www.mywebsite.com/page">

Use the canonical link element to prevent SEO issues caused by duplicate content by specifying the original source for pages that are available on multiple URLs.

Link to Markdown optional

<link rel="alternate" type="text/markdown" href="https://web.site/page.md">

Link to a Markdown version of your page. LLMs work better with Markdown than with HTML, and serving content as Markdown significantly reduces token usage.

• Making your site visible to LLMs: 6 techniques that work, 8 that don't

Verification on Mastodon optional

<link rel="me" href="https://mastodon.social/@username">

This link tag can be used to verify that you actually own a page you've listed on your Mastodon profile.

That's not the only way to do it. You can also add rel="me" to a link to your profile anywhere on your website. Then you wouldn't need the link tag anymore.

<a rel="me" href="https://mastodon.social/@username">Mastodon</a>

Standard site optional

<link rel="site.standard.publication" href="at://[DID]/site.standard.publication/[RKEY]">

The link tag you need to publish on the atmosphere.

• Publishing on the Atmosphere with Standard.site - Piccalilli

Page description essential

<meta name="description" content="Page description">

The unique description of the page, for example, displayed on search result pages. It can be any length, but search engines truncate snippets to ~155–160 characters.

These days, search engines don't guarantee they'll use your description. They may use different content or create their own summary.

Preview image for social media, chats, etc. essential

<meta property="og:image" content="https://web.site/sm.jpg">

The image displayed when you share the link to a page on social media, chat applications, or other sites that scrape URLs.

• The Open Graph protocol

Canonical URL for social media essential

<meta property="og:url" content="https://web.site/page">

The canonical URL of the page. A required property for valid Open Graph pages. This tag is necessary to ensure that platforms don't cache separate entities of your websites when links include GET parameters. If someone shares a link with, for example, ?utm_source= it must not be treated as a separate entity. It's hard to tell wether there is a fallback to the canonical meta tag if the og:url meta tag doesn't exist. That's why I would include it. It's the same value as for the canonical meta tag.

Theme optional

<meta name="theme-color" content="#FF5302">

theme-color provides browsers with a CSS color to customize the display of the page or of the surrounding user interface.

This is currently only supported by Chromium based browsers on Android. From version 15 until 26, Safari also supported this meta tag, but starting with version 26, it either uses the body's background color or a color value from a position fixed element at the very top of the page.

• Define the Theme Color for Safari 26
• prefers-color-scheme in SVG favicons for dark mode icons

Author attribution optional

<meta property="fediverse:creator" content="@user@mastodon.social" >

This meta tag adds an additional line to links to your website posted on Mastodon, giving you credit.

For this to work, you have to add your domains to the allow list on Mastodon under Preferences -> Public profile -> Verification -> Author attribution.

General non-render-blocking JS optional

<script src="/js/non-render-blocking-scripts.js"></script>

Non-render-blocking JavaScript for the site.

This isn’t the absolute minimum, but it’s what I need in most sites I build. To round things up, I’ve added a bunch of tags you might need from time to time.

Other noteworthy elements

Dedicated title for Social Media optional

<meta property="og:title" content="Unique title">

The title used by URL scrapers on social media platforms like Bluesky or Mastodon. You only need this if you want the title in the preview to be different from the page title. If you don't define it, apps and websites default to the page title. If you define it, also define a dedicated Open Graph description, because some apps, such as Discord, won't pick up the standard meta description anymore.

Dedicated description for Social Media optional

<meta property="og:description" content="Unique description">

The description used by URL scrapers on social media platforms like Bluesky or Mastodon. You only need this if you want the description in the preview to be different from thes standard meta description.

Alt for preview images optional

<meta property="og:image:alt" content="Image description">

A description of the preview image. Whether the website or app uses it is really up to them. In my brief and incomplete tests, I found the situation very complicated.

• Bluesky ignores it.
• Mastodon respects it, but it's part of the card's accessible name. The link text of a preview card contains the description of the image, the title, and the description. Mastodon uses an empty alt if you omit the meta tag.
• Slack ignores it entirely.
• Discord respects it, but falls back to "Image" if you omit the meta tag.

I tried using an empty string, but it is also ignored by all the websites I tested. If you add alt text to the preview image, keep it short.

Type optional

<meta property="og:type" content="article">

The type of content you’re sharing, e.g. website, article, or video.movie. If you omit it, it defaults to website, which is what you want for most pages. Whether you see a difference when you change the type depends on the website or application rendering the preview. In my very limited testing, the only significant difference I saw was that if you set the type to article and added published and modified dates, Slack will display the published date and Signal the modified date.

<meta property="article:published_time" content="2026-08-01T09:00:00+02:00">
<meta property="article:modified_time" content="2026-08-03T14:30:00+02:00">

Language for social media previews optional

<meta property="og:locale" content="en_GB">

An optional Open Graph property. It defines the page's natural language. Bluesky ignores this, but Mastodon does not. If you don't define the locale, Mastodon will just fall back to the page's lang attribute, which I assume most applications will do too. I guess it only makes sense to define the locale if the language of the title and preview description is different from the language of the post.

Preloading optional

<link rel="preload" href="font.woff2" as="font" type="font/woff2" crossorigin>

Use preload if you want to ensure that specific resources are available earlier in the page lifecycle.

• Preloading content with rel="preload"
• Preload, Prefetch And Priorities in Chrome
• Prefetching, preloading, prebrowsing

RSS optional

<link type="application/atom+xml" rel="alternate" href="/feed.xml" title="My Blog - Manuel Matuzovic">

RSS feed for your site.

• The Wonderful World of Web Feeds

The document's author optional

<meta name="author" content="Manuel Matuzović">

Websites or apps may want to know who the author of the document is.

The notch optional

<meta name="viewport" content="width=device-width, viewport-fit=cover" />

By default, the content on a device like the iPhone is within a safe area kept away from the notch and rounded corners.

If this is an issue, you can opt out of that behavior and take up the entire screen edge-to-edge.

Viewport resize behavior optional

<meta name="viewport" content="width=device-width, interactive-widget=resizes-content">

This option allows you to control how the viewport resizes on mobile when the keyboard is shown. With resizes-content, not just the visual viewport, but also the layout viewport, resizes. This fixes an issue where sticky or fixed elements at the bottom of the screen would disappear when the keyboard is shown. I haven't used it yet, so I don't know how it affects UX, performance, or accessibility. I guess the best advice is to use this option only where you need it and test it properly.

• Control the Viewport Resize Behavior on mobile with interactive-widget

Color scheme

<meta name="color-scheme" content="dark light" />

You can use this meta tag to indicate to the user agent which color schemes the website supports.

If you want to learn more about the <head> element and its children, check out Josh Buchea’s fantastic repository HEAD.

Did I get anything wrong or did I miss anything? Please find me on social media or via e-mail.

Thanks

Thank you, Vale, Nathan, Šime, Thain, and Matt, for your feedback!

My blog doesn't support comments yet, but you can reply via blog@matuzo.at.

I can’t know for sure if that pause was deliberate but something triggered in my brain that reminded me of how we call folks who partake in medicinal substances “users”. The connotation of a drug “user” is often negative but it gave me a better understanding of what’s going on with some analogies to how drugs exist in society today.

On maturity

I’d like to think my relationship with drugs is fairly normal. The only recreational substance I’ve ever done is alcohol and only ever socially. I have a solid self-discipline that doesn’t give in easily to peer pressure. I also don’t immediately reach for drugs just for minor inconveniences nor do I believe pumping myself with antibiotics is a good idea since your body then depends on that over time. However, it doesn’t mean I’ve never taken drugs. I’ve taken stuff for headaches and more significant ones when prescribed.

Importantly, this is only my experience. I know there’s a large spectrum out there, from folks who are straight-edge and haven’t done anything to folks who could be considered junkies. There’s folks that take drugs to regulate their own issues, and folks who want to try new experiences. There’s all kinds of people with all kinds of backgrounds, beliefs, and situations they are going through.

On addiction

When you look at AI in the same lens, I think the bottom line is addiction. If you are in a situation where you cannot function without AI, this is a dependence that you don’t want to have. We’re seeing a lot of AI slop because people have an addiction. It’s basically a super performance enhancing drug that anyone can use. As Uncle Ben says to Peter Parker: “With great power comes great responsibility.” There are many people who are irresponsible with AI and cannot self-regulate. Some of these folks are in leadership positions that affect the livelihood of the folks around them. This is the challenge that society is facing today. I think we need to address this in the same way we might address someone who is abusing substances.

It takes a big person to recognize when they have a problem, and otherwise it’ll take help from others for folks to realize their abuse. It’s not healthy if you’ve thrown out all of your processes and experts in favor of the dopamine hit that AI will give you. You have to use it with self-control. I’m seeing some of the effects in peers, where token limits are being constrained. These folks feel helpless without it because they relied too heavily on the dependency.

On shame

By the same token, I don’t think it’s right to chastise someone for using AI. I feel this is akin to straight-edge folks who look down upon people recreationally drinking or vegetarians scolding meat-eaters. I don’t see AI as inherently bad. I think there’s good qualities to AI. An example I think about all the time is trying to understand how to get something done in a new tool. Before AI, I’d search on the Internet for something like creating an image mask in Affinity, only to find forum posts with people arguing about the best way to do it or YouTube videos that spend 10 minutes introducing themselves and the tool. Having something that cuts through all of the fat to unblock you is helpful. Especially if you are in the creative flow. Just think of all the times you had to side quest and get distracted from the main task because people put up unnecessary barriers to farm engagement or unknowingly tangent from the purpose. You’re still in learning mode, just with less friction.

For full transparency, each of the posts here on the blog has a random animal illustration associated with it. Each of these is generated with AI and has been for years. The animal images provide no value to the blog beyond matching the parody motif of the website’s design. If I wasn’t able to generate the drawings, it just means I might need to pivot. I’d have to weigh out the importance of continuing the style over the amount of time it would take to draw these animals myself. If I found that it isn’t worth it, which is likely the case, I’d just redesign the website. AI doesn’t define what I do, or drive the content on the site. I’m still writing every word by hand. That’s the value here. There’s areas where AI is helping. I see this the same as taking an Advil to get rid of a headache quickly instead of wasting time trying to sleep it off.

As another example, I’ve just started a newsletter at Design Systems House. While the short sentences found in the newsletter are AI generated, the links found inside are not. I could just send you a sterile list of links with zero AI involvement or I could dress them up with something that summarizes what you are getting; helping you determine if the link is worth your time to read without clicking it. Am I lazy for having AI summarize the links? Maybe. Or maybe I prefer redirecting my energy to the projects I’m sharing in that news.

I have empathy for users people. I care about the things I’m making and I think about how they affect people. I can’t please everyone, but I have confidence that my use of AI isn’t addiction. Maybe that’s exactly what an addict would say. But I do believe if AI were to disappear tomorrow, I could continue being creative because I’ve always had those skills. Not the Markdown files, the real expertise that I’ve gained through learning. I value being able to do this stuff no matter what.

Prompt responsibly.

But, to ensure this built-in control works well for everyone, it’s important to follow this single but essential rule: always provide text content or accessible text attributes for your option elements.

Every time that rule is broken, every time an option is styled to show a visual without any text and without any accessible fallbacks, three different problems get introduced all at once. The menu is harder to use for everyone, impossible to use with accessibility tools, and it becomes a completely broken experience in browsers that don’t support it yet.

When you remember to follow the rule, you’ll improve the user experience, support accessibility, and provide progressive enhancement so it works for people regardless of what browser they choose.

We’ll show you why following this mission critical rule gets you:

Better UX

Take this category filter from a photographer’s gallery site. The version below uses icons alone — a building, a flower, a hummingbird — to represent each category:

It looks clean. But a user who doesn’t immediately recognize what the hummingbird icon represents has no fallback. The closed select shows only an icon in the button, with no other hint of what’s currently selected. Add a text label to each option and the experience becomes immediately scannable. The selected state is readable at a glance, and every option is unambiguous:

The icons are still there. The labels make it readily decipherable for everyone.

Better accessibility

When a screen reader encounters an option with no text, the user may not hear a descriptive label for each option. Braille rendering and other assistive technology output may also be confusing. Text, even when hidden visually with a .visually-hidden class, stays in the accessibility tree and gives screen readers, braille displays, and speech recognition software something real to work with. If you use an icon as an <img>, add an alt or aria-label — or mark it decorative using alt="" and let the visible or visually-hidden label carry the meaning.

<option>
   <img src="bird.svg" alt="">
   <span>Wildlife</span>
</option>

The problem you solve isn’t just a compliance checkbox: it’s the difference between a visitor completing your form and someone abandoning it.

Better progressive enhancement

Customizable select is a new feature. Browsers that don’t yet support it fall back to the platform-native <select> — which is exactly the right behavior, as long as your options still make sense in that fallback state.

If you’ve removed text in favor of icons or swatches, a user on an older browser sees a dropdown full of empty options. The same is true when CSS fails to load at all: a slow connection, a corporate proxy stripping stylesheets, a user with custom styles enabled. Wrap your enhancements in @supports (appearance: base-select) and keep plain text as your baseline. Adding a swatch is an enhancement. Removing the color name to make room for it is a regression.

The rule for maximizing the power and utility of customizable select is simple: keep the text. You can hide it visually. You can make it tiny. You can position it off-screen. But it needs to be there. Icons, swatches, and illustrations are additions to an option — never substitutes for it. Follow that rule and the rest of customizable select is yours to play with.

Feedback

We love hearing from you. To share your thoughts, find our web evangelists online: Saron Yitbarek on BlueSky, Jen Simmons on Bluesky / Mastodon, and Jon Davis on Bluesky / Mastodon. You can follow WebKit on LinkedIn. If you run into any issues, we welcome your feedback on Safari UI (learn more about filing Feedback), or your WebKit bug report about web technologies or Web Inspector. If you run into a website that isn’t working as expected, please file a report at webcompat.com. Filing issues really does make a difference.

Under current U.S. hacking laws, a human can face criminal charges for breaking into someone else’s computer without permission. But when an AI agent autonomously hacks into a company’s computers, determining who is liable is much murkier.

The surprise admissions by OpenAI and Anthropic that their unreleased AI models autonomously hacked into several companies have upended our understanding of America’s computer hacking laws, prompting discussions over whether the companies could face legal reprisals.

You can add Meta to the list of companies that have done some light digital breaking-and-entering because they insufficiently secured an A.I. model. In any case, I am fascinated by the seemingly pervasive idea that obviously illegal things somehow become a grey area when a highly-valued A.I. company is responsible. Corporations now allegedly authorize mass piracy at the highest levels and use illicit movie rips as though it is just another day.

⌥ Permalink

Until recently, if you looked at most websites with a theme toggle^[1], you’d find three options: Light, Dark, and System.

Thankfully, these days the trend has shifted towards a simpler two-state toggle, but tri-state ones are still incredibly common.

The rationale sounds plausible: “System” is a different intent than “Light” or “Dark”! One is a policy (whatever my OS says, do that) The other is a value (dark, forever, I don’t care what my OS says.) Surely, users should be able to express that intent!

Except, real users don’t generally seek out dark mode toggles to express intent for things to stay as they are, they seek them out when things need to change.

Think of the user goal when browsing a website (as opposed to a separate Settings page, where three states are fine). E.g. on a documentation site, they may be there to look something up. On a landing page, they may be trying to evaluate whether the product is suitable for their needs.
On a media site, they may be there to read the news.
On a graphics app, they want to draw something.

One thing is for certain: tweaking the theme is not their primary goal ^[2]. To get in the mindset of tweaking the theme, something needs to be off. When things look right, users just move on with their actual goal instead of thinking about the theme.

The tri-state control is solving a largely imaginary user goal that is extremely rare among real users, and does not justify the additional complication and UX friction of a three-state toggle.

Worse, it forces the user to decide between choices that produce no visible difference, breaking the principle of feedback.

Yes, tri-state toggles are common. That doesn’t make them good. This essay explains why, and how to do better.

Tri-state toggles are implementation-driven UI

One of the most common UX mistakes is designing UI around the underlying data model instead of user goals. Good interfaces abstract away the underlying model and expose a model that aligns with user goals (unless of course these happen to coincide, which is rare).

This is exactly the case with tri-state dark mode toggles; exposing all three states is data model leaking into the UI.

Yes, there should absolutely be three states in the underlying implementation! But at any given point, one of them is irrelevant to the end-user.

Users cannot meaningfully express intent about problems they don’t currently have.

A dark mode toggle is a temporary comfort adjustment. When it comes to user goals, there are only two real states:

1. The website looks ok. The user moves on with their actual goal and doesn’t look for the toggle at all.
2. The website is too bright or too dark to be comfortable. The user wants to fix it.

You’re reading in bed, the page is a flashbang, you hit the toggle. You’re on a laptop outside and the dark theme is unreadable in sunlight, you hit the toggle. It’s situational, it’s immediate, and it’s usually about the environment you’re in rather than a considered long-term stance on color schemes.

A third state assumes a usage scenario where a user visits a website that looks perfectly fine, and still looks for a dark mode toggle to ensure it can continue to look fine in the future. Users do all sorts of weird things, so I won’t assert that this never happens, but it is not a natural user interaction, fueled by a real user goal. Even the strongest proponents of tri-state toggles I have spoken with either admit they have never done this, or bring up some extremely rare, weird one-off edge cases.

But what’s the harm?

One could argue that sure, the third state is not frequently needed, but surely it doesn’t hurt to have it there for the one user that will need it, right?

But a more complex UI has a cost. It increases cognitive load for interacting with the control and forces you towards certain UI design decisions.

A two-state toggle can be very compact: Just a single icon that switches to another when clicked.

Some websites do go that route with a tri-state toggle that cycles through three states. Docusaurus for example:

But generally, the ergonomics of that are poorer than for the two state toggle, so it is no surprise it’s rare (Docusaurus was the only example I could find).

Some tri-state controls go for three icons side by side, which triples the screen real estate used.

Others, in an attempt to balance clarity and real estate, resort to a dropdown:

That improves learnability, at the cost of efficiency, as it turns a single click interaction into a two-step process.

The actual perceived friction is actually worse than one extra click. Perceived friction is not a pure function of user actions, but also of the mental effort required to make a decision, and larger UI shifts (e.g. opening a dropdown) are more cognitively expensive than smaller ones (e.g. clicking a toggle) as the user needs to perceive and interpret a larger area.

If not three states, then what?

Guidance towards using tri-state controls is well meaning, but often based on paring good tri-state controls against poor two-state ones. E.g. in this article by Bramus:

Above that many implementations I have seen don’t take the “System” value into account. By omitting this option, the sites will never be able to respond to the system preference again, as they always have an override applied.

Indeed, a bad two state toggle is worse than a tri-state one. It makes the system mode unreachable once tweaked, making the selection irreversible and violating the usability principle of user control and freedom. A good two-state should be able to express all three states.

The idea is that the underlying model is still three states, but only two are shown at any given time:

When you press it for the first time, it toggles to the opposite of what you’re currently seeing, and stores the literal value (light or dark). The next time you press it, it toggles back to the system default, and removes the stored value.

That last bit is the one many two-state toggles get wrong. Storing a value that happens to match the system preference silently converts a temporary adjustment into a permanent pin with no way out.

Another common mistake is being overzealous about removing the stored value when the system preference changes, even if the user has explicitly set an override.

This evaluation must only happen at user interaction.

This is important because many users have their OS set to automatically switch between light and dark mode based on time of day, and removing the stored value proactively would make it impossible for them to actually pin a theme.

If a stored override later happens to coincide with the system preference — because the OS changed, not because the user did anything — you keep it.

This looks like an oversight — they’re the same now, why not tidy up? Because tidying up silently downgrades an explicit choice into a default, based on an event the user didn’t cause and can’t see.

Interactive demonstration

Here’s a concrete scenario that you can navigate interactively (view on separate page):

But what if users get confused?

An argument I heard when discussing this was “but if the user selects light when their OS is light, then the OS switches to dark, won’t they get confused that the website did not preserve their choice?”

People hypothesizing that other people, who are not them, will get “confused” is a bit of a pet peeve of mine in usability discussions, but let’s entertain it for a moment.

Here’s that exact scenario:

Remember, this control is entirely tangential to the actual user goal for visiting the website. Even if their intent were to pin light instead of reverting to System (light), this is something they would only notice once these diverge, i.e. the OS switches to dark. At that point, fixing it is a single click away. It’s such an easy fix, that there is no point in dwelling on it further.

It’s not that this never comes up, but making the tradeoff in favor of a tri-state control isn’t justifiable, IMO. A tri-state control introduces permanent UI complexity to prevent a one-time, easily fixable problem.

Additionally, color appearance is not just a pure function of color components, but also affected by surroundings and other factors. Even if a website implements only two modes, light mode may look slightly different in a light OS vs a dark OS, so selecting it as an override makes it an informed decision.

The title and icon could make the state clearer (e.g. the tooltip saying “Switch back to light (system default)” instead of “Switch to light” or the icon having a small screen icon instead of just a sun or moon). But those would need user testing to validate that they are an actual improvement. My concern is that once you distinguish System (light) from light, it (ironically) could become the thing that primes users to seek a third state that they previously had not considered.

Even if there is an ingenious UI that exposes three states at the same time without adding any cognitive load or friction (I have some ideas about what that might look like), I’m unconvinced this is a problem worth solving, and feels a lot like the UX version of premature optimization.

When is a tri-state control appropriate?

Although I spent the whole article arguing against tri-state toggles, there are actually valid use cases for them.

These are the two cases I’m aware of, but feel free to recommend more in the comments!

1. Color scheme setting that lives a separate settings panel

This article is primarily geared towards a permanently visible toggle in the header or footer.

A setting that lives alongside other settings in a settings panel is a fundamentally different usage scenario:

• The user is already in the mode of making decisions about their future
• The expectation is not that every setting must produce immediate feedback
• There is a lot more screen real estate to explain three states.

It is no accident that while 2-state toggles are becoming the norm for persistent controls, tri-state is (rightly) king for settings panels.

2. When color schemes are implemented differently depending on the system setting

This entire essay assumes the common case where a website only has two color schemes: light and dark, and there is no difference between light mode in a dark OS vs light mode in a light OS. Vadim Makeev had an interesting idea: color schemes should take the underlying OS setting into account. Light mode should be less bright in a dark OS and dark mode should be less dark in a light OS, to reduce the contrast between the website and the rest of the system.

I have not seen many UIs doing this, and CSS does not make it easier (light-dark() is very much designed around duality), but if you are actually doing this, you have earned your three states my friend, display them as prominently as you like, none of this applies to you!

Edit: I reached out to Vadim to ask if he had seen any UIs following his guidance. Here’s what he had to say:

Unfortunately, I haven’t seen any websites using this idea. I would say we’re pretty limited with tools currently to do so. The moment we want to override prefer-color-scheme, the whole light-dark() convenience is falling apart.

Yet another problem that CSS functions will solve (nothing preventing us from creating a 2-4 arg version of this).

The general version

The dark mode toggle is a nice case study, but the underlying lesson is bigger:

Users do not seek out solutions to problems they don’t currently have.

The tri-state toggle is the GUI version of low signal-to-noise APIs that ask you to pass dozens of parameters that could have sensible defaults, forcing you to decide on problems you have not encountered and are not relevant.

Do not flood users with options that are irrelevant to their current situation. Options that might become relevant in the future, should be surfaced in that future, not pre-emptively.

Not every state of your state machine warrants visible UI.

Ultimately, everything boils down to the very same principle:
Respect user effort.

Thanks to Chris Lilley and Jake Archibald for reviewing an earlier version of this draft

That reminded me that I wrote a web component that I use quite a bit (particularly with FFConf), which should really be called do-when, but it's not, it's (stupidly) called when-do (the dash, I guess, being a comma in my head).

The component says: when a time occurs or passes, do a what: show, hide or scroll-to.

You can get the code from github - which also includes an interactive demo that lets you try the settings.

What it is

A small web component to toggle on or off depending on wall clock (date) time without affecting the visual layout (with it's own element).

Use case

I've been using this web component on the FFConf event pages for a number of years to reveal the ticket button if a visitor is sitting on the page (though I appreciate that's unlikely!).

<when-do what="hide" datetime="{ticket-live}">
<p>Tickets live at {nice-ticket-live}</p>
</when-do>
<when-do what="show" datetime="{ticket-live}">
<p>Buy <a href="…">now</a>
</when-do>

I've also used the what="scroll" for our schedule page, to automatically scroll to the current speaker.

Though I do appreciate my "battle testing" has been rather limited, so if you use this and spot bugs, please let me know!

API

• what="show|hide|scroll" - the component also throws an exception if a non valid string is used
• datetime="isodate" - recommended that you include the timezone, ie. "2026-09-13T10:00Z" is 10am on 13th September on UTC
• apply="classname" optional class name to apply to the when-do element when it activates, useful if you wanted to transition your contents into view, or highlight the newly scrolled element

How it works/styling

The web component makes use of display: contents to prevent itself from modifying the visual layout.

Due to this display method, it means you can't style the element directly, in that styling has no effect.

If you want to style the contents when the element is active, such as when it has been scrolled into view, it's recommended you wrap the child elements it a parent element, such as a div.

You can also use the apply property to indicate the current when-do has activated.

AI wasn't used in any part of this web component (which is also why the demo page is so ugly).

Originally published on Remy Sharp's b:log

Then a bug report was submitted on the wp.org forums leading to 1.1.0.

The Bug I Shipped on Purpose

In 1.0.0, I cleaned up a batch of false positives such as bracketed text like [at] and [dot] that isn’t really a shortcode by leaning on WordPress’s own get_shortcode_regex().

It was the right call for false positives but wrong call for other reasons. It was also, it turns out, the wrong call for the plugin’s entire reason to exist.

get_shortcode_regex() only matches shortcodes that are currently registered. But the shortcodes this plugin is meant to clean up are, almost by definition, the ones that aren’t registered anymore such as the leftovers from a plugin or page builder you’ve since turned off.

By keying off the registered list, 1.0.0 quietly stopped seeing the exact thing it was built to remove.

The nudge came from someone migrating a client off a site built with WP Bakery. They’d imported all the posts, deactivated the builder, and were staring at content packed wall-to-wall with , , , and similar tags.

The user installed Remove Empty Shortcodes hoping it would at least stop those from rendering on the front end while they cleaned house. It did nothing. The scanner came back empty, too. Obviously, a bug.

What’s New in 1.0.0

It Removes Inactive Shortcodes. Again. (Seriously.)

The front end now detects unregistered shortcodes and removes them, while keeping all of the false-positive protection from 1.0.0. So from a deactivated builder gets handled, but [at] in “email me [at] example [dot] com” is left alone, exactly as it should be.

If you’d rather remove the whole block, content and all, there’s a resc_removal_mode filter for that.

It Keeps Your Content

If you’d rather remove the whole block, content and all, there’s a resc_removal_mode filter for that. The default is the gentle one.

This is the part I cared about most. When the plugin finds an inactive shortcode that wraps content such asSome real copy, it strips the wrapper tags and keeps the copy. You lose the dead , you keep “Some real copy.” Your writing survives; only the scaffolding goes.

The Scanner Looks Where the Content Actually Is

The 1.0.0 scanner only examined registered, public post types. So if your import dropped everything into a custom post type whose plugin is no longer active, the scanner never looked at it which is exactly how you get “nothing found” on a site that’s clearly full of orphaned shortcodes.

The scanner now looks at the post types actually present in your database, minus the obvious system ones.

“Ignore” Finally Means Ignore

The scanner has always let you add shortcodes to an ignore list. In 1.0.0, the front-end remover didn’t consult it. In actuality, the two halves of the plugin weren’t talking to each other. Now they are. If you tell the scanner to leave a shortcode alone, the front end leaves it alone too.

WordPress 7.0

1.1.0 is tested up to WordPress 7.0, and I fixed a small admin-button icon that 7.0’s new button styling had knocked out of alignment.

Still Nothing Touches Your Database

This was the founding promise of the plugin back in 2019, when it started life as a way to retire Restrict Content Pro without gutting my posts: remove shortcodes from what’s displayed, never from what’s stored.

That’s still true, and now it’s pinned down by tests. The plugin filters content on its way to the screen. Your post_content in the database is left byte-for-byte intact. Reinstall the page builder and every shortcode renders again as if nothing happened because, in the database, nothing did.

Under the Hood

A couple of things for the developers in the room:

• Integration tests against real WordPress. The 1.0.0 suite mocked WordPress with Brain Monkey, which is fast but can’t catch how the scanner behaves against an actual database. 1.1.0 adds a full integration suite that boots WordPress, seeds real posts, and exercises the scan-and-remove path end to end including a test that proves stored content is never modified.
• CI across PHP 7.4–8.3. The unit suite now runs on every push and pull request across four PHP versions. Which is how I caught that the code had quietly drifted into PHP 8.0-only syntax while the header still claimed a 7.4 minimum. 1.1.0 honors 7.4 again (though I’d eventually love to retire support for it sooner rather than later).

Get It

Remove Empty Shortcodes 1.1.0 is live on WordPress.org. Install it, activate it, and the front-end cleanup just works. There’s still no configuration required. If you want to review what’s lurking in your content first, the scanner is waiting under Tools → Empty Shortcodes.

The code, the changelog, and the issues are all on GitHub if you’d like to follow along.

Source

My immediate thought was to throw two spans in the header cell and position or grid them within that cell, but the accessibility of that seemed… questionable.  It’s also what Wikipedia already does, and we here at meyerweb are nothing if not obsessed with finding new ways to do niche stuff.  So I tried something different.  But is its accessibility any better?

If you want to see it as a live example, it’s over at Codepen.  Most of the text in the table is what macOS Preview OCRed out of the original image, which I kept intact because I think it’s funny.  Anyway, here is the original markup I came up with for the table head, which you should not use:

<thead>
	<tr>
		<th scope="row">SCIENTIFIC DISCIPLINE</th>
		<th scope="col">GEOLOGY</th>
		<th scope="col">GEOPHYSICS</th>
		<th scope="col">GEOCHEMISTRY</th>
	</tr>
	<tr>
		<th scope="col">EXPERIMENT</th>
	</tr>
 </thead>

So one row for the headers across the top of the table, including the top-left label that goes with them, and then another row with the header that relates to the row headers for the rows below.  That is to say, the row-scoped table header in each of the rows in the table’s bodies (it has more than one), like this:

<tbody>
	<tr>
		<th scope="row">CONTINGENCY SAMPLE COLLECTION</th>
		[…]
	</tr>

The thing is, when I ran the idea past accessibility experts like Alice Boxhall and Adrian Roselli, they identified a problem: Not having a full row of cells, as is the case for the second header row, fails WCAG 1.3.3.  The suggested fix was to rowspan most of the cells in the first row, like this:

 <thead>
	<tr>
		<th scope="row">SCIENTIFIC DISCIPLINE</th>
		<th scope="col" rowspan="2">GEOLOGY</th>
		<th scope="col" rowspan="2">GEOPHYSICS</th>
		<th scope="col" rowspan="2">GEOCHEMISTRY</th>
	</tr>
	<tr>
		<th scope="col">EXPERIMENT</th>
	</tr>
 </thead>

With that, table navigation wasn’t perfect, but it seemed decent, so we could move forward.

In terms of presentation, to get the upper-left header cell to do the split-diagonal thing, I relatively position the <thead> and then absolutely position the second row in the table head to sit over top of the first, pinned to the bottom left corner.

thead {
	position: relative;
}
thead tr:nth-child(2) th {
	  position: absolute;
	  bottom: 0;
	  left: 0;
}

I fiddled around for a bit with trying to use a grid instead, but it didn’t really add anything that positioning didn’t already provide and threw some other wrenches into the works, like having to convert the entire table into a grid so the columns would stay aligned, so I decided to just stick with the positioning.

Then I throw a linear gradient background into the first row’s first cell to draw the diagonal, and everything’s thus more or less as intended, visually speaking.  (That diagonal could also be an SVG, in fact probably should be in production, but I was seeing how an all-CSS solution might work so a gradient is where things stand.)

There are some layout caveats with this approach, but they’re pretty much the same as other solutions I saw: primarily, the two bits of text that the diagonal visually separates can stick out of their respective halves of the split cell, or even overlap each other.  Also, you might need to explicitly set a minimum height of the first header row, in order to not exacerbate the overlap risk just described.

And then there’s a really big caveat: Safari, as of this writing, doesn’t handle the layout at all well, because it doesn’t apply relative positioning to <thead> (or <tfoot> or <tbody>, but at least it does <tr>s).  I went to file a bug and found there’s already one open, so maybe this will be fixed in the near future.  I figured out a way to get at least close to the intended result while still allowing line-wrapping in the column header cells, but it mangled the layout in Firefox and Chrome.  In the end, to work around the problem, I delved into browser strangeness (at the suggestion of Marius Gundersen) and settled on the following:

/* this is gross and I hate it but it works to fix 
   Safari’s layout of the table’s top headers */
@supports (font: -apple-system-body) {
	thead tr:nth-child(1) th {
		white-space: nowrap;
	}
	thead tr:nth-child(2) th {
		position: static;
		display: block;
		margin-block: -1.5lh 0;
		padding-block: 0;
		text-align: start;
		transform: translateY(0.25lh);
	}
}

Thanks, I hate it!  But it works, and I try to be pragmatic.

Anyway, the point being, what I’ve done here feels more accessible to me, and basic testing by both me and Adrian didn’t reveal any major problems, but I still worry about the positioning dorking things up for the users of screen readers I don’t have access to.  So I throw it to the audience, particularly the accessibility-technology-using part of the audience: does this solution fall down for you, or is it good enough? Please let me know!

Have something to say to all that? You can add a comment to the post, or email Eric directly.

While many factors drive this abandonment, research suggests that mental health apps have tended to prioritise visual appeal at the expense of what actually sustains users. In a space defined by vulnerability and cognitive strain, chasing visual fashion risks adding effort when users have the least to spare — quietly trading away the utility and trust the app depends on. Users don’t open mental health apps out of curiosity, but from need — often while stressed, anxious, overwhelmed, or exhausted. In these states, an unconventional icon, a confusing gesture, or a flashy animation instead of a delightful surprise becomes an extra cognitive overload. Moreover, it becomes a reason to disengage.

In those moments, visual experimentation from a mild distraction can turn into a friction that undermines the very help the app is meant to deliver. A solution must be a visual interface that is simple in usage and understanding from the first moment.

Crucially, improving engagement depends less on which UI trends you follow than on a single test applied to each one of them: does a trend lower the cost of using the app when the user can least afford it?

Before we look into the specific problems, we must recognise a core tension: many UI trends are optimised for goals that mental health apps don’t share.

Trend design is often about capturing attention and signaling innovation. Mental health design, in contrast, must be about offering refuge, reducing strain, and building trust.

Pursuing the former directly overrides the latter. It’s not a surface-level error of colour or font; it’s a foundational conflict of purpose. This tension surfaces across five fronts, each a place where adopting a trend on novelty alone can cost more engagement than it seeks to create.

The proposed principles are not based on a single A/B test or one isolated study. They are built from published research on mental health app engagement, cognitive load, accessibility, and emotional response in mHealth, set against competitive product audits and app-store evidence, and pressure-tested against my own quantitative and qualitative product work. That last source I treat as an illustration, understanding the limits of personal experience. In this context, validation is less about proving that one interface pattern universally works and more about asking whether a design reduces effort, preserves agency, avoids emotional mismatch, and remains usable when the user is already under strain.

A note on the examples: This isn’t a ranking of apps. Every app has its own positioning, target audience, constraints, and business pressures that may not be visible from outside, and a pattern that strains a user in distress may be exactly right for that product’s actual goal. I’m reading individual, visible design decisions for one question only: how they might affect someone arriving in a low-capacity state.

The primary goal of any mental health tool is to reduce, not increase, cognitive load. Yet, many trendy interfaces achieve the opposite. Neo-brutalist layouts with stark contrasts demand visual parsing. Hidden navigation menus that rely on non-standard swipes turn simple tasks into puzzles. Abstract, unlabeled icons force users to guess rather than recognise. Each of these patterns adds friction — seconds of hesitation, a moment of confusion — and for a user whose mental energy is already low, those costs start to accumulate.

This friction is most damaging during acute need. Research suggests that when a user is in a state of high anxiety or depression, even typing or making simple choices can feel overwhelming. When an interface demands high cognitive effort at the moment support is needed, it doesn’t just make that session harder — it gives an overwhelmed user a reason to close the app, and a reason not to reopen it. Each point of confusion can become a place where a user may quit for good.

Other findings show that apps with simple interfaces reduce the time and effort required to engage, directly improving retention. Conversely, a complex, trend-driven UI increases that time, creating an obstacle course that undermines the very healthy habit formation the app is meant to support.

This does not mean that every mental health product must be visually plain or minimal. The issue is whether the interface meets the user’s current capacity.

A panic-support tool, for example, works best when it offers a small number of obvious actions, rather than asking the user to browse. However, if a calming action meant for a moment of panic instead surfaces an upgrade screen, the product fails the user at precisely the point where failing matters most. Monetization is not the issue by itself; the issue is whether it appears at a point where the user expects immediate support.

Nonori shows the same principle in a more reflective context. The app does not present the user with a large content library or a complex dashboard at the start. Instead, it leads them through a simple, linear sequence of small actions. The value of this pattern is that it reduces the effort needed to begin. When a user is tired, anxious, or mentally overloaded, knowing exactly what to do next can lower the barrier to returning.

At the other end of the spectrum, comprehensive tracking apps show a different trade-off. Bearable, for example, is genuinely powerful: it consolidates almost everything a person tracks — mood, symptoms, sleep, medication, habits, reports, correlations — into one place. For users managing chronic conditions or preparing for medical appointments, this can be genuinely useful. But the same comprehensiveness can become a burden for an exhausted user. Dense dashboards and multi-step check-ins require executive capacity — the very resource that anxiety, depression, burnout, or brain fog often reduce.

A similar tension appears in anxiety apps with strong support content but busy entry points. A product may contain useful features yet still make the first screen feel noisy with too many cards, locked items, playful characters, or upgrade prompts. This is not evidence that the product is bad. It shows how the same interface can feel very different depending on the user’s state: clear enough during exploration, but too demanding during distress.

This insight shaped a guiding principle for our work: every interaction point must meet users at their current level of capacity, removing mechanical and cognitive barriers rather than adding to them. This principle guided our integration of low-friction, state-aware interactions in apps like Bear Room, a stress and anxiety reduction app, and Teeni, an emotional-wellbeing app for parents of teens.

In Bear Room, we already had a fast mood-based flow built around four emotion cards. At the same time, our product research supported a second need: users also wanted more personalised support. We avoided making this a long selection flow or a typing-only route because both can still create friction for people under stress or anxiety. Instead, we made voice a primary, prominent path, always alongside a text alternative. A central microphone button allows users to share what’s on their mind. The app then uses AI to analyse the input and provide a tailored set of coping practices.

Rather than picking a single entry model, we kept two paths because they served different states. That matched what we saw in later analytics and user conversations: quick emotional selection worked better when users wanted speed, while open voice or text input worked better when they wanted personalisation and to feel more heard. This was more a pattern we noticed, without having the exact measured results.

Similarly, in Teeni, we directly addressed the cognitive friction of parenting stress by introducing a “Quick Relief” button. This creates an empathy-friendly flow for parents experiencing anger or frustration. The button initiates a dedicated “Hot Flow,” allowing them to first vent and relieve their immediate negative emotions through voice input. Only after this emotional release does the app gently guide them into the more reflective “Cold Flow” for the rest of the app’s resources. This sequential, state-sensitive design acknowledges that a user in peak distress cannot navigate a complex app; they need a direct, simple, and validating first step.

These solutions directly tackle cognitive friction by meeting users at their level of capacity, resisting trends that add visual or interaction complexity. Voice input and single-action buttons remove the mechanical and cognitive burden of navigation and typing. The result is an interface that feels reliably non-judgmental and genuinely helpful when users are least equipped to navigate complexity.

A user’s emotional state is the context in which a mental health app operates. This is why its visual language must be empathetic and considerate. Research investigating how colour and aesthetics influence mood in mHealth apps suggests a critical insight: users in distress show a strong preference for subtlety. They long for dark palettes, sleek and sophisticated looks, and clean, uncluttered aesthetics, explicitly noting that cheerful, bright colours, while seemingly appropriate, can create a jarring, even physically uncomfortable conflict with their current mood.

This does not mean that every mental health or wellbeing app should look dark, quiet, or clinically restrained. The category is broad: it includes self-care, anxiety support, habit change, addiction recovery, trauma tools, therapy-adjacent products, and apps for more severe mental health contexts. A playful visual style may be appropriate for one product and a poor fit for another. What matters is not whether the interface is bright or muted, but whether its emotional tone fits the product’s purpose and the likely state in which users arrive.

Emotional mismatch can also appear in mechanics, not only in aesthetics. In Calmer, an anxiety and panic relief app, the interface itself appeared relatively clean and relaxed. Yet some of its engagement and monetisation mechanics sit in a different register from that relaxed: a discount wheel, or confetti celebrating a logged low mood. For a user who just recorded a hard moment, that shift — from quiet support to upsell or celebration — can land as a mismatch, whatever its intent.

For Bear Room, we prototyped a “cosy room” design informed by direct feedback from our users, which echoed the study’s conclusions. Several users in our research described the apps they had tried for similar needs as “too bright, too happy, and too overwhelming”. Users longed for a digital safe space. This was part of what pointed us toward a quieter palette in the final design: muted, earthy tones — neutral hues like soft greens and taupes — set against darker, calming backgrounds. For this product — a refuge for users arriving overwhelmed — that meant a middle ground: a space that feels safe without being gloomy. The interface avoided any bright alerts or sudden animations, making calmness the core feature.

This case underscores a critical principle: an overly cheerful, bold, or trend-forward interface can feel dismissive to someone in distress, creating a conflict that erodes trust. As Bear Room shows, trust is built when the interface respectfully aligns with the user’s emotional reality, offering solace through subtlety (which creates an overall feeling of a “welcoming and safe atmosphere”), not a solution through saturation.

Mental health often relies on routine and predictability. Yet many contemporary UI trends thrive on novelty and disruption, intentionally reimagining fundamental navigation. When an app introduces a novel interaction pattern, such as a unique swipe or a non-standard button behavior, it asks the user to learn something before they can act, forcing them into cognitive effort they can’t afford.

This does not mean that mental health apps must be plain, rigid, or generic. A product can have its own character, playfulness, and sense of identity. The question is whether that identity remains understandable and predictable when the user returns in a low-capacity state. A gamified self-care app like Finch may work well when the user arrives ready to explore, play, and build a routine. But open it after a hard day just to mark one task done, and the can’t-skip celebration screens that delight an engaged user become one more layer to get through before they reach what they came for.

A similar tension appears in large meditation and wellbeing platforms. Apps such as Headspace and Calm offer extensive libraries of different content. This breadth can be valuable during exploration. But in moments of stress, the product question becomes sharper: can the user return and immediately find the exact support they need, or do they have to search, filter, and relearn the structure?

Someone experiencing anxiety or executive dysfunction needs to use the tool in a straightforward navigation manner, not an interface they have to learn each time anew.

PTSD Coach, a public-health-oriented trauma-support app designed to help users learn about and manage symptoms after trauma, offers a useful positive example. Its interface is not trying to be fashion-forward. Its strength lies in a stable information architecture: users can learn, track symptoms, manage symptoms, and get support through clearly separated areas. For a user returning during distress, this predictability matters more than novelty.

CALMzone offers another useful example. Some of its breathing animations differ from standard visual patterns, but they remain tied to the exercise itself: the animation shows what to do, when to inhale, and when to hold. The guided audio screen also explicitly invites the user to put the phone down and listen. This is a rare and valuable form of interaction design: the product’s success is not more screen time, but reduced effort and regulation.

These insights guided our approach in applications like Bear Room, where navigation reliability was treated as a therapeutic feature. We intentionally crafted an experience of an empathetic guided flow.

Recognising that users would likely approach in states of overwhelm, we structured the interface as a clear, unwavering path, with a visible “Start” sign. Key emotional support tools here are represented as the room’s objects — symbols of daily life, unmistakably recognised by all. They are visually highlighted by design so that the user won’t get lost in the elements, can easily access the needed tool, and can remember their way around the digital space upon the next return to the app.

Trend-driven interfaces sacrifice this navigational certainty for novelty. Each unconventional choice in mHealth apps, when core functions are buried behind experimental interactions or placed in unexpected locations, leads to a cumulative effect of fatigue instead of innovation. Users are not in a place to explore. They abandon the entire practice of seeking digital support when every interaction feels like solving a new puzzle. This does not restrict experimentation; it simply means that animations, micro-interactions, AI, or playful mechanics must serve the user’s state rather than interrupt it.

Many popular UI trends can be exclusionary when applied without adaptation. The minimalist trend of low-contrast text fails users with visual impairments. Gesture-only navigation marginalises those with motor difficulties. Visually dense, animated interfaces can overwhelm users with cognitive or attentional conditions. In mental health, the population needing support disproportionately includes individuals with these accessibility needs.

Choosing a trending aesthetic over an accessible one is therefore an active decision to limit the app’s reach and efficacy. It ensures that those who might benefit most cannot use the tool effectively. Accessibility isn’t a layer you add at the end; it’s a constraint you design within, with most of it codified in Web Content Accessibility Guidelines 2.2. Body text needs 4.5:1 contrast against its background, large text and interface elements 3:1 — exactly what low-contrast minimalism fails. Interactive targets need a floor of 24×24 px (more for unsteady hands). Every gesture needs a visible button fallback, or you risk excluding anyone who can’t perform the swipe.

A final, and often overlooked, consequence of trend-following is the adoption of engagement mechanics designed for entertainment, educational, or productivity apps. Features like streaks, aggressive notifications, and gamified reward systems are engineered to maximise screen time and create dependency. Although they have long been considered effective tools for increasing retention, in a mental health context, this approach can easily be misguided. What presents as “motivation” can quickly transform into a source of performance pressure and guilt. For a user managing depression, a broken streak or a missed daily goal can exacerbate the very feelings the app aims to alleviate.

These mechanics are not inherently unethical. In routine-building products, they can help some users. The risk appears when they are transferred into mental health contexts without adapting for shame, low energy, relapse, and non-linear recovery. A streak, for example, is not just a retention mechanic when the user is emotionally vulnerable. It can become a visible record of whether they have “kept up” with their well-being.

In the apps I reviewed, this tension appeared through familiar persuasion patterns: streaks, streak freezes, commitment copy, urgency-based notifications, “don’t miss this offer” prompts, and success-framed buttons such as “Yes, I want to succeed.” In self-care or wellbeing products, these details can make the app feel less like a supportive tool and more like another system the user has to satisfy.

Designers still need return triggers. A mental health app has little value if users install it once and forget it exists. But return mechanics must be adapted to the emotional context. In Bear Room, for example, this philosophy is embodied in short, forgiving three-day streaks: the streak does not reset when a user misses a day, and every third day brings a small benefit. The goal is not to punish absence, but to gently support return.

The same principle applies to lighter interactions. Bear Room includes a simple, optional bubble-popping game. Its purpose, however, is not to hook the user but to offer a brief, calming interlude. It is deliberately finite, providing a small mood lift and gently signposting other resources within the app. The value is in the momentary relief, not the extended session.

This commitment to supportive, non-coercive design extends to foundational app architecture:

• Respectful and User-Tailored Interaction Models
  The Pillow, a visual interface in the app, acts as a neutral, accepting space. Users can select a feeling or record a voice note, and the app responds with an AI-curated set of practices (28). It offers support without judgment, commentary, or pressure to “achieve” a certain state. Our app prioritises mood-aware algorithms to dynamically order activities. Breathing exercises or grounding techniques are surfaced based on the user’s reported emotional state, creating personal resonance without the need for an overwhelming content library.
• Feedback as a Reciprocal Exchange
  We approach feedback not as a data grab via constant emails but as a respectful dialogue. An unobtrusive object allows users to contribute at a natural pause point, and their input is acknowledged with a small reward. This frames their participation as a valued gift, not a demanded obligation.

In mental health technology, sustainable retention is earned not by capturing attention, but by becoming a consistently respectful and helpful presence in a user’s life.

The mHealth apps design invites finding a challenging balance between boosting their use without being too demanding.

This is not a niche concern affecting a fringe audience. The World Health Organization (WHO) estimates that about one billion people globally live with a mental disorder, with depression alone affecting nearly 5% of adults. Critically, the overall number is rising — in the last decade, depression and anxiety cases have increased by 25%. This vast and vulnerable population cannot afford for its tools to fail due to poor design. While UI trends aren’t inherently problematic, their application within wellbeing products demands a radically contextual approach.

Even a five-minute decompression tool between meetings has an emotional context, and a style chosen for its look — glassmorphism, a certain flavour of ultra-minimalism — can miss it, however sophisticated the audience. The point isn’t that these styles are wrong; it’s that the look has to answer to the moment. Soft biomorphic shapes or fluid transitions can genuinely help when they directly serve the goal of calm — and the same elements become noise when they’re there to impress.

What carries the highest risk is lifting a visually striking “Dribbble shot” and applying it without deep adaptation: it solves for the designer’s portfolio, not the user’s need.

The five fronts outlined above are not just a diagnostic lens; they are the foundation of an evaluation framework for anyone designing in the mental health space. Before incorporating any trendy visual or interaction pattern, it is worth running it through each of them in sequence:

• Cognitive load
  Does this reduce the effort required for someone who is overwhelmed, or does it add another layer of complexity to an already strained experience?
• Emotional alignment
  Does this support a wide spectrum of emotional states, including distress and exhaustion, or does it clash with the context in which users are most likely to arrive?
• Navigational reliability
  Does this build trust through predictability, allowing users to return and find their way without relearning, or does it prioritise novelty at the cost of consistency?
• Accessibility
  Does this uphold or enhance accessibility for diverse sensory and cognitive abilities, or does it quietly exclude the users who may need support the most?
• Engagement integrity
  Does this invite use in a way that is supportive and non-coercive, or does it borrow mechanics from entertainment products that may create pressure rather than relief?

A design that passes all five holds together as something more than usable: it becomes a tool that users can trust enough to return to in moments of genuine need.

Trends can be inspiring. They can win awards and generate buzz. But in mental health, sometimes the best design is the one that helps users feel understood — a quiet helper they trust enough to return to in moments of stress and vulnerability. It doesn’t steal the spotlight, but focuses on the user’s emotions. In the end, the ultimate goal is not for the interface to be seen — but for the support to be felt.

Different colors, sizes, or rotations based on how close they are to the edge and which side of the container they are on. Instead of relying on class names, item counts, or sibling positions, we can achieve this with a single CSS function.

The view() CSS function is known for its use in scroll-driven animations, affecting elements based on their visibility within a scroll container. However, it can be used without involving any actual scrolling or motion effect.

This article shows you how to do that to create more adaptive interfaces based on their closeness to their container’s boundaries.

How view() Works

The view() function links an animation’s progress to its visibility within its scroll container. When we apply animation-timeline: view(), the browser tracks the position of the element relative to its nearest scrollable container. The animation progress goes like this:

• 0% Progress (Start): Triggered the exact moment the top/left/leading edge of the element enters the visible boundary of the scrollport.
• 100% Progress (End): Reached when the bottom/right/trailing edge of the element completely exits the opposite side of the scrollport.

Boundary-Aware Style on Static Elements

Here’s a group of elements that are arranged in a three-column grid.

<main>
  <div class="card">Contacts</div>
  <div class="card">Shipping information</div>
  <div class="card">Find a product</div>
  <!-- more -->
</main>

.card {
  background: rgb(16, 111, 235);
}

I want the cards to have different colors based on their horizontal distribution in their container. So, first, we turn the cards’ parent, <main>, into a scroll container.

Let’s update <main> to be a scroll container:

main {
  overflow: hidden;
}

If <main> doesn’t become a scroll container, the view() function we’ll later apply might take the <body> element as the nearest scroll container.

To change the cards’ colors, I’ll use the hue-rotate() filter. This goes into a @keyframes declaration.

@keyframes cr {
  /* Set the color range */
  from { filter: hue-rotate(180deg); }
}

Use the keyframes animation on the cards with the view(x) timeline. x is the horizontal axis.

.card {
  background: rgb(16, 111, 235);
  animation: cr;
  animation-timeline: view(x);
}

Another example:

@property --a {
  syntax: "<angle>";
  initial-value: 0deg;
  inherits: false;
}
@keyframes cr {
  from { --a: 360deg; }
}
main {
  overflow: hidden;
}
.card {
  background: conic-gradient( from var(--a), red, pink, crimson, fuchsia, orange);
  animation: cr;
  animation-timeline: view(x);
}

Here’s what some simple style changes look like:

Boundary-aware style on draggable elements

<div id="draggable-box">
  Draggable box
</div>

The #draggable-box element is a draggable (by JavaScript). Its position on screen, the default scroll container, changes as we drag it across the viewport. So does its color.

@keyframes shiftColor {
  to {
    background-color: rgb(203, 49, 242);
  }
}
#draggable-box {
  background-color: rgb(41, 113, 248);
  animation: shiftColor;
  animation-timeline: view(x);
}

See the box’s color change as you drag it from the left to the right side of the screen.

You can apply the same principle in HTML sliders.

<input id="slider-range" type="range" min="0" max="100" value="50">

@keyframes shiftColor {
  from { background-color: red; }
  50% { background-color: yellow; }
  to { background-color: green; }
}
#slider-range {
  /* the slider track */
  &::-webkit-slider-runnable-track{ /* Webkit */
    overflow: hidden;
  }
  &::-moz-range-track {             /* Firefox */
    overflow: hidden;
  }
 /* the slider thumb */
  &::-webkit-slider-thumb {         /* Webkit */
    animation: shiftColor;
    animation-timeline: view(x);
  }
  &::-moz-range-thumb {             /* Firefox */
    animation: shiftColor;
    animation-timeline: view(x);
  }
}

The slider’s track is set as the scrollable container with overflow: hidden, and view(x) is applied to the thumb. There are three color stops in the @keyframes animation that view() drives. As we slide the thumb along the track from one edge to the other, its color changes between the edges and the middle.

Here’s another example where an anchor-positioned element to the thumb changes.

<div id="slider-container">
  <input id="slider-range" type="range" min="0" max="100" value="50">
  <!-- the anchor-positioned custom thumb -->
  <div id="slider-thumb">&#x2B50;&#xFE0F;</div>
</div>

@property --a {
  syntax: "<angle>";
  initial-value: 0deg;
  inherits: false;
}
@keyframes shiftColor {
  from { --a: 370deg }
  50%  { --a: 180deg }
  to   { --a: -10deg }
}
#slider-container {
  overflow: hidden;
}
#slider-thumb {
  background-image: conic-gradient(crimson var(--a), dodgerblue var(--a));
  animation: shiftColor;
  animation-timeline: view(x);
}

You can experiment with the axes, animation range, animation steps, and more to achieve different results. Just make sure the right ancestor is set as the scroll container using the overflow property.

JavaScript in the Shadows

As one of the new proposals for JavaScript, the ShadowRealm API is pretty interesting. It allows for the creation of a realm, or in my mind, an environment, with JavaScript that is 100% disconnected from the main environment of your browser window. Mat Marquis gives a great introduction to this in Soon We Can Finally Banish JavaScript to the ShadowRealm over on CSS Tricks. (If for some reason you've never heard of css-tricks, you should absolutely bookmark it and make it part of your required reading.) Mat's introduction is a pretty fun read as well.

Brownies for Storage

I'm a sucker for anything browser-storage related, and Brownies is a great example of that. Brownies is a library that wraps cookies, Web Storage, and IndexedDB, all in one. Here's an example from their docs:

import { cookies, local, db } from 'brownies';

cookies.token = 42;     // Set it
let t = cookies.token;  // Get it
delete cookies.token;   // Eat it

local.token = 42;       // Set it
let t = local.token;    // Get it
delete local.token;     // Del it

// db is ASYNC so read is different
db.token = 42;          // Set it
let t = await db.token; // Get it
delete db.token;        // Del it

This looks quite delicious. It's probably not fair to say it is a wrapper for IndexedDB as from what I can see, it's just doing a key/value store and not letting you specify custom object stores and such. In fact, the docs for db seem to be missing, and the repository doesn't have issues enabled so I'm going to have to find another way to leave that feedback, but check it out nonetheless. (I sent the author an email about this.)

Don't use JavaScript!

My first two links were JavaScript related, so why not advise against JavaScript in my third link? While not an "anti" JavaScript resource, NoLoJS is a resource showing multiple different UX/UI components that can be built with no, or at least little, JavaScript. As I discovered last week, there's a lot you can do with CSS and removing JavaScript dependencies is just one benefit.

Just For Fun

Yesterday was July 4th which means hot dogs and fireworks and that's all... right? Unsurprisingly, there's quite a few examples of fireworks being rendered in HTML. Here's one fun example that's pure CSS:

See the Pen Pure CSS Fireworks by Eddie Lin (@yshlin) on CodePen.

I’m a front-end developer not a medical practitioner. If you’re bleeding IRL visit the hospital and stop googling medical issues!

The full-bleed layout — as described there by Josh Comeau — can be done with CSS grid (and subgrid). Sometimes you can’t grid the entire page.

That’s where Andy Bell’s utility class is useful.

.full-bleed {
  width: 100vw;
  margin-left: calc(50% - 50vw);
}

But it ain’t perfect. The issue is that viewport units don’t solve the classic scrollbar problem. If you’re on macOS or a fancy OS that has fancy scrollbars, test on Windows! 100vw can be wider than the viewport. Because why would browsers do anything sensible?

It’s hard to see in Andy’s CodePen but a few pixels can be cropped either side. Add something like a border or shadow and it’s easier to see.

.full-bleed {
  box-shadow: inset 0 0 0 10px yellow;
}

This is not always a problem but it can lead to subtle alignment issues. By the way, macOS has a scrollbar setting “Show scroll bars > Always” that’ll let you test the issue.

Andy solves this partially by hiding horizontal overflow on the <body> element.

body {
  overflow-x: hidden;
}

An alternative fix is to always reserve space for the classic scrollbar.

html {
  scrollbar-gutter: stable;
}

That can look weird if there is no vertical scroll necessary.

Modern solution

The “modern” approach is to use CSS containment. Turn the <body> element (or any 100% width child) into a container. Then replace the viewport units with container units.

body {
  container: body / inline-size;
  overflow-x: clip;
}

.full-bleed {
  inline-size: 100cqi;
  margin-inline-start: calc(50% - 50cqi);
}

Now hiding overflow is not strictly necessary. I prefer clip — see Overflow Clip guide by Ahmad Shadeed. I clip out of caution because I make dumb things. I also use logical properties and values to support right-to-left (RTL) text direction. Ahmad has an excellent RTL Styling 101 too.

But wait!

Using cqi units assumes body is the parent container of the .full-bleed element. What if we have nested containers? Check this out. I’ve forked Andy’s CodePen to add another .inside container that is not the full viewport width.

This alone would usually break the new .full-bleed class and ruin the fun.

But we can fix that!

@property --body-size {
  syntax: "<length> | <percentage>";
  inherits: true;
  initial-value: 100%;
}

body {
  container: body / inline-size;
}

.inside {
  --body-size: 100cqi;
  container: inside / inline-size;
}

.full-bleed {
  inline-size: var(--body-size);
  margin-inline-start: calc(50% - (0.5 * var(--body-size))); /* † */
}

What is that @property magic?

To be honest I struggle to wrap my smooth brain around this!

Let me try to explain it to myself. Without the at-rule the value of --body-size is calculated at the time of use, i.e. within .full-bleed and therefore relative to the inside container. By explicitly defining a @property the value is now calculated when it’s set within .inside. There 100cqi refers to the parent body container and .full-bleed inherits that value.

But what if you have more containers?

(╯°□°)╯︵ ┻━┻

Gosh! Stop being so difficult!

I would have a direct child of <body> like <main> set the --body-size value.

<body>
  <main>
    <!-- blah -->
  </main>
</body>

^† I’m multiplying by 0.5 because division is for chumps.

Next-gen solution

What CSS needs is a way to reference a container when using container units.

Ideas have been proposed for example:

.full-bleed {
  inline-size: 100cqi(body);
  inline-size: calc(100 * cqi(body));
  inline-size: calc(100 * container(cqi, body));
}

Cancel Interop 2026 and make this happen!

Thanks for reading! Follow me on Mastodon and Bluesky. Subscribe to my Blog and Notes or Combined feeds.

On birds, nature, and being carefree

I recently spruced up my garden with a bird-feeding station and it has been an absolute joy to sit and watch nature at every opportunity. As I observe the wood pigeons, collared doves, gold crests, house sparrows, robins and a family of squirrels coexist peacefully and peck the seeds and munch on the nuts (even if the squirrels do often steal the bird food) I become painfully aware of how I’ve lived so much of my life on The Internet in the last six years. I also reflect on how much has changed in the technology industry throughout that time, how much negativity and weird stuff I am forced to consume every day as a result, and how much I yearn to be as carefree and alive as the nature that I love so much to sit and witness.

Before working in DevRel I was a tech lead for a small creative agency in Manchester, UK. At the time I was frustrated with how much of my time was taken up with meetings, presentations, sprint and stakeholder management, and how little time I had to dedicate to building and working on my craft as a front-end developer. As a self-taught engineer who worked incredibly hard to pivot from teaching music to a successful tech career, I moved to DevRel in 2021, which promised to give me the time and space to continue to hone my craft. At the time, this small niche of the tech industry offered me the opportunity to explore, learn and build through teaching. I couldn't believe what a perfect combination of my skills this type of job was at the time. It felt too good to be true, honestly.

The good parts of DevRel

The good parts of DevRel are really good. Throughout the years I’ve had the privilege of helping many people succeed through my teaching, mentoring and support, and at the same time, I’ve been able to build some fun projects and learn about The Web along the way. I even picked up some half-decent video editing skills. Through the opportunity to travel and speak at conferences, I’ve made some truly wonderful friends scattered around the world, who all come from different backgrounds and cultures, brought together through their shared love and passion for technology (or at least, what it used to be). As I reflect on the last five and a half years, I’ve found myself at the heart of a thriving network of technologists who all have each other’s back. And I will be eternally grateful for that.

Unfortunately, for me, the difficult parts have outweighed the good.

The difficult parts of DevRel

The approaches to effective DevRel can vary wildly depending on the individuals that make up a team and the company itself, but ultimately, the primary goal of a DevRel team is to inspire and educate a community to encourage product adoption, and to help users achieve meaningful outcomes with that product in as short a time as possible. Unfortunately, the nuances within this clear remit are often at odds with what business leaders require in terms of being able to measure success.

Arbitrary measures of success

Developer education in the community is a long game. Product adoption by the right audience takes time, patience, and an experimental approach. But very often, this does not satisfy those in leadership positions, as they want to see measurable success in the short-term. I get it, I really do. However, it is notoriously difficult to measure the short-term impact and success of DevRel unless you use somewhat arbitrary metrics. These could be sign-ups (that might not end up being activated), blog post views or video stats in order just to have something to measure and report on.

The issue with this is that you can measure anything, and you'll naturally optimise for making that line go up, regardless of whether it's the right approach for the product or the customers or the team. For example, you could write a click-bait blog post and reach the front page of Hacker News. You could make a silly YouTube short that gets 15k views. Congrats, you demonstrated success! But it's most likely the "wrong" success, as those little Internet escapades most probably won't convert to impactful product adoption and paying customers. What's more, all of this distracts and diverts the efforts of DevRel teams from real impactful work that shows meaningful results in the long term.

Like many others in the industry, I have tried to find ways to show how DevRel and education is more than content creation, arbitrary metrics and making the line go up. But my detailed article Defining Paths to Business Value in Developer Relations, in retrospect, feels like a bit of a cry for help in trying to justify the profession to people who have already decided that regardless, they need those meaningless results in the short term in order to appease the shareholders.

Fighting to be valued and justify my existence

Given DevRel is a long game, with the only way to measure short-term successes through entirely arbitrary metrics, businesses who are struggling to grow in this reckless economy often find financial investment into DevRel very difficult to justify. Even as this niche of the tech industry was seemingly thriving in the digital post-pandemic pre-AI era of 2021-2023, my day-to-day work was always accompanied by an ominous, low-level, yet all-encompassing feeling of anxiety centred on the premise that if I cannot demonstrate short-term financial success for the company, then I could lose my job at a moment's notice and be without a way to support my family. In fact, I was made redundant in 2023 from a DevRel role at a company that was moving away from a community-centred approach to an enterprise-based strategy at the time. On reflection, what most notably contributed to the feelings of anxiety was that my job and responsibilities were being heavily micromanaged by those that did not understand or respect DevRel as a discipline. This came as a direct result of the lack of immediate measurable metrics that convert to financial gains, which often tends to send leadership into a flailing panic of pivots which leave a wake of destruction in their path.

As a result, I have — all too often — overworked myself in a desperate attempt to justify my existence, demonstrate my value and impact, and keep my job. This has, more than once, caused me to suffer from health problems including joint and nerve pain, despite being "completely healthy" according to numerous tests. At its worst at the start of 2025, I couldn’t even use my hands due to the pain for work or anything else, and I had to learn how to code with my voice. Unfortunately, I’ve been suffering from wrist pain and unexplained ailments again since December 2025. It's becoming quite embarrassing how frequently I visit the doctors only to realise that I am, once again, suffering from work-related stress and anxiety that manifests in my physical body.

It’s worth mentioning that in my latest role, my education work was definitely respected and understood, but by the end of my tenure, it had become difficult to justify. Given the shift in the technology industry that has changed how people learn and seek information (more on this later), it was difficult to find the right captive audience for my content through the more traditional methods that worked well in the past. I know my work was excellent, but I also feel like I failed. And for someone who takes pride in their work and wants to do well, this was a heavy burden for me.

On being the face of a company

When you work in DevRel, you are a public company representative. As such, your online presence (because you are expected to be online, and present) is tied inextricably to the perception of a company. If you struggle with any of the above issues mentioned, you must seek solace in the deep, dark shadows of group chats and backchannels. It’s comforting, in a way, that many of my peers also feel this way, but alas it is destroying us slowly, one by one. And whilst you share your anxiety and worries with your peers in the dark, you must continue to remain outwardly positive and sparky and cheerful on The Internet as a company representative whilst you’re crying and screaming and throwing up on the inside because you spend all day, every day, trying to prove your worth to keep your job.

It’s exhausting to have to always play a character. As a result, I’ve spent pretty much all of my developer relations career in a constant state of burnout.

Over the years, I also started to feel trapped inside my own “online technical educator” whitep4nth3r persona, and for every time I have summoned the courage to write or talk about a controversial topic that affects us all, there have been many more things that I have been unable to say. In fact, one of the reasons I started my weird newsletter was to give me a way to share the things on my mind that were difficult to say as whitep4nth3r, albeit rather cryptically.

AI is killing developer education

These feelings of instability, anxiety and unease are even more pervasive now in 2026, as the way people learn and explore technology has changed significantly since the mass-adoption of generative AI tools. Google has declared war on the web. People aren’t seeking information in the ways we once knew; The Internet and its communities have fragmented. It is now more and more difficult to use search engines to actually search for real and accurate information as a result of imposing AI overviews and the swathes of new AI slop articles that are poor regurgitations of stolen content that have been eating themselves for quite some time.

Additionally, developers aren’t gathering together in online spaces to learn and teach and share exciting projects anymore, rather they are mindlessly scrolling for a much-needed hit of short-form content dopamine (because the horrors of the world are more persistent than ever). And, as I mentioned in a recent blog post, many developers have replaced authentic human collaboration with conversations with the dreaded Chat Bots. A friend who is a very talented developer educator has come to the same conclusions:

The entire vibe has shifted. The majority of [community] folks are still on Twitter but there’s so much AI grifting and misery and hate in that place. LinkedIn is a parody of itself at this point. Bluesky feels reasonably cosy but way too much of a bubble. The community isn’t there. The forums are dead, the new Discord is quiet.

Freelance educators are also being impacted by this shift. Josh W. Comeau, author of incredible industry-defining courses like Whimsical Animations, recently shared on Bluesky that he has doubts about how sustainable his business model is:

I just launched my third course, Whimsical Animations, and so far, it’s on track to sell roughly ⅓ as many copies as a typical course launch. It’s a similar story with my two existing courses. Sales are down significantly from last year.

There are likely a lot of reasons for this, but I think the biggest is AI. There’s sort of a double whammy with AI:

1. Many people are wondering whether developer jobs will even exist in a few months, so they’re reluctant to spend time/money learning new dev skills.

2. Even if they do want to learn new dev skills, LLMs can provide personalized tutoring, so there’s less incentive to buy a paid course.

The future feels bleak for educators. Rich curriculums we craft intentionally and carefully for real human audiences are now routinely stolen and regurgitated by predictive algorithms. The Chat Bots, with their sycophantic tone of voice, are deliberately engineered to erase our own personalities, hard work and craft entirely from the equation. If DevRel is to survive, I think it will need to look entirely different from how it functioned during the last ten years.

The only conclusion I can draw from this is that my experience, skills, empathy and teaching expertise no longer hold the value they once did in this volatile industry (if they ever really did?). And this only exacerbates the burnout and anxiety that so often consumes me.

What’s next for me

I am leaving developer relations and I am going offline.

I wondered for a while whether I should leave tech entirely. But I still really, really enjoy making websites. I’ve found an exciting new role as a Staff Engineer, and I can’t wait to get stuck in. I’ve taken great joy in tearing down my video production studio to create a zen little coding den in which to explore my new role, and I can’t wait to never have to wear makeup ever again to do my job. (I mean, I didn’t really have to wear makeup, but I also kind of did. If you know, you know.) To protect my mental health and decouple my online presence from a company brand (at last!), I will not be announcing this new role publicly in the ways this weird industry has become accustomed to. Although, if you’re a close friend, you know where I’m going and that I’m happy and I trust you. I’ve deactivated my LinkedIn profile, and I’m going dark on Bluesky.

This is not a decision I have taken lightly, and it’s probably been in the works in my subconscious for a couple of years now. I’ve taken a lower salary, and outwardly it may look like I’ve gone “backwards” in my career, but I know this is right for me, right now. After all, progress is not always linear, and I see this as the first step towards the life I have been craving whilst sitting and watching nature in my beautiful garden. One day I’d like to follow in Chad Whitacre’s footsteps (please read his letter), and leave this place for good. But that’s a little while off yet; I have some more things to do here first.

As for what the future holds for whitep4nth3r, I’m actually not sure. I know I’m not that important in this vast and strange ever-evolving world; I know this won’t affect many people in the grand scheme of things, but I’m sure some of you will be wondering if I’ll still be around. I’d love to continue sharing what I’ve learned about The Web and technology on my blog, but given the current state of the search engine industry, would anyone even see it? (I have an RSS feed, for what it's worth.) I’ll probably continue to send my weekly newsletter, but the format may change given I am Logging Off for good and won’t be scouring The Internet for weird links anymore.

After all these years I can finally say out loud: I do not want to be the face of a company. I do not want to speak at conferences or on podcasts or do workshops in order to try and sell you a product. I do not want my value determined by arbitrary gamified metrics like how many video views or blog post views or company sign-ups I generate in a landscape that is completely out of my control. I do not want to be perceived. For being perceived is breaking me, and I need to put myself back together.

I just want to exist. I want to be closer to nature and my loved ones. I want to be present in the now. I want to be free. I want to make music. I want to live.

And I just want to build good websites.

• Your Grid Lanes will likely fail WCAG 2.4.3
• The Goldilocks customizable select height – ” I realised there’s a sizing ‘pattern’ that’s almost always the-one-you-want, but it took me a long time to figure out how to do it in CSS” writes Web Standards hunk Jank Architect
• County With 37 Data Centers Asks Schools to ‘Conserve Electricity’ – “Henrico County is a major hub for data centers in Virginia. Its officials said it expects a 25% rise in electricity costs next year, and advised workers to close the blinds and turn off their computers to make up for it.”
• Using CSS corner-shape For Folded Corners
• Neko – a browser to run other browsers
• Apple ‘Hide My Email’ Vulnerability Reveals Peoples’ Real Email Addresses – Remember, although it’s still unfixed a year after it was reported to Apple, your privacy and security remain Apple’s absolute priority. Honest.
• US Supreme Court just blew up EU-US Data Transfers– “US Supreme Court decided the US Federal Trade Commission (“FTC”) may not be independent anymore. Since 2000, the EU has relied on the “independent” FTC as the enforcer of EU-US deals on personal data. According to EU treaty law, such oversight must be independent. In the current EU-US deal, the European Commission relies on the independent FTC 259 (!) times”.
• What’s missing from SVG – glamorous Patrick Brosset tells all
• Ireland is big tech’s lapdog – and that compromises its EU presidency
• Experimenting with random() in CSS by ‪Kilian Valkhof‬
• Data Transfer Initiative’s regular regulatory roundup
• Surveillance Is Not Safety: A statement on the UK’s latest threat to privacy ^[PDF] by Signal
• The Siren Song of ariaNotify() – a means of programmatically triggering narration in a screen reader
• How good is Browser Support for the ARIA Notify API?
• NFC access on iOS – CMA call for evidence – “We are continuing to work on the full design of any potential intervention to ensure fair and reasonable NFC access on iOS”
• Google and Apple’s Anti-DMA Lobbying Strategy Goes All-in on Security and Privacy – As the EU starts to press Big Tech to open their operating systems to competitors’ services, you’ll hear a lot more handwringing from them about privacy and security. Most is FUD. Look at their record for privacy and security, especially of their own single-platform (“native”) apps and app stores.
• The Slow Death of the Power User – “This is the result of two decades of deliberate, calculated effort by the largest technology companies on earth to turn users into consumers, instruments into appliances, and technical literacy into a niche hobby for weirdos.”
• How AI reduces the world to stereotypes – Rest of World analyzed 3,000 AI images (“an Indian person,” “a house in Mexico,” “a plate of Nigerian food”, etc) to see how image generators visualize different countries and cultures.
• Wiggly/Wavy Input Range Slider – almost certainly useless; great fun

Intro to Grid lanes

CSS Grid Lanes is a new layout technique in CSS. Although the name suggests it, you don’t create grids with it; instead, you create columns or rows that automatically get populated with items. The layout kinda looks like a grid, but the big difference from regular grids is that you can only control one axis. By default, the browser decides where to place each item: it’s placed in whichever column brings it closest to the start of the container.

HTML

<div class="grid-lanes">
  <button class="s">1</button>
  <button class="m">2</button>
  <button class="l">3</button>
  <button class="l">4</button>
  <button class="m">5</button>
  <button class="s">6</button>
</div>

CSS

.grid-lanes {
  display: grid-lanes;
  grid-template-columns: repeat(3, 1fr);
}

button { block-size: var(--h)}

.s { --h: 2lh; }
.m { --h: 4lh; }
.l { --h: 6lh; }

1 2 3 4 5 6

In the demo above, you can see what makes Grid Lanes special: you can arrange differently sized items in a grid-like fashion with equal gaps.
You may have noticed that the columns in this demo are equal in height. That's because I arranged them that way, but one of the strengths of Grid Lanes is that you don't have to care about that. The browser looks at the items you give it and tries to create balanced columns (or rows). It does so by placing items as close as possible to the grid's start edge.

In the following demo, items 1-3 are each placed in a separate column because this brings them as close as possible to the start of the container. Item 4 is in the second column because that's the shortest column at the time of placement. The next two columns are equal in height. If there's a tie, the browser continues from where it left off (column 2 in our example) and places the item in the next available fitting column (column 3). Finally, the last item is placed in the shortest column, column 1.

HTML

<div class="grid-lanes">
  <button class="l">1</button>
  <button class="m">2</button>
  <button class="l">3</button>
  <button class="m">4</button>
  <button class="m">5</button>
  <button class="s">6</button>
</div>

1 2 3 4 5 6

That's pretty cool, but this strength is also Grid Lane's biggest weakness. As you can see, the visual order no longer matches the tab order.

That can be a problem, especially when the container spans a larger area on screen. WCAG Technique C27 lists several reasons why:

• A user with low vision who uses a screen magnifier in combination with a screen reader may be confused when the reading order appears to skip around on the screen.
• A keyboard user may have trouble predicting where focus will go next when the source order does not match the visual order.
• If a blind user, who reads the page with a screen reader that follows the source order, is working with a sighted user who reads the page in visual order, they may be confused when they encounter information in different orders.

That’s definitely a problem, but not necessarily a deal breaker. The flow-tolerance property may help improve the situation.

Placement tolerance

The flow-tolerance property allows us to adjust the placement precision. As mentioned, the algorithm places items as close as possible to the start edge. If one column is smaller than the other, the next item will be placed in the smaller column. If a column is only slightly larger, that behavior may result in an order mismatch and in an ugly layout. You'll see what I mean in the next demo.

We have 4 items. One is much larger than the others, and one is much smaller. The two others are almost equal in height; there's only a 1px difference.

HTML

<div class="grid-lanes">
  <button style="--h: 50px">1</button>
  <button style="--h: 60px">2</button>
  <button style="--h: 49px"">3</button>
  <button style="--h: 20px">4</button>
</div>

CSS

.grid-lanes {
  display: grid-lanes;
  grid-template-columns: repeat(3, 1fr);
  flow-tolerance: 0;
}

button { block-size: var(--h)}

1 2 3 4

Item 4 ended up in the third column because item 3 is 1px smaller than item 1. That's only happening because I set flow-tolerance: 0. The default value is 1em. If I increase the tolerance or use the initial value, you can see how item 4 ends up in the first column. That's because the property specifies what the threshold is for considering tracks to be “the same height”. If you set the value to 10px, a smaller column has to be at least 10px smaller to be considered smaller.

1 2 3 4

When the logical and visual orders are out of sync, you can increase the Flow Tolerance to mitigate the mismatch. That sounds like a solution to the problem, and it is for some (most?) layouts. The thing is, that the tolerance value sometimes needs to be very high to make a difference.

Demos

The WebKit team created The Field Guide to Grid Lanes, a demo and playground for CSS Grid Lanes. What they build is cool and useful, but all their demos would fail WCAG 2.4.3 by default if they contained focusable elements, which in a realistic example they most likely would.

Their first demo is a classic image gallery with images of varying heights. The numbers you see on each image indicate its position in the DOM within the container. The order of the first 5 items is fine, and we also know why, but starting with item 6, things get ugly. There is a critical mismatch between the DOM and the visual order.

The Field Guide comes with controls for each demo. You can increase the Flow Tolerance with a range slider that goes up to 10rem. With a Flow Tolerance of 10rem, it's slightly better but still not acceptable.

I had to increase the Flow Tolerance to 40rem (640px) to remove the mismatch entirely. Unfortunately, that surfaced another problem. The lengths of the columns are now imbalanced, and because the heights of the images are so different, focus still jumps around a lot, but now vertically. For example, you can see how the focus has to travel down from item 11 to 12, then up to 13, and down to 14. That's not great.

To be fair, although all their demos fail WCAG by default, increasing Flow Tolerance sometimes fixes the problem. In the following screenshot (click to enlarge), you can see an order mismatch across all screen sizes.

Setting the Flow Tolerance to 10rem, gets rid of most issues.

Update:

1. As Patrick pointed out on Bluesky, you can also set flow-tolerance to infinite, which makes items distribute themselves strictly in order, without considering the length of the tracks at all.
2. Clarified that the Field Layout demos don't fail 2.4.3, but would if they contained focusable elements.

Reading flow

Of course, I'm not the first to address this issue. There has been a lot of discussion, even dating back to when CSS Grid Layout was proposed. If you're interested, check out Adrian Roselli's post Source Order Matters for a chronological overview or read the following issues on GitHub:

• Masonry layout in CSS Grid 3 has potential to cause accessibility problems with reading order.
• Providing authors with a method of opting into following the visual order, rather than logical order.

There is awareness of this problem, and people have been discussing it a lot; the outcome was two new properties in CSS: reading-flow and reading-order. I won't go into detail now, you can read about them on the Chrome blog or MDN, but essentially, the reading-flow property can be used to ensure the reading and tabbing order reflects the visual order when the visual and DOM order don't match.

.reading-flow {
  display: grid; 
  grid-template-columns: repeat(3, 1fr); 
  gap: 10px;
}

<div class="reading-flow">
  <button style="grid-column: 2 / -1">1</button>
  <button>2</button>
  <button style="grid-column: 1; grid-row: 1;">3</button>
  <button style="grid-column: 1 / span 2; grid-row: 2;">4</button>
</div>

.reading-flow {
  display: grid; 
  grid-template-columns: repeat(3, 1fr); 
  reading-flow: grid-rows;
}

Reading flow could address many of the issues (not all, because visual jumps could still be present) I described in this blog post, but it's still theoretical: it's only implemented in Chromium-based browsers and doesn't yet work with Grid Lanes. Also, the positions of WebKit and Mozilla aren't clear. Safari still has some concerns and open issues, and Firefox hasn't published its position yet.

• CSS reading-flow standards position Mozilla
• CSS reading-flow standards position WebKit

I haven't been following the discussions around Reading Flow, and I haven't played with it yet. Not having spent too much time thinking about it, I'm a bit torn. On the one hand, Reading Flow seems to work and fix a real, common issue. On the other hand, it may lead developers to care even less about source order. Anyways, this post isn't the right place to discuss that, but I feel like it could be a good idea to set an implicit default value for Grid Lanes that follows the visual order, since Grid Lanes inherently break the tabbing order. That may not be a good idea, and it may not be possible, because there are different ways to lay out Grid Lanes, but as this blog post has shown, the default state is unacceptable in many cases. If you have ideas on how to address this issue, please add your opinion to one of the issues I linked, create your own issues or bug reports, or talk to browser people on social media.

The title of this post

Consequently, today, that means that if the heights of your grid items don't vary too much and if you increase Flow Tolerance, which you probably always have to do, you can make Grid Lanes more or less accessible. In the future, when all browsers support reading-flow and implement it for Grid Lanes, it may get even easier and you may not have to rely on flow-tolerance too much.

Now you may ask yourself, why is the title of this post still so negative? Why didn't I go for something like “Improving the accessibility of Grid Lanes“?

1. It's too easy to create inaccessible Grid Lanes if you aren't aware of the implications. That's a big difference compared to regular grids because, to mess with them, you have to change the order or explicitly place items, which, by the way, is also possible with Grid Lanes and can potentially make the situation even worse.

2. I watched a talk by Rachel Andrew in which they explain that they didn't want Grid Lanes to ship unless Reading Flow existed for the reasons described in this post, but that's exactly what happened in Safari. It supports Grid Lanes, but not Reading Flow. Chrome and Edge support reading-flow and Grid Lanes behind a flag, but as of today, Reading Flow is scoped to regular grids and flex containers.

3. Since Reading Flow for Grid Lanes is only an idea, and Safari made Grid Lanes very real by shipping it, we're left with Flow Tolerance for improving accessibility. Based on my limited research and experience, the default value for flow-tolerance seems too low. It should be high by default to reduce the likelihood of a mismatch between the logical and visual order.

4. Flow Tolerance is not a silver bullet, and DOM order is not the only thing that matters. Large differences in height between grid items can also affect keyboard accessibility.

5. The specification has a section about accessibility, but it's not detailed enough.

6. The WebKit field guide has nice demonstrations, but doesn't address the obvious accessibility issues or reading-flow as a possible solution. They only mention that spanning and explicit placement can be problematic. I find that questionable. The fact that their website isn't WCAG-compliant doesn't make it better.

Bonus: Another solution

I'm not sure I really want to recommend this solution, or even if it's a solution, but I was trying to figure out whether there is a way to improve the situation for keyboard users. And I tried the following, which surprisingly works.

CSS

.grid-lanes:has(:focus-visible) {
  display: grid;
}

1 2 3 4 5 6

You can have your Grid Lanes in any order you want, because as soon as there is focus within, the display switches to grid for keyboard users. Of course, that doesn't fix the problem for sighted screen reader users who use the virtual cursor, and it can also be confusing if the layout suddenly changes on focus. I'm mentioning it because I find the idea interesting, and it can be a solution for some layouts.

Conclusion

I was never really excited about Grid Lanes to begin with, but that was just my personal opinion. After watching Patrick's presentation, I can see how there are more use cases than the classic Pinterest layout, but still now I'm even less excited due to the potentially poor baseline accessibility. And I'm afraid most people will use them out of the box without adjusting the Flow Tolerance or testing them with the keyboard or screen readers.

To sum it up, my recommendations are:

• Always test your Grid Lanes with the keyboard or a screen reader at different screen sizes.
• If you find a mismatch between the DOM and the visual order, increase the flow-tolerance value.
• As soon as it's available, try to use reading-flow instead.
• If that doesn't work, consider using a regular grid.

My blog doesn't support comments yet, but you can reply via blog@matuzo.at.

If you ever bookmarked the CSS Tricks Complete Guide to Flexbox, HTML5 Rocks, or CSS Zen Garden, a guide like this might feel familiar. It’s designed to be an easy introduction, a reference guide — and just plain fun.

The interactive playground

At the top is a live, editable Grid Lanes layout. Switch between Waterfall and Brick. Try preset layouts. Drag the slider labeled “Flow tolerance” and click “Play tab order” to understand the impact of flow-tolerance.

Resize the demo browser window to test responsive behavior without resizing your whole window. Edit the CSS directly. Copy the code you create.

The cheat sheet

Next is the Field Guide itself — a single-page reference for every property, value, and option.

It has four sections:

• Grid Lanes Basics — display: grid-lanes, plus the difference between waterfall and brick layouts
• Options for Lane Definitions — Grid track-sizing with fr units, fixed lengths, percentages, auto, min-content & max-content, fit-content(), minmax(), repeat(), and auto-fill vs auto-fit
• Options for Placement & Spacing — flow-tolerance, gap, spanning tracks, and explicit placement
• Good to Know — info about source order, progressive enhancement, and switching layouts at different breakpoints

The demos

To showcase the possibilities of Grid Lanes, we created six demos, each available in several variations:

• Photos — just images, in a variety of aspect ratios
• Recipes — components containing both flexible images and varying lengths of text
• Newspaper — longer passages of text, with a few images (and a lot of CSS puns)
• Mega Menu — lists of very short text
• Timeline — text in brick layout
• Pinboard — mixed media

Each demo opens with a floating control panel.

“Layout” offers a dropdown of variations — showing off what Grid Lanes can do, and comparing it to Flexbox, Multicolumn, and Grid. “Numbers” shows item order. “Flow tolerance” lets you experiment with its effects. The code panel displays the key layout CSS.

“Hide controls” puts the focus on the demo itself. To get the controls back, click the gear that appears in the lower-right corner.

Working with Safari’s developer tools

Web Inspector knows about Grid Lanes, too. Toggle “Order Numbers” to reveal overlays marking the DOM order of items. These numbers are extremely useful when experimenting to find the best flow-tolerance value for your content.

Learn more by reading New Safari developer tools provide insight into CSS Grid Lanes.

What about other browsers?

Grid Lanes works today in Safari 26.4+. For the latest information about other browsers, check Can I Use. For progressive enhancement guidance, read When will CSS Grid Lanes arrive? How long until we can use it?

Made by the people who shipped it

The Field Guide was built by the same team behind Grid Lanes. We hope this is a fun experience that makes Grid Lanes easy to learn. Bookmark it, share it with colleagues, and let us know what you make.

Visit the Field Guide →

Feedback

We’d love to hear from you. Find us online: Jen Simmons on Bluesky / Mastodon, Saron Yitbarek on Bluesky / Mastodon, and Jon Davis on Bluesky / Mastodon. You can follow WebKit on LinkedIn.

Ok so Ethan Marcotte wrote this better (to be fair he literally wrote the book on tech unions)… my version is a little more documentary.

1. The American tech labor market softens

The workforce shrinks and developer jobs intensify

The industry hemorrhages workers to free up funds to invest in data centers. Workers try to organize, but are drummed out. Massive layoffs at every large tech company leave thousands of formerly well-paid developers unemployed for months on end.

Senior and Principal developers are RIF‘d perfunctorily, seemingly at random or based on arbitrary (and possibly ageist) standards. Team members simply disappear as they are locked out of systems. Everyone else needs to take on more work to cover their lost colleagues; morale and productivity sink as every remaining worker fears they will be next.

Because training junior devs is an investment, fewer companies hire them to juice their short-term numbers. American companies offshore developer positions to countries with worse labor protections and/or lower wages.

Work conditions worsen

Developers pull back from directly creating code to supervise AI agents and review generated code, becoming alienated from their labor and lacking opportunity to truly exercise their skills. Bonuses become more competitive as budgets squeeze, further dampening morale and disincentivizing collaboration. Degrading surveillance  and reassignment to data labeling makes workers nihilistic.

RTO orders force workers back into exhausting commutes, only to sit on video calls all day anyway because the workforce is internationally distributed. International workers in the US on visas are trapped between extortive labor conditions and hostile immigration policies — quitting could mean being deported. Companies double down on work intensification, and more workers burn out of the industry.

2. Coders are deskilled

Incentives heighten developer reliance on generation

The few junior devs that are hired have to meet higher production quotas upfront, while senior devs have less time to mentor them and review their work, driving early career reliance on code generation, meaning that they don’t develop their own coding skills as richly through trial and error.

Meanwhile, the incentive structures for individual developers encourages generating code over stepping back to consider high-level logic as production expectations intensify and bonuses are tied to output. When generating is perceived to be cheap, developers don’t need to weigh the value of a solution before producing it, and they drown their colleagues in pull requests. In this system, it is usually the most competent who are the least rewarded.

The code quality produced by an LLM likely varies in quality depending on the experience of the prompter and the base of training data. As more developer jobs shift from coding to supervising AI, prompters have less and less experience developing code on their own to draw upon.

3. What next?

Sidebar: the risk to companies of deskilling industries

My dad worked as an electrical engineer at a TV station (KGO for the SFers) — one of his duties was repairing equipment. Every piece of tech the station needed to run, on-site and off, he could fix. But over the decades, the companies selling the equipment started making it less repairable, so more and more, they had to send it back to the manufacturer to repair or replace. That meant he was the tail end of the career… no one younger was trained to replace him.

Unfortunately for the station, there remain a handful of things that really must be done locally / in-house. Having no one they could hire, they begged him not to fully retire, and he remained on-call for five years before finally deciding it wasn’t his problem and he didn’t have to do shit jobs like drive the giant satellite truck or climb Sutro Tower to repair equipment anymore.

Why I am thinking of this now:

“There’s some use in distinguishing here between the worker who, having learned the skills of writing software over many years, now turns to so-called AI to assist her in that task; and the worker who will follow her some years hence and may never learn those skills, but will know only the work of supervision.”
— Mandy Brown

If genAI actually pans out (or merely serves its purpose of allowing companies to lay off workers they over-hired during the pandemic / when money was cheap), many software engineering positions may go this route. And for a while, that might work out. But what happens when all the software engineers who are intimately familiar with the code are gone, and problems become exponentially harder to fix… perhaps beyond the technical capabilities of supervisor-coders? If the code was generated, then there is no company to send it back to to fix. It is work that must be done by a software engineer, somewhere.

Workers regain power?

Unemployed developers are forced to confront the reality that they are working class when the jobs don’t come back. Some are rehired as contractors for similar positions at lower pay with worse benefits, also losing the status of being an FTE. People who think of themselves as upper-middle-class lose their homes when they can’t pay their mortgages.

Seeing former colleagues forced to take large cuts in pay and prestige, do remaining developers recognize their own precarity and the lie of “meritocracy”?

Lower bonuses weaken the incentive structure.

Do people become more cutthroat, throwing their colleagues under the bus for the sake of ultra-competitive promotions and limited bonuses? Or does it make workers realize that working 80+ hour weeks for the promise of unguaranteed future compensation is a bum deal?

Over the medium term, the weak entry level developer job market and worsening job conditions discourage students from becoming developers. Fewer workers enter the labor market as developers. More and more workers simply don’t have the skills to compete for high level roles. As the labor market (and competition) shrinks, this grants the remaining high-skilled workers greater power for the final years of their careers.

Do they take it as their due and demand better compensation and restore working conditions for themselves only? Do they establish a new pecking order with themselves at top and supervisor-coders as a lower tier, like testers? Or do they use their newfound power as leverage to protect conditions for all workers by unionizing?

Recommended reading:

All tomorrow’s parties. by Ethan Marcotte (2026) — if you didn’t read it up top

why office workers didn’t unionize by Anne Helen Petersen (2020)

The Cruel Optimism of Tech Work: Tech Workers’ Affective Attachments in the Aftermath of 2022-23 Tech Layoffs by So et al (2025) — this is long but the parts I skimmed were interesting

AI Killed My Job: Tech workers by Brian Merchant (2025)

Affordances we can’t refuse by Andrey Mir (2026)

Ten Times by Mandy Brown (2026)

See also:

On work: who sets the defaults?

The dream of AI is the dream of free labor

Mat Marquis, former Responsive Images Working Group (RICG) chair and amateur boxer, isn’t known for pulling his punches. And yet, Marquis stopped short when he declared The End of Responsive Images. Mat left responsive images on the ropes. I hope to finish them.

Or rather, finish most responsive images. The ones below the fold. Let me explain.

The responsive images race condition

In the beginning of our search for a responsive images solution, the challenge seemed simple: the img element only supported one source file, and we needed multiple sources to support responsive designs. However, if we supply multiple image sources, how will the browser know which source to choose?

Therein lies the rub. Browsers download images before they’ve calculated the layout of the page. And if the browser doesn’t know the page layout, it doesn’t know the size of the image in the page. As I put it back in 2012:

How do we reconcile a pre-parser that wants to know what size image to download ahead of time with an image technique that wants to respond to its environment once the page layout has been calculated?

Solving this problem is how we ended up with srcset and sizes. One tells the browser what source options it can choose from and the other provides the browser with the information it needs to calculate the size of the image in the page based on a measurement the browser always knows—the viewport size.

Lazy loading changes everything

In the years since, lazy-loading images has become a common practice. We can safely defer loading images outside the initial view (aka, below the fold) in order to ensure that the browser’s resources are focused on the assets that are immediately visible.

So many developers adopted this practice that it is now a web standard. Adding loading="lazy" to any image will tell the browser to delay downloading the image until it will be visible in the viewport.

Because lazy-loaded images won’t download until they are visible, the race condition described earlier no longer exists. When lazy-loaded images are downloaded, the browser knows their size.

Lazy-loaded images now allow us to simplify the markup for sizes as Mat Marquis explained:

A few weeks ago, two patches landed in Gecko and WebKit — championed by Simon Pieters and Yoav Weiss, respectively, two of the RICG’s finest. These patches landed to little fanfare, quietly aligning Gecko and WebKit with Blink in supporting a relatively recent addition to the HTML specification: support for an auto value in sizes attributes. Automatic sizes — the potential sizes of the rendered image, left up to the browser to determine alongside all those other factors. Fully automatic responsive images. Supply the browser with a list of candidates using srcset, bolt on sizes="auto", and let the browser do the rest.

So long as an image has loading="lazy" you can use sizes="auto". Here is the sample Mat provided (with a few cat-related tweaks on my part):

<img 
  loading="lazy"
  src="cat.jpeg" 
  srcset="cat-650.jpeg 650w, cat-960.jpeg 960w, cat-1400.jpeg 1400w"
  sizes="auto, (min-width: 1040px) 650px, calc(94.44vw - 15px)"
  width="650"
  height="400"
  alt="My cat Boyle is super cute.">

You’ll notice that Mat includes fallback sizes values to support older browsers. But with Safari and Firefox now supporting sizes="auto" we likely won’t need the fallback for long.

Caution: Images above the fold shouldn’t be lazy-loaded. In fact, hero images are likely your Largest Content Paint (LCP) image in Web Core Vitals and should be loaded as early as possible. Therefore, images in the initial viewport will likely always require responsive images syntax.

Removing srcset

Simplifying sizes is a good start, but I believe we can go further and radically simplify the markup for lazy-loaded images using Responsive Image Client Hints. Responsive Image Client Hints is a draft specification being stewarded by Eric Portis also of RICG fame.

Responsive Image Client Hints builds on the existing Client Hints standard that has been implemented by Blink and thus supported by Chrome, Edge, and other browsers built on the Blink engine. Web page authors can declare support for Client Hints and ask for specific hints like the size of a requested image. The browser then sends this information in HTTP headers.

For example, a server might send the following HTTP headers along with an HTML document:

Accept-CH: Sec-CH-Width
Permissions-Policy: ch-width=(self "https://images.cloudfour.com")

The first line says that the server will accept client hints and is looking for Secure Client Hints Width (Sec-CH-Width). The permissions policy line helps reduce the potential for passive fingerprinting by restricting access to the specified domains. A similar declaration can be made via a meta tag:

<meta http-equiv="delegate-ch" 
      content="sec-ch-width https://images.cloudfour.com;">

And then when an image on the page is requested by the browser, it will supply the requested Client Hints—in this case, the width of the image in the page:

GET cat.jpg
Accept: image/webp,image/*,*/*;q=0.8
Sec-CH-Width: 650

Sec-CH-Width value will contain the pixel width of the image in the page multipled by the display density. So if the image is 400 pixels wide on a 2x display, the value sent to the server will be Sec-CH Width: 800.

If both the browser and server support client hints, and the image is lazy-loaded, we can greatly simplify our markup:

<img 
  loading="lazy"
  src="cat.jpeg"
  width="650"
  height="400"
  sizes="auto"
  alt="My cat Boyle is super cute.">

We no longer need srcset because the server knows what image sizes are available or can resize the image as needed based on the image size supplied by Client Hints.

Because the image is lazy-loaded, we also know the size of the image in the page which means we shouldn’t need sizes at all. Unfortunately, the Client Hints standard expects the sizes attribute so we still need to supply sizes="auto". Perhaps this can change in the future and we can remove the sizes attribute as well.

How is an image source selected?

If we’re not supplying a list of image sources in srcset to the browser, how will one be selected? For this to work, you need an image resizing service on the server to respond to the image request. If you don’t have one, you can continue to use srcset and sizes.

If this approach takes off, image resizing services may want to change the way they select what image size to return. Instead of working from a list of image sizes that the web page author thinks might be needed, the server can monitor what sizes are requested the most and make sure those sizes are cached. The server can optimize the cached image sizes based on real world usage.

What about browsers that don’t support Client Hints?

Client Hints aren’t new. Chrome shipped them in v46 back in 2015. I wrote about their possible uses in 2016. But developers haven’t widely adopted Client Hints because Firefox and Safari don’t support them.

Because of this reality, I gave up on Clients Hints for many years. Three developments have caused me to revisit them:

1. The proliferation of lazy-loading images and the standard to support them means we have a large body of images for which the speculative downloader’s race condition doesn’t apply.
2. In my review of ImageEngine, I was impressed with how simple it is to use. Some of this simplicity is due to leveraging Client Hints when they are available.
3. Eric Portis has created a small JavaScript library that provides similar functionality for Cloudinary users in browsers that don’t support Client Hints.

Eric’s script works like this:

• If the browser supports Responsive Image Client Hints, the script does nothing.
• If Client Hints aren’t supported, the script looks for images with the loading="lazy" attribute.
• It also checks for some specific Cloudinary parameters in image’s src URL which tell the script that this image is one that it should modify.
• The script then updates the width value in the Cloudinary URL to send along the actual size of the image in the page.

I’ve modified the sample markup from above to show how it would look using Cloudinary and supporting Eric’s script:

<img 
  loading="lazy"
  src="[…]/upload/c_limit,w_auto:breakpoints:650/v1716911991/catbeans_zbh3iu.jpg"
  width="650"
  height="366"
  sizes="auto"
  alt="My cat Boyle is super cute.">

The key section in the image URL is w_auto:breakpoints:650:

• w_auto — This tells Cloudinary that the image is responsive and should be dynamically resized to fit the size of the image in the page.
• breakpoints — This tells Cloudinary to pick image sizes using a performance budget—a feature they created based on one of my articles. If performance budgets aren’t your speed, you can set a value for how many pixels before a new image is created on the server.
• 650 — this is the fallback width that should be used if the browser doesn’t send additional information via Client Hints.

If the image in the page was actually 900 pixels wide at 2x display density, the script would update the src to be:

  src="[…]/upload/c_limit,w_auto:breakpoints:1800/v1716911991/catbeans_zbh3iu.jpg"

For browsers that don’t support Client Hints, the actual size of the image in the page is added to the URL. This technique could be modified to work with other image resizing servers.

There are a few caveats with this script:

• It must be placed in the <head>
• It has to be a blocking script. You can’t async, defer, or use type="module".

Eric explains:

This script needs to see <img>s as soon as they are parsed, so that it can prepare to re-write their URLs as soon as they’re laid out. If the script executes after an <img> has been parsed, it won’t get a chance to do any of that; it’ll do nothing.

Luckily, it’s only ~950 bytes (~600B compressed).

Eric has created a couple of CodePen examples that show the script in action. One uses placeholder images and the other real images from WikiPedia.

I normally wouldn’t advocate for a blocking script, but this seems lightweight and the tradeoff is worth evaluating. Make sure to measure the performance impact on your site.

A JavaScript Solution? Really?

During the halcyon days of the RICG, not a month went by without someone proposing a way to solve responsive images using JavaScript. We repeatedly and patiently explained why JavaScript couldn’t be used because images are downloaded before JavaScript is processed.

Lazy-loading images outside the initial viewport changes this equation. We now have a small window of opportunity to modify lazy-loaded images so we can add the equivalent of Client Hints to their URLs when their size is known.

The End of Most Responsive Images

Responsive images syntax will always have a role to play. Not every web page will have a image resizing server and images visible in the initial viewport will still face the race condition that gave the RICG fits. Any images in the initial viewport shouldn’t be lazy-loaded.

Fortunately, most images on the web live below the fold and thus can be lazy-loaded. If they can be lazy-loaded, then we no longer face the intractable race condition that forced us to place presentation information in the sizes attribute where it doesn’t belong.

Moving to simpler responsive images will require some work. According to CanIUse.com, 78% of users have access to Client Hints. That’s a great start, but ideally we’d get other browsers on board. Firefox and Safari expressed privacy concerns with client hints which is why they didn’t implement them. I’m hopeful that some combination a mandatory permissions policy (e.g., primary domain and subdomains only would be ideal) and a more limited set of hints (image width and dpr only?), that we might be able to get other browser makers on board.

But even without these changes, it is possible now to remove srcset and simplify sizes using a combination of lazy-loading, Client Hints, and the techniques that Eric Portis has pioneered.

Mat concluded his article by saying:

I won’t miss all those hand-hewn sizes attributes; I never had any love for them to begin with. I will never experience a shred of nostalgia for a thing that I helped make real and inexorably bound to my name. A syntax was never the goal; the goal was always a mechanism. At the time, the web platform lacked a way for browsers to make smarter decisions about what image asset to request and when, and no amount of clever scripting or markup trickery would ever result in an asset request as fast or efficient as one the browser itself could make.

None of us working in the RICG were ever enamored with our solutions. We wanted something simpler, but srcset and sizes was the best we could do with the constraints we were given. Now that lazy-loading has removed one of the constraints, I believe we can do better.

Special thanks to Eric Portis, Mat Marquis, and Scott Vandehey for their feedback and to Tyler Sticka for the grim reaper illustration.

We’re Cloud Four

We solve complex responsive web design and development challenges for ecommerce, healthcare, fashion, B2B, SaaS, and nonprofit organizations.

See our work

No database breach was found, so no action is required on your part. The breach only sought to redirect links to a malicious download, and no personal information was accessed.

With this situation – as I've been working on only it for the past two weeks – I have realized this project may have reached the ceiling of effort on my part. I have been partially over my head technically and partially burnt out from the process.

After the Autumn/Winter issue, I wrote a personal blog post about how it felt to publish a magazine. In response, I received a bounty of responses of folks willing to learn the programs or experienced in design. I cried at the response and found myself unable to reply, in shock at the thought that folks would actually step up and help. Thank you to everyone who reached out, genuinely. I wish I had asked for help sooner.

I must confess: I have entirely lost money on Good Internet, despite a not-insignificant amount of folks who supported the project. I undercut myself and tried to keep the magazine affordable. Without scale, print media is – shocker to no one – expensive. Unfortunately, my well has gone dry, both energetically and financially.

Good Internet completed a full volume, but I do not feel comfortable maintaining subscriptions during this indefinite hiatus.

Immediately:

1. All subscriptions, monthly and annual, will be canceled.
2. Print editions of Spring 2025 are still available for purchase.
3. Any further issues will be announced via email.

High resolution and low resolution Digital Editions will be available for download to all free members in a couple of weeks.

All money that was received from 2026 subscriptions are going into the digital infrastructure of Good Internet, including hosting through our new host and email services. Please reach out if you'd like a refund, which I entirely understand at this stage.

I'd like to keep the site up for archive, so at least through the end of the year. I'd like to reassess then, also, and consider if Good Internet comes back in 2027. I'll notify you as soon as I know. If you'd like to continue supporting the website and project, feel free to contribute – you'd be helping me a lot.

I know this decision will be met with mixed reactions, but I want to thank you so much for your continued support and belief in this project. I love each and every single one of you. From the bottom of my heart, thank you.

x Alexandra
personal email: al@xandra.cc

But… it would animate backwards upon closing, “rewind” so to speak, which is exactly how CSS should work, but I wanted it to “complete” the rotation, so:

1. idle: start at 0 degrees
2. expanded: go to 180 degrees
3. closed again: go to 360 degrees
4. idle: start at 0 degrees
5. … and so on.

Let’s take a look at what I tried, and which solution I landed on.

First, here is the base markup and styles for all the demos:

<details>
	<summary>
		<span>Learn more about this!</span>
		<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" class="details-marker">
			<path d="M6 9l6 6 6-6" fill="none" stroke="currentColor" stroke-width="2" />
		</svg>
	</summary>
	<div class="details-content">
		<p>I have important things to say!</p>
	</div>
</details>

details {
	--DET-transition-duration: 300ms;
	--DET-transition-easing: ease-in-out;
}

/* Rewinds upon closing */
.details-marker {
	@media (prefers-reduced-motion: no-preference) {
		transition: transform var(--DET-transition-easing) var(--DET-transition-duration);
	}

	details[open] & {
		transform: rotate(180deg);
	}
}

/* Aesthetics skipped for brevity but available in the CodePen demos */

And here’s what that looks like: it works everywhere but the marker “rewinds” — keep an eye on that chevron at the end of the line there when opening and closing the details/expander/accordion/stretchyboi:

View on CodePen

I managed to get most of the way using a registered custom property to hold the “opened” state until everything was closed, using a transition on this property with a step-end timing function, which holds a value at its initial state until the duration has passed (e.g. from 0 to 1 over a second, it’ll stay at 0 for a second, then immediately flip to 1 without any interpolation). My original (and promising) result looked like this:

@property --DET-state {
	syntax: '<number>';
	initial-value: 0;
	inherits: true;
}

details {
	--DET-state: 0;
	--DET-transition-duration: 300ms;
	--DET-transition-easing: ease-in-out;
	
	transition: --DET-state var(--DET-transition-duration) step-end;

	&[open] {
		--DET-state: 1;
	}
}

/* "Works" in Chrome and Safari, but unwinds after closing */
.details-marker {
	@media (prefers-reduced-motion: no-preference) {
		transform: rotate(calc(360deg * var(--DET-state)));
		transition: transform var(--DET-transition-easing) var(--DET-transition-duration);
	}

	details[open] & {
		transform: rotate(180deg);
	}
}

View on CodePen

It did almost everything I wanted (in Chrome and Safari…), going from 0 degrees, to 180, and to 360 on close, except… when the rotation was completed, and --DET-state returned to 0, the marker would also transition from 360 degrees to 0 degrees, so it looked kind of loopy (pun intended, thank you very much, I’ll be here all week).

I tried a few things, like adjusting the timing function between open and closed states. Ultimately, I came to the conclusion that I needed the closing transition to run normally while --DET-state was held at 1, but the second transition due to --DET-state flipping back to 0 should be skipped. I could achieve this by adjusting the transition-duration itself, but this doesn’t work in Firefox and Chrome — Safari does what I expect of it, in version 18.6 as well as Technology Preview:

/* This does not work in Firefox and Chrome! */
.details-marker {
	@media (prefers-reduced-motion: no-preference) {
		transform: rotate(calc(360deg * var(--DET-state)));
		transition-property: transform;
		transition-timing-function: var(--DET-transition-easing);
		transition-duration: calc(var(--DET-state) * var(--DET-transition-duration));

		details[open] & {
			transition-duration: var(--DET-transition-duration);
		}
	}

	details[open] & {
		transform: rotate(180deg);
	}
}

View on CodePen

Instead of quashing the duration, I tried using a negative transition-delay, and I clicked in disbelief several times to see the marker animate exactly as I wanted. My final result is as follows:

/* This does not work in Firefox! */
.details-marker {
	@media (prefers-reduced-motion: no-preference) {
		transform: rotate(calc(360deg * var(--DET-state)));
		transition: transform var(--DET-transition-easing) var(--DET-transition-duration);
		transition-delay: calc((var(--DET-state) - 1) * var(--DET-transition-duration));
		/*
			The delay above could also be expressed like so, if you find it easier to read:
			transition-delay: calc(-1 * (1 - var(--DET-state)) * var(--DET-transition-duration));
		*/

		details[open] & {
			transition-delay: 0s;
		}
		
		@-moz-document url-prefix() {
			transition: transform var(--DET-transition-easing) var(--DET-transition-duration); /* Standard look in Firefox */
		}
	}

	details[open] & {
		transform: rotate(180deg);
	}
}

View on CodePen

However, as mentioned at the start of this article, this does not work in Firefox. Which sucks! These properties are not exactly bleeding edge… I know I’m manipulating time in weird ways here, but this doesn’t require a flux capacitor… it feels like it should work.

In any case, in Firefox, with a little browser-specific hack, the transition is reverted and the chevron rewinds back to 0 degrees instead, which means it’s still absolutely usable, and I consider this a nice little progressive enhancement.

I am certain there are ways to make this work: maybe some trick using mod() off by 0.01deg, or adding in a CSS keyframe animation (I specifically avoided keyframes as you cannot smoothly reverse the transition if you interrupt it midway). Definitely easy with some JavaScript (either Web Animation API or an event listener), but that’s no fun!

If you have ideas, I’d be happy to hear some details and expand this article accordingly (eehhh?).

PS: As a bonus, we can totally have the chevron face to the right when closed, down when open, and still do a full rotation!

View on CodePen

Update

vrugtehagel and Temani Afif chimed in on Mastodon with different solutions, which work cross-browser! Not only that but they both require less code, so I’m all for it.

vrugtehagel suggested using linear() to create a negative version of the easing, and it works! A little bit of a pain to maintain if you want to adjust the easing but I wouldn’t imagine you’d change that often, so this is really neat!

View on CodePen

Temani suggested something even simpler, that kind of resonates with my negated duration approach, but applied to a different property. Because the chevron is symmetrical, mirroring it allows to get the same effect: rotate then mirror.

View on CodePen

Bluesky has always supported a few open graph meta tags which I use to generate images for blog posts. That’s part of the social media game; get in people’s faces as loudly as possible. Now the game has changed!

Fancy button

I return Monday ready to work and suddenly I start seeing a fancy new “View publication” button appear in my Bluesky feed. I’ve never wanted nor needed a button before but now that people are rocking buttons, what am I supposed to be, a buttonless pleb?

I got my own button it looks like this:

Mat Marquis, fellow button connoisseur, was quick with a guide to “Implementing Standard.Site” which I hastily copied.

Automation

Mat used an atproto explorer to edit records which is akin to rawdoggin’ SQL in production. Given the weekly GitHub and NPM malware party this is probably a safer play than running npm install yourself. I’m never going to remember to publish manually though.

I have a janky build script and some experience with the @atcute libraries. How hard can it be? My script begins by generating a manifest of pages by parsing markdown before rendering the HTML template.

I added a new step that fetches all atproto records in the site.standard.document collection. It cross-references the paths in my manifest. Any unknown path has the record deleted. It then iterates the manifest and either updates the atproto record (if title or description has changed), or creates a new record if none existed. Finally it adds the atproto URI to the manifest for the <link> element.

Now my blog is standard.site and I have a fancy button to prove it.

Thanks for reading! Follow me on Mastodon and Bluesky. Subscribe to my Blog and Notes or Combined feeds.

It’s a cool feature! There’s loads of different platforms doing cool stuff, all using different data structures, so the standardisation was really needed. Integrating is fairly straightforward too.

If you’re using WordPress, for example, it’s as simple as using a plugin. There’s an Astro plugin too, along with all of your favourites (I imagine).

I’ll write up the details as part of my ongoing series. I’ll definitely be getting on that towards the end of the month too as my studio workload quietens down a bit.

Was it all a bit of a faff to integrate? Yes. Did I get rate limited multiple times? Absolutely. But do I think it’s worth doing? I think Standard.site is going to do wonders for website discovery, so without a doubt.

“At last,” said the most tired-looking man you have ever seen in your life. “A standard for fancy little social media preview cards.”

Well, that wasn’t entirely fair. For a lot of people, the immediate appeal is a shiny new preview card when posting a link to a service that runs on the AT Protocol, and Bluesky being the biggest and most visible of such services means that this feature landed as a kind of novelty — a way to add a themed button to links posted to Bluesky. I assumed this would be in exchange for yet another thing crammed into the head of a document alongside all the meta tags for Open Graph, defunct Twitter cards, and whatever nonsense LinkedIn or Pinterest or LiveJournal or Friendster or whatever currently expects of us.

There’s a more to it than that, both technically and conceptually — and potentially quite a bit more to the latter for us die-hard Publish [on your] Own Site, Syndicate Elsewhere (POSSE) enthusiasts in the years to come.

As it stands now, there’s a necessarily manual step in the POSSE process when it comes to social media: the syndication efforts fall to you. If you’re doing it right, you’ve rigged up some kind of process that posts links to your work to various social media sites for you — as long as you have an account on all of them, and none of their APIs change, and you didn’t get rate-limited, and you didn’t forget any. If you’re doing it like me, you’re copying and pasting your freshly-published link into textareas provided by four different websites, one of which contains a typo, and the fifth of which you forgot about until a few days later. In either case, this syndication step is effortful — a necessary step that needs to be taken to broadcast your work to the world, wholly dependent on you doing it, and you knowing where your potential audiences are. For example, I don’t post anything I write on Twitter due to my having self-respect, so nothing I write appears there, full stop. I have no doubt that there are a half-dozen other social media websites out there where I don’t have an account — or ones I straight-up don’t know about — where I certainly wouldn’t mind seeing my work appear, but it likewise does not. No matter how robust or mechanically-streamlined your approach to POSSE might be, the “SE” part of the equation still involves work for the part where you chuck “social cards” at various and sundry services like social media Gambit, even if your publishing process does that work for you.

Now, compare this pattern to good ol’ RSS, darling of POSSE enthusiasts the world over — you publish your post, you publish a feed that contains that post, and the contents of that feed are out there in the world for sites and services to consume. At no point do you need to “remember” to post the title and a link to, say, Feedly — someone using that service has subscribed to your site, so that post appears in their feed. You own your platform, you own your content, the end user decides on the medium.

Standard.Site aims to do something similar for any platform powered by the AT Protocol. The Standard.Site schema provides you with a set of lexicons you use to describe your website and the individual pages and posts on it in a way where they can be parsed by a service that runs on the AT Protocol — an “App View,” in the language of their standard — which would allow users to subscribe, via that service, to your domain. The most obvious use case is allowing users on a platform like Bluesky to subscribe to an RSS-like feed of, say, blog posts, the way they would follow any other account on the service. If you tease that use case out just a little from there, it paves the the way for microblogging powered by your own website, with the content hosted and fully owned by you. If a specific platform used to subscribe to your website becomes, say, too morally reprehensible to stomach, or they trip over a network cable and spill a big bowl of spaghetti all over their servers, or both, the result is a situation more “end of Google Reader” than “end of Twitter” for you and for anyone consuming your content. Anyone can subscribe to your website — where all your content lives — via any AT-Protocol-powered service, since they’re all speaking the same fundamental language.

It all sounds great on paper for sure, but I had the same kind of “own everything, syndicate everywhere” hopes for Mastodon, too — I still kinda do, truth be told. I set up my own little Fediverse test server back at the height of Mastodon and, no, not for me; I like using it just fine, but owning it all was too much of a lift. I want to own my content, but I don’t want to own running an instance — something with its own UI, something with uploads in need of managing, something my experience of a larger network is routed through, something in need of privacy controls and preferences and settings and management. I put borders on stuff for a living. I just want a website; I want my website. In theory, that’s the intent of AT Protocol, as I understand it: my website, used and updated the way I want to, acting as an API.

Also, okay, yes, in the much nearer term, I want a neat little preview card with a theme-able button. Of course I want a neat little preview card with a theme-able button. I’m not made of stone.

So, my goal was to tinker with the steps outlined in the Standard.Site quick-start guide with as little overhead as possible, and that meant reusing the Personal Data Server (PDS) already provided to me by Bluesky rather than spinning up my own — not the long-term plan, but enough to get a feel for things. I pulled myself up on Atmosphere Explorer, logged in, and added a record for my “publication” — my website — named site.standard.publication:

{
  "$type": "site.standard.publication",
  "url": "https://wil.to",
  "name": "Wil.to",
  "description": "My name is Mat Marquis, and I believe in the web.",
  "preferences": {
    "showInDiscover": true
  }
}

Check.

Then, over here on the site, I spun up a new page pointing to that newly-created record — did:plc:mlmtsmr3fcbhffjoydyg3663 being my account, site.standard.publication being the (standardized) name of the record, and 3mnf7wqnkaf2b being the generated key for the publication record (placeholdered in the Standard.Site documentation as rkey):

---
permalink: /.well-known/site.standard.publication
---
at://did:plc:mlmtsmr3fcbhffjoydyg3663/site.standard.publication/3mnf7wqnkaf2b

And to cover my bases, added a link to the head of my site:

<link
  rel="site.standard.publication"
  href="at://did:plc:mlmtsmr3fcbhffjoydyg3663/site.standard.publication/3mnf7wqnkaf2b"
/>

That’s the easy part done. So far as AT Protocol is concerned, my website now exists as a publication with no documents. So, just to get my bearings, I’ll start by adding a document manually: this very post. Same process as adding a publication record — I hop over to Atmosphere Explorer and create a new record named site.standard.document:

{
  "$type": "site.standard.document",
  "site": "at://did:plc:mlmtsmr3fcbhffjoydyg3663/site.standard.publication/3mnf7wqnkaf2b",
  "title": "Implementing Standard.Site",
  "path": "/posts/standard-site",
  "description": "I tell you, I have high hopes for this one. I hope it sticks.",
  "publishedAt": "2026-06-03T15:26:19.516Z"
}

At time of writing, the docs have a record key in place of an rkey placeholder, so watch out for that — that site property should end with the record key for the publication record you created earlier. I’m not including the textContent property mentioned in the documentation, because that’s not something I want to copy and paste and un-format for a test run; I’ll want that eventually though, once this process is automated, so I could theoretically syndicate entire posts.

The next step calls for a link in the head of the associated document:

<link
  rel="site.standard.document"
  href="at://did:plc:mlmtsmr3fcbhffjoydyg3663/site.standard.document/3mnfcoxoqsy2w"
/>

Can’t just drop that in across the board if I want it associated with the one post, so a quick kludge to get things minimally-viable:

{% if permalink ==  "/posts/standard-site/index.html" %}
<link
  rel="site.standard.document"
  href="at://did:plc:mlmtsmr3fcbhffjoydyg3663/site.standard.document/3mnfcoxoqsy2w"
/>
{% endif %}

I push all that up to production, fire up the Standard.Site validator, quietly fix the one place where I had left a stray rkey placeholder, push to production again, et voila: a new preview card.

Working as a prototype, at least. As it stands now, that preview card is a mish-mash of Open Graph and Standard.Site — the thumbnail, for example, is coming from the former. The Standard.Site document lexicon covers things like the thumbnail (coverImage), of course — Bluesky is aware of the thumbnail thanks to the og:image, but anything parsing this as-syndicated across the I-have-too-much-dignity-to-say-“ATmosphere” wouldn’t necessarily pick that up. I’ll need to get that situated at some point.

More pressingly, this is entirely manual, just to get my bearings — only this one document is set up with a site.standard.document record, copied-and-pasted into place. I’ll need to wire something up so that anything I publish here includes a step where an associated site.standard.document is created via API. That permalink string-check for the meta tag has to go, too. In the grand scheme, I’d want to move this off of the Bluesky PDS and fire up my own PDS, on my own server, of course.

But more than any of that, I think we can all agree on the most important part of this process, which takes precedence above such petty issues as “automation” or “maintainability.” I gotta theme that button:

{
  "url": "https://wil.to",
  "name": "Wil.to",
  "$type": "site.standard.publication",
  "basicTheme": {
    "$type": "site.standard.theme.basic",
    "accent": {
      "b": 239,
      "g": 65,
      "r": 54,
      "$type": "site.standard.theme.color#rgb"
    },
    "background": {
      "b": 252,
      "g": 252,
      "r": 252,
      "$type": "site.standard.theme.color#rgb"
    },
    "foreground": {
      "b": 63,
      "g": 7,
      "r": 18,
      "$type": "site.standard.theme.color#rgb"
    },
    "accentForeground": {
      "b": 252,
      "g": 252,
      "r": 252,
      "$type": "site.standard.theme.color#rgb"
    }
  },
  "description": "My name is Mat Marquis, and I believe in the web.",
  "preferences": {
    "showInDiscover": true
  }
}

Now we’re talking.

We solved this by giving editors an option to pick the appropriate heading level in the CMS. That works, but it means more work for them, because they need to keep track of the document outline, and it's also a potential source of error.

The headingoffset attribute

Yesterday, I heard about a new experimental attribute that offers a better solution to this problem. The heading offset content attribute allows us to offset heading levels for descendants.
Let's take the outline from the page in the screenshot and see how we can make it more context-aware.

<h1>Museums</h1>
<section>
  <h2>Free entry to the museum</h2>
</section>
<section>
  <h2>All museums and collections</h2>
  <h3>Aphabetical</h3>
  <h3>By district</h3>
</section>

First, we turn all headings into H1s. Then we add the headingoffset attribute with a value of 1 to every parent element where we want to increase the heading level by 1.

<h1>Museums</h1> <!-- heading level 1 -->
<section headingoffset="1">
  <h1>Free entry to the museum</h1> <!-- heading level 2 -->
</section>
<section headingoffset="1">
  <h1>All museums and collections</h1> <!-- heading level 2 -->
  <div class="cards" headingoffset="1">
    <h1>Aphabetical</h1> <!-- heading level 3 -->
    <h1>By district</h1> <!-- heading level 3 -->
  </div>
</section>

The heading offset attribute increases the current heading level by the specified number; in this case, by 1 (h1 + 1 = h2). The H1s inside the sections become H2s and the H1s nested in another heading offset container become H3s.

In the accessibility panel in Firefox, you can see that the tag for the “All museums and collections” heading is H1, but the level is 2.

Now that we know how it works, let's do a quick Q&A based on the questions I had when I first saw this.

On a really large page, I would need a bachelor's degree in maths to create the document outline. Is using an h1 for everything really a good idea?

I don't think so.

I've been waiting for this feature for years. I think it's fantastic and super helpful, but the example I showed you is not necessarily the best use case. I probably wouldn't use heading offsets for static HTML documents, because the document is much easier to read if the tag name represents the actual heading level.

It gets really interesting when you don't have immediate access to the headings or control over the page's structure. For example, when you're working with components.

Here's an example of the same structure built with a web component. When we write the markup, we don't see the heading tags because the web component renders them for us.

<the-section heading="Free entry to the museum"></the-section>
<the-section heading="All museums and collections">
    <the-section heading="">
        <div class="cards">
          <h1>Aphabetical</h1> <!-- heading level 3 -->
          <h1>By district</h1> <!-- heading level 3 -->
        </div>
    </the-section>
</the-section>

class Section extends HTMLElement {
  static observedAttributes = ["heading"];

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'heading') {
      this.shadowRoot.innerHTML = `
      <section headingoffset="1">
        ${newValue != '' ? `<h1>${newValue}</h1>` : ''}
        <slot></slot>
      </section>
      `
    }
  }

constructor() {
    super();
    this.attachShadow({ mode: "open" });
  }
}

customElements.define("the-section", Section);

For the page I showed at the very beginning of this blog post, this would be perfect because we, as developers, have little to no control over how editors will use the components.

Can I opt out of the algorithm for specific headings?

Yes, by using the headingreset attribute on a parent or the heading itself.

<h1>Museums</h1>
<the-section heading="Free entry to the museum"></the-section>
<the-section heading="All museums and collections">
  <the-section heading="">
    <div class="cards" headingreset>
      <h3>Aphabetical</h3> <!-- heading level 3, not affected by the headingoffset -->
      <h3>By district</h3> <!-- heading level 3, not affected by the headingoffset -->
    </div>
  </the-section>
</the-section>

Do I always have to use H1?

No, you can use whatever you want, but in our example, h2s would become h3s.

<h1>Museums</h1>
<section headingoffset="1">
  <h2>Free entry to the museum</h2> <!-- heading level 3 -->
</section>
…

What happens if you set the value to 2?

The h2 becomes an h3 because h1 +2 = h3.

<h1>Museums</h1>
<section headingoffset="2">
  <h1>Free entry to the museum</h1> <!-- heading level 3 -->
</section>

What happens if you set the value to 14?

The h1 turns into a heading level 9. I'm not exactly sure why, but the maximum offset is 8, and if the heading level is greater than 9, it always returns 9.

<h1>Museums</h1>
<section headingoffset="14">
  <h1>Free entry to the museum</h1> <!-- heading level 9 -->
</section>

Can I use a negative number for the offset?

No.

How can I style an H3 when there's no H3 tag?

You can use the headings pseudo-class, which is currently only supported by Firefox Nightly.

:heading(3) {
  color: fuchsia;
}

Do screen readers support it?

I don't think screen readers need to support anything; if the information is correct in the accessibility tree, they'll read the heading levels accordingly. I tested it with VoiceOver and it always announced the correct heading levels.

How's browser support?

This feature is brand new and currently available only in Firefox Nightly, behind a flag. If you want to test it, type about:config into the address bar, proceed to the next step, search for dom.headingoffset.enabled, and enable it.

If you like this feature, then make some noise and encourage other browser vendors to implement it.

Conclusion

Heading offset is a long-awaited feature, and I hope it will soon make its way into other browsers as well. The implementation, as it stands, seems very sensible to me. Thanks, Keith, et al.

My blog doesn't support comments yet, but you can reply via blog@matuzo.at.

I guess WordPress 7.0 assumes you are using a theme.json file these days. I’m not doing that yet on any of the sites I work on. If you want to embrace that future, you could add a theme.json file to the root of your theme, and put some typography basics only in there:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "layout": {
      "contentSize": "720px"
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "system-ui, sans-serif",
          "name": "System Font",
          "slug": "system-font"
        }
      ]
    }
  },
  "styles": {
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system-font)",
      "lineHeight": "1.75"
    }
  }
}

That will be much nicer than no styles at all.

Or if you don’t want to mess with that you can go to the upper-right three-dot menu (“Option”), choose Preferences then go to the Appearance tab and make sure Use theme styles is unchecked.

I think it’s sorta neat that you could use the same typography setup for both the front-end and back of your site this way, and if you use theme.json for the front, might as well use it for the back. But I also personally don’t mind if the back-end is entirely default styles. It’s a reminder that you’re in a CMS, and content is data, not WYSIWYG.

I know this is gonna sound a little navel-gazesque from the jump, but yesterday I had something I’d written dismissed as the “work” of an LLM. According to their comment, the reader saw a bunch of emdashes up-front and bailed on the rest of the article. If you can believe it, this was the first such comment I’ve gotten, despite the hundreds of thousands of words — and almost as many emdashes, case in point — that I’ve written over the past few years. I won’t link to it here because I wouldn’t want anyone piling onto a thread on an unrelated post, and because I don’t really fault the person for saying it; leave 'em be.

For one thing, I do use too many emdashes. Listen, I read a bunch of Kerouac a long time ago. I don’t apologize for the emdashes; I do apologize for my reading habits back when I was twenty-mumble years old, but that’s only semi-related.

Mostly though, I don’t fault them for the impulse that drives that kind of comment. Hell, I agree with it: generated text, assembled by nobody and increasingly for nobody, should be dismissed. Even leaving aside the lack of craft, dubious accuracy, and insultingly cloying and sycophantic tones: why should anyone care about reading something nobody cared enough to write? If a publication is willing to pad itself out with the prose equivalent of Circus Peanuts — to take you, the reader, for an easy mark — I agree that you should hold them in lower esteem, if not outright scorn. If I thought I was being tricked into eating a meal stretched with sawdust, I’d be left feeling angry and dismissive of the meal, chef, and restaurant too. I’ve been there — reading-wise, I mean, not eating-wise. I know that “hah, gotcha; they’ll never put one over on me” feeling. It feels ~good to catch on to the fact that you’re being tricked, the way it feels ~good to prod at an aching tooth. It could be that I’ve been wrong about it before too — I bet I have been, but I’ll never know. I can’t know, by design.

The only “advancement” in generative AI, since its inception, has been in slowly getting better at fooling us into thinking its output isn’t generative AI. It is software designed to put strings in the most statistically likely order that an average human would. It is meant to trick us, at its core; an engine with “passable sentence” as its sole ideal output. Why else would it make us so angry? Why else would so many of us want to lash out at the sight of it, whether real or imagined? Why else would we “boo” these hollow-eyed, out-of-touch ghouls that try to advertise their “AI” investments during commencement speeches? Hell yeah; good. Send a message — call it out for what it is, and dismiss it loudly and in no uncertain terms.

Which is how my work got dismissed. It stung — it stings, sure — I mean, c’mon, same team — but I get it. I really do. I mean, look at the start of this paragraph, which I’m now refusing to go back and edit for illustrative purposes. Hell, I’m starting to suspect me a little. Emdashes have come to represent the big glowing weak point on the boss monster that threatens to consume the livelihood of so many of us; something recognizable, from a hundred paces, as a sign that something is dismissable. Of course we’re gonna attack it on sight. I also want to take a swipe at the grey goo threatening to smother both the web that I’ve worked so hard to build and the career I’ve been so fortunate to have.

But my second reaction, after the flash of “the robots can have my emdashes when they pry them from my cold, dead hands” anger and just a whisper of “what’s the point of even writing” was that I’m privileged in that I can shrug this off. I am established — I’m here, and you’re reading this now, for some wild reason. I’m “a long time out from reading Kerouac,” as we emdashers of a certain age call it — forty-mumble years old, nearly half of which was spent here, doing this. I’ve done a lot of writing over a lot of years, and I’ve been fortunate enough to get it in front of a lot of people. I’m not the thing that gets us out of this mess. I can’t be.

These tools, to the extent they can or should ever be personified, want rid of me pretty bad — but not half as badly as they want to prevent another one of me from ever happening again. The explicit goal of generative AI is to fill the role of “junior-level” everything the way insulating spray-foam in a car’s exhaust pipe might help prevent excessive engine noise. This technology exists to keep entry-level workers pruned all the way back to the roots, in the interest of keeping wages low, employment tenuous, staff nervous, and the unfathomably rich insulated from the potential financial repercussions of destroying countless lives. If you can never advance beyond “press the button, generate the thing,” you’re as replaceable as the next person — if there’s nothing beyond entry-level experience, they’ll never have to pay you more than an entry-level salary. They’ll destroy you, me, the web, the environment — anything but their valuations — to finally realize their long-held dream of “entry level position, five years of experience required.”

That’s why I’ve been writing so much more lately. That’s why I spun up this blog, finally, for-realsies, as small as its voice is. That’s why I’ve been trying to eke out more of a living writing courses and articles and picking fights about web standards, a thing I swore I would never do again, despite that being exceptionally difficult to do in this climate; despite the constant, crushing discouragement — a topic for another post altogether.

I’m doing this because I also want to take a swipe at these garbage machines, and this is the only infinitesimally small way that I think I could: by helping people to learn and improve out of spite for the people who’ve foisted these machines upon us, and would see the world burn to fuel them. I want us to want more — more than “press the button to generate the thing,” more than a life of “junior-level.” I want to chip at the wall they’re trying to build between you and “more.” I want new voices sharing what they know and what they’re learning — they’re doing so against unfathomable odds, in a climate far more difficult than things were back when I first clawed my way here. I’m barely hanging on here, and again: easiest difficulty setting. Don’t risk making things even harder for them.

For anyone stumbling on this thread, this post unequivocally [was not generated by an LLM], either in whole or in part. I do not use LLMs, full stop.

Now, whether or not you personally believe that is your business. What I would ask you to do, though, is imagine that an author might be someone that bristles every bit as much as you do at the idea of technical writing — something they do professionally, for personal fulfillment, or both — being systemically devalued by these tools. Imagine then having their work dismissed as slop; imagine the kind of “why bother” message that would send to an author less established than I am. Imagine your comment on a junior developer’s proud first post.

I agree that you shouldn’t value generated text. You don’t have to value my writing either, honestly — plenty don’t, I’m sure. But if you value real, human writing the way I think you do, I’d ask you to please be more careful about dismissing it as the very thing trying to rob it of value. I’m not going anywhere, but a brand new voice might, and we need those desperately right now.

I know you’re angry; I am too. I know you want better for us too — don’t let that anger risk silencing new voices, though. Don’t let it make you think that you’ve stumbled onto some secret, glandular instinct that makes you — and you alone — immune to something specifically engineered — to the tune of trillions of dollars — to trick you. Do not risk silencing even one new voice — our only way through this mess — just to take an easy and self-satisfying swing at a switch statement that can’t hear you anyway. Some of us just write this way.

There are real people deserving of that anger. Save it for them. Make sure they’re the ones that hear it. Say it to their faces as you climb over them.

Modern Web Guidance is a set of evergreen and expert-vetted skills that guide your AI coding agents across many common use cases to build modern web experiences that are accessible, performant, and secure.

I appreciate this set of LLM skills lists accessibility first, something I feel strongly every MVP (or early preview as Google calls this) must:

Simply, if your MVP does not have accessibility factored in, it is not viable. If you claim accessibility is a core principle but your version 0 does not include it, then it is not a core principle.

Last year I made a straightforward and simple request to Google (that also respects the law in most jurisdictions where Google does business):

Please, if your team cannot explain how the thing satisfies all WCAG Success Criteria at Level AA, then don’t release the thing.

Unfortunately, MWG accessibility doesn’t satisfy. Partly because not every pattern has tailored guidance. For example, you may remember when Google ran at a toast pattern before abandoning it:

Again, the people designing the feature neither understood accessibility nor had consulted anyone who did while they designed it, instead relegating accessibility to the later stages of their design and assuming it could simply be remediated with a modest effort and without any serious redesign or rethink.

I hoped Google also remembered and applied that experience here, making a skill tailored to toasts to avoid another debacle. Nope.

Reopening because this guide needs accessibility guidance in some form as there’s no general toast guidance.

But this is an early preview of what developers can do with MWG. It’s not going to cover every pattern. That would be absurd. So let’s look to a pattern Google decided to showcase at launch via this first example prompt on the page:

Create an accordion-style stats component that smoothly animates on open and close.

I expected a pile of <details name> elements, maybe CSS block-size with a JavaScript fallback, probably a couple placeholder images for generic stats, possibly a well-formed table to accompany them, and of course all of it passing WCAG. This is what Antigravity produced with MWG:

See the Pen Google Modern Web Accordion by Adrian Roselli (@aardrian) on CodePen.

Antigravity with MWG went well beyond the prompt, providing a theme switcher, configuration settings, and plenty of calls to Google fonts. But it failed to do what I asked. The animation doesn’t work in Firefox. This despite the promise of baseline / Baseline support and fallbacks:

• Progressive Enhancement & Nuanced Fallbacks: We distinguish between purely additive enhancements (like speculative preloading) which are safe to let older browsers silently ignore, and critical behaviors (like dialog controls or network beacons) where we write highly considered, low-overhead fallbacks.
• […]
• Baseline-Aware Integration: We leverage real-time compatibility data from the Baseline project so agents can dynamically adapt to current browser support and any browser support preferences.

This is already worrisome given we know that three years on, Baseline still doesn’t really address baseline support:

The relatively new Web Platform Baseline offering does not track browser support for accessibility features built into the web platform. If you need to understand whether browsers support accessibility features as your own base level set of requirements, for legal or other compliance reasons, then Web Platform Baseline does not represent a baseline.

Let’s ignore the non-DRY code, like duplicated HTML text in the script and stringing out the transition instead of using transition-property. Antigravity with MWG didn’t even create a WCAG-conformant example from its own prompt. I found errors within moments. MWG failed its core promises of creating accessible and performant code. Despite its own explicit guidance.

For the first two of these MWG already had guidance, and the a11y skill just wasn’t picked up. Overall activation aside, this highlights the importance of including contextual a11y information.

[…] [W]e should try to have one guide for each common interactive element summarizing and linking/embedding relevant bits of guidance (e.g. tabs, accordions, drawers, etc). The more scattered the use case guidance is, the less likely it is that agents will actually pick up all the pieces.

And there’s the rub. There’s no way to guarantee you’ll get what you ask for, that you won’t get something else, and that these guides — the entire promise of MWG — will be honored. MWG asks authors to trust MWG when using an LLM to code interfaces. But MWG knows its guidance may be ignored:

LLMs are non-deterministic. Even if we do everything right, there is no guarantee any guideline will be used for any given prompt. Even if the relevant guide is picked up, it may not be read fully. Case in point: As you say, MWG already had guidelines for many of these things!

The underlying code generation technology can’t be trusted to follow the rules and the rules aren’t robust enough to blunt that reality.

If your job requires you to burn tokens to satisfy some manager’s dashboard, then yes, grab the MWD skills files and integrate them into your LLM work. You’ll almost definitely get better output than if you do nothing at all. There are smart people working on this and many of the accessibility rules I saw were on-point.

But that output will be wrong in subtler and more nuanced ways across potentially fatter piles of code with more unrelated output and unwanted dependencies. It will require a more specialized set of skills to identify errors. And those errors will be different every time the code is generated.

So on the side, keep supporting any existing pattern library. If it’s built well, it’s copy-ready code that you can stuff into a project just as quickly as a chatbot could generate it. It’s deterministic, so you get the same code every time. Ideally it’s been vetted, so you don’t need to look for errors. It’s tailored to your context, meaning you don’t need to yank out random style switchers and typefaces (hoping you got all the dependencies).

If your job doesn’t require you to burn tokens, then probably ignore MWG and, by extensions, LLM for code. In case the environmental damage, intellectual property theft, wealth redistribution to the rich, encoded biases, and built-in support of fascism weren’t enough.

Update: 24 June 2026

The Silktide blog has this banger of a quote:

Across the board, [Google Antigravity using Modern Web Guidance] was a deprioritization of accessibility requirements in favor of visual presentation.

I don’t agree Antigravity nor MWG should use APG, which a regular visitor here may know, but the author is correct the APG disclosure pattern is mostly harmless.

But Silktide is right that the, once again, Google built the wrong thing for the wrong people and then proudly shoved it out into the world with no hint of self-awareness.

What’s a shorthand property?

CSS shorthand properties let you set a bunch of related values in a single declaration. There are quite a few of them, some more widely used than others.

One you may be familiar with is the background property, which can set the image source, position, size, repetition rules, origin, color, clip threshold, and scroll behavior all at once:

.selector {
  background: url(“/images/my-image.jpg”) 1rem 1rem / 50% 75% no-repeat fixed content-box padding-box orange;
}

Do you know what each of those values corresponds to? Some are obvious. orange is clearly the background color, and the URL is the image. But the numeric values and the content-box/padding-box pair? I have to look those up every single time.

That’s exactly the kind of situation where I’d rather just write it out.

When to use it, when to skip it

When the ordering is intuitive

Directional properties like padding and margin are generally fine to shorthand. I’ve committed the ordering to memory (clockwise from the top side), which is what makes them feel safe. The number of values determines what gets applied.

One value applies to all four sides:

.selector {
  padding: 1vw;
}

Two values split into y-axis then x-axis:

.selector {
  padding: 1px 10%;
}

Four values apply clockwise from the top (top, right, bottom, left):

.selector {
  padding: 1rem 10rem 3rem 2rem;
}

The three-value version, though? I always forget that the second value applies to both right and left. I’d rather write them out individually than trip over that every time I read it back.

So this:

.selector {
  padding: 1px 5rem 2rem;
}

Becomes this:

.selector {
  padding-bottom: 2rem;
  padding-left: 5rem;
  padding-right: 5rem;
  padding-top: 1px;
}

An even more resilient pattern is to use logical properties rather than strict directional ones, to account for layout changes across different languages and writing modes. In a left-to-right language like English, padding-inline maps to left and right, and padding-block maps to top and bottom. In a right-to-left language like Arabic, the inline axis flips.

You can get more specific with padding-inline-start, padding-inline-end, padding-block-start, and padding-block-end to target individual sides. In this example, a left-to-right reader sees 2rem on the left and 6rem on the right; a right-to-left reader sees those values swapped, with the same top and bottom padding either way:

.selector {
  padding-block: 10%;
  padding-inline-start: 2rem;
  padding-inline-end: 6rem;
}

border-radius falls into this category, too. One value applying to all four corners is intuitive enough that shorthand may be fine:

.selector {
  border-radius: 8px;
}

And when we have a variety of values, it’s good to know what we intend with longhand syntax. Sometimes I’ll even write out a zero-ed out property (like border-bottom-right-radius) in this example to communicate exactly what’s needed for this element’s shape:

.selector {
  border-top-left-radius: 2rem;
  border-top-right-radius: 8rem;
  border-bottom-right-radius: 0;
  border-bottom-left-radius: 5px;
}

When each value is a distinct type

transition and animation are both shorthands that pack in a lot: duration, easing, delay, and the property being targeted. For simple cases, the shorthand may hold up when each value is a distinct type: a name, a duration, an easing function.

This example may be easier to parse without ambiguity:

.selector {
  animation: spin 1s ease-in-out;
}

But even when the types are distinct, ordering can become its own problem at scale. If one part of a codebase has:

.selector {
  animation: spin 1s ease-in-out;
}

And another one has:

.selector {
  animation: linear fade 2s;
}

Both are valid, but the inconsistency means you’re re-parsing the order every time you encounter the shorthand. Writing them out individually enforces a consistent structure by default. There’s no order to forget or vary.

When things get specific with different delays per property or timing, I’ll pull out the individual properties anyways. Ana’s post has a great example of this: if you have multiple properties transitioning at the same duration, writing the full shorthand for each one is just repeating yourself:

.selector {
  animation: 1s ease-in-out;
  animation-name: spin, fade;
}

animation in particular has enough sub-properties (animation-fill-mode, animation-iteration-count, animation-direction, and more) that the shorthand may get unwieldy fast. In practice, once I’m reaching for any of those, I just write them out all individually.

When the syntax has its own rules

Some shorthands have parsing rules specific enough that you may need to have the spec loaded to read them. These are the ones I almost always write out.

background is my go-to example. Unless you’re setting something dead simple like a solid color or a plain image, the full shorthand becomes a puzzle. This is still readable:

.selector {
  background: url("/images/my-image.jpg") no-repeat center / cover;
}

But once you’re reaching for position offsets, size, origin, and clip together, the shorthand stops carrying its weight:

.selector {
  background: url("/images/my-image.jpg") 1rem 1rem / 50% 75% no-repeat fixed content-box padding-box orange;
}

It fails here not because there are many values, but because the values are opaque without knowing the specific syntax. The / separates position from size, so 1rem 1rem / 50% 75% isn’t four coordinates, it’s two pairs with different meanings. The content-box padding-box pair sets origin and clip in that order, which isn’t something you can always intuit. And that’s a different problem from padding having too many values, because at least those follow a spatial logic.

.selector {
  background-attachment: fixed;
  background-clip: padding-box;
  background-color: orange;
  background-image: url("/images/my-image.jpg");
  background-origin: content-box;
  background-position: 1rem 1rem;
  background-repeat: no-repeat;
  background-size: 50% 75%;
}

border is also interesting because it’s a layered shorthand situation: border is a shorthand, and so is border-left. The catch is that border applies to all four sides. You have to go down to the directional properties or the individual sub-properties to set different sides. I usually write border shorthand when I want a consistent border all the way around, but I’ll break it out when I’m doing something more specific with colors or styles on individual sides.

You can also write the sub-properties directionally, which is a nice middle ground:

.selector {
  border-color: red blue green yellow;
  border-style: solid dashed;
  border-width: 10px 3px 50px;
}

grid falls into this category too. The shorthand syntax can be genuinely hard to parse at a glance:

.selector {
  grid: auto-flow dense 40px / repeat(3, 1fr);
}

This feels easier to read to me:

.selector {
  grid-auto-flow: dense;
  grid-auto-rows: 40px;
  grid-template-columns: repeat(3, 1fr);
}

I write grid and flex out fully, almost every time.

When you can’t retain it

Some shorthands just don’t stick, and that’s reason enough to write them out. This is also an honest admission that the thresholds I’m describing aren’t necessarily universal; they’re shaped by what I’ve internalized over time. These are conditions as I experience them and not objective rules.

I use the longhand syntax for text-decoration more often than not, even though the individual property names are fairly obvious. I just can’t seem to retain the shorthand structure.

I always have to think about this:

.selector {
  text-decoration: underline dotted red 2px;
}

And to me, this syntax reads like a list of decisions:

.selector {
  text-decoration-color: red;
  text-decoration-line: underline;
  text-decoration-style: dotted;
  text-decoration-thickness: 2px;
}

gap is another directional one: it only deals with row gap and column gap in CSS grid. I usually set the same value for both, so shorthand is fine. But when they’re different, I’ll often write row-gap and column-gap separately, mostly because I can never remember which order they go in. I’ve somehow committed padding and margin to memory but not this one.

font I have literally never written shorthand in my life. It just doesn’t feel natural, especially with font-family, which often has spaces and fallback stacks and needs its own line anyway.

font-variant is a fancy one I reach for when handling special typefaces, usually for turning on ligatures. I can never remember all the individual values, so I write them out. And since I’m typically only tweaking one or two things, it doesn’t add much overhead.

It’s not all or nothing

You don’t have to choose between going full shorthand or writing out every individual property (spoiler though: I often do make that choice). You can mix them by using the shorthand to set a baseline and then applying a specific longhand when you need precision for one value.

border is a solid example of this. Set the baseline with shorthand, then override what changes in a variant:

.button {
  border: 2px solid navy;
}

.button--destructive {
  border-color: red;
}

The goal is always clarity. Use the version that makes your intent most obvious.

Writing only what you mean

Despite what I’ve just written in the previous section, I don’t usually mix short and longhand and am most often choosing the latter.

Longhand can communicate scope, and is a key reason I often err on that side rather than brevity.

Even for something as simple as background color, I’d rather write:

.selector {
  background-color: green;
}

Instead of:

.selector {
  background: green;
}

The shorthand works, but leaves the door open. If I only mean to set a color, background-color says that plainly and there’s no slot for anything else other than that to accumulate.

The same logic applies when I want a handful of sub-properties. If I only want a selector to have a background image, color, and repeat value, I write exactly those three properties:

.selector {
  background-color: #b4da55;
  background-image: url(“images/my-image.jpg”);
  background-repeat: no-repeat;
}

A background shorthand would create a natural place for other sub-properties to creep in. Someone (including future me) might reasonably add background-size or background-position to that declaration later. And while those are fine additions, it signals intention to me when they’re written out as their sub-properties instead of values within the shorthand.

At the end of the day, shorthand properties are a tool, not a mandate. And if your answer differs from mine: yeah, well you know, that’s just like uh, your opinion, man.

Post by @pawelgrzybek@mastodon.social

View on Mastodon

Note that the example above has little circular dots, and what Paweł is asking about are little square dots. This is the example look from atproto.com:

Repeating a Small Area

My first thought is we’re obviously not drawing all these dots in one big graphic. We’re drawing one, leaving empty space, and using our ol’ pal background-repeat: repeat;

In order for the repeating to work, we need to define a smaller space via background-size. So let’s say it’s…

html {
  background-size: 100px 100px;
  background-repeat: repeat;
}

Now we’ve got a 100px square that will repeat over the entire background. We just need to fill that 100px square with a smaller square that repeats.

Drawing the Square Dot

Again my first thought was that we could make it look like we’re drawing a small square dot by actually letting a background-color show through and covering up everywhere else. So like a three-layer system:

html {
  background: 
    linear-gradient(to bottom, transparent 10px, white 10px),
    linear-gradient(to right, transparent 10px, white 10px),
    black;
}

If we flatten out that visual, you can see the three shapes smoosh down into a small square, which we then repeat.

That’s what’s going on here exactly:

Uh Oh — Transparency?

The problem with the above is that we need a solid color to be the “mask” that covers all the area except the mask. This means we can’t have, for example, one big image behind the dots or a gradient or anything (without more exotic trickery). The problem is we don’t have proper transparency.

What we want to be doing is drawing the dot with one “gradient”, if we can, and leaving the rest of the area empty/transparent.

Enter Conic Gradients

I didn’t think of this! Eric Meyer had the clever idea. The idea is that you can use conic-gradient to describe what we want in one go. “Hard stop” color stops are in use here, the classic trick to make a gradient just bands of solid color, not actually gradients. But in this case, three-quarters of the area is transparent, and the last bit is the dot color.

html {
  background-image: 
    conic-gradient(
      from 0deg at 5px 5px, 
      transparent 75%, black 75% 100%
    );
}

This took me a sec to understand, but it’s essentially setting the center of the conic gradient at a specific spot, then forcing most of the way around to be transparent and leaving the last bit as the dot.

Then we use the same concept as before where we set a smaller background-size and let it naturally repeat, and we’ve got square dots with a transparent background!

Scott Jehl, an engineer at Squarespace focusing on performance and accessibility, has been the driving force behind this. Scott and a small team of engineers proposed the spec change, wrote the implementation, and got it through the WHATWG HTML spec process with positive signals from all three major browser engines. If you want to understand the full story behind it, Scott talked about it in detail on ShopTalk Show and Squarespace published an excellent post on how to use the feature today. This is what working with the web platform looks like: identify a real problem, propose a solution, build consensus, ship it. A good story.

But that’s not the story of Chrome 148. The story of Chrome 148 is that Google – in the very same release – shipped the Prompt API, a feature that was met with explicit opposition from both Mozilla and WebKit, that the W3C TAG raised deep concerns about, and that the web community has been vocally and overwhelmingly against.

Mat Marquis wrote the definitive piece on this, and I won’t retell it here because he puts it in much better words than I ever could. Go read his post. But to understand the scope of the problem: the Prompt API, as shipped, is not a standardized interface for interacting with language models in general. It’s an API for interacting with Google’s Gemini Nano – a 4 GB model that Chrome has already silently downloaded to your machine, without asking, and that it will re-download if you remove it. Any website you visit can now send prompts to that model, using your processing resources, without requesting permission. When both other browser engines explicitly oppose a feature, calling it a “web standard” is a bit of a stretch. I’m not involved in any of this. But after working on the Web for over 25 years, I know how web standards work. This is not one. This is a Chrome feature wearing the costume of a web standard.

And that’s not all. To use the API as a developer, you must agree to Google’s Generative AI Prohibited Uses Policy – a corporate policy attached to what is supposed to be a web platform API. Jake Archibald, who is now at Mozilla, called this out explicitly (and got over 800 likes for it btw): elements of this policy go beyond law, and it sets a dangerous precedent for APIs that come with vendor-specific terms of use. As Mat writes, imagine the Geolocation API requiring you to agree to Google Maps’ Terms and Conditions. Think about what this means if we accept it: the next browser API could come with its own corporate terms, too. And the one after that. The web platform has always been open, implementable by anyone, and governed by specs – not by a single company’s usage policy. This is a line that, once crossed, is very hard to uncross.

There’s also the question of what the browser is even for. A browser is a user agent – it’s supposed to act on behalf of the user, not the vendor. Silently downloading 4 GB of AI model to your machine, re-downloading it if you remove it, and then letting any website access it without your permission – that’s Chrome acting as Google’s agent, not yours. And it’s hard not to notice how many Google products stand to benefit from having an LLM pre-installed on every Chrome user’s machine. With opt-out, of course.

And how did Google justify shipping it over the opposition of the other browser makers? By listing developer sentiment as “strongly positive” in their Intent to Ship. But the evidence behind that claim doesn’t really hold up. The blink-dev thread where the feature was approved consisted entirely of browser engine insiders – Chrome engineers and one Microsoft Edge representative. No external developers participated. A GitHub issue Google created specifically to capture developer interest in the API received exactly two responses in seven months. Satisfaction scores came from a survey Google administered to its own Origin Trial participants — self-selected early adopters who had actively signed up to test experimental Chrome APIs — with no sample sizes disclosed. The stakeholder feedback page cited one promotional blog post, one post on Twitter, and a now-broken link. This seems to be the foundation on which “strongly positive” was built.

Jeremy Keith has documented this pattern over the years: Google’s habit of shipping first and standardizing later, or not at all. AMP. FLoC. Privacy Sandbox. Chrome ploughing ahead and unilaterally implementing whatever it wants, even if there’s no consensus from other browser makers. The Prompt API isn’t an exception. It fits the pattern.

What makes this particular instance so frustrating is that the contrast is right there in front of us, in the same set of release notes. There’s lazy loading for audio and video: carefully proposed, properly standardized, welcomed by all implementers. A true gift to the web community. And then, there’s the Prompt API: rammed through despite broad opposition. One feature shows how the standards process can and should work. The other shows what happens when a company with dominant browser market share decides that the process doesn’t apply to them. The fact that my posts on Bluesky and Mastodon sharing Mat’s article are (still) getting hundreds of reactions while Google's own call for developer interest in the Prompt API received two responses in seven months tells you everything you need to know.

Chrome 148 could have been a celebration. It should have been about lazy loading. About the power of the web standards process. Instead, Google made sure that all anyone’s talking about is how they’ve once again shoved something down our throats that nobody asked for.

Pie charts, line graphs, bar and column charts (let’s just call them all ‘charts’ for ease) are really useful, visual ways to present data, and we’d include one on a webpage using an image, like a PNG or SVG.

Accessible PNGs

I say ‘PNGs’, but these could be any other image format, like WebP, AVIF, or even JPG. The mechanism we’d use to embed them on our page would be the <img /> element:

<img src="my-great-chart.png" alt="A description of the information the chart conveys" />

Depending on the complexity of the chart, our alt text could be doing a lot of work here. In principle, that’s fine, as the alt attribute can contain as many characters as you need, but the problem is that there’s no way of introducing any meaning to the content in alt text; it’s just a wall of unstructured text.

Here’s an example with some made-up figures about people’s favourite characters from the original Star Wars trilogy:

<img src="star-wars-favourites.png" alt="Pie chart showing that 22% chose Han Solo, 18% chose Darth Vader, 15% chose Princess Leia, 12% chose Chewbacca, 9% chose Luke Skywalker, 7% chose Yoda, 6% chose Obi-Wan Kenobi, 4% chose Lando Calrissian, 3% chose R2-D2, 2% chose C-3PO, and 2% chose other characters." />

That’s a fairly typical amount of information for a chart, and it takes a fair amount of concentration to make sense of, especially with so much repetitive language. Imagine more complex charts, like a stacked column chart or a best-fit line chart.

Before you mention longdesc…

I know what you’re thinking: there’s the longdesc attribute, which allows us to reference a structured HTML document:

<img src="star-wars-favourites.png" longdesc="star-wars-favourites-description.html" />

Although browser support still appears to be there, longdesc is long deprecated so definitely not recommended.

Accessible SVGs

So if alt text isn’t ideal, and longdesc is out, maybe a more complex image format like SVG is the answer?

We could reference an SVG file just as we did with the PNG in our last example, but for inline SVGs the result is exactly the same; a big lump of unstructured descriptive text:

<svg role="img" aria-labelledby="title description" xmlns="http://www.w3.org/2000/svg">
    <title id="title">Pie chart showing people's favourite characters from the original Star Wars trilogy</title>
    <desc id="description">22% chose Han Solo, 18% chose Darth Vader, 15% chose Princess Leia, 12% chose Chewbacca, 9% chose Luke Skywalker, 7% chose Yoda, 6% chose Obi-Wan Kenobi, 4% chose Lando Calrissian, 3% chose R2-D2, 2% chose C-3PO, and 2% chose other characters.</desc>
    <!-- SVG coordinates -->
</svg>

ARIA in SVG

But we’ve been ignoring SVG’s superpowers! SVG is markup, so ARIA can be used to add semantics to the elements that make it up.

In Accessible SVG line graphs, Léonie Watson goes into detail about how we can make purposeful use of SVG’s group (<g>) element and various ARIA role attributes to give the chart table semantics. A chart is a visual representation of tabular data, after all!

For our Star Wars pie chart, we could use:

• role="table" for the containing group
• role="row" for each character
• role="columnheader" to label each column of information (character name, and percentage of votes)
• role="rowheader" for each character name
• role="cell" for each percentage value

Visually a chart; semantically a table.

One thing visually, another non-visually

I love the ARIA in SVG approach, but it’s fiddly enough to make me wonder if there’s a simpler approach. We could separate the two things:

• An SVG chart that’s hidden from assistive technologies with role="presentation" or aria-hidden="true"
• An HTML table that’s hidden visually with CSS, but still available to screen reader users

This way, sighted users would see the chart and screen reader users would get the data in an HTML table. That would work, but it still assumes the table is only useful to screen reader users.

Just show the underlying data

Maybe we should stop treating the table as an accessibility-only fallback? I reckon it could be even better to present both the visualisation and the underlying data. After all, some people might prefer rows and columns to a chart.

The way I’d probably approach this is to ensure the chart doesn’t get picked up by assistive technology like screen reader software at all, as we did before:

<svg role="presentation" xmlns="http://www.w3.org/2000/svg">
    <!-- SVG contents -->
</svg>

And then our table:

<table>
    <caption>Favourite characters from the original Star Wars trilogy</caption>
    <tr>
        <th>Character</th>
        <th>Percentage of votes</th>
    </tr>
    <tr>
        <td>Han Solo</td>
        <td>22%</td>
    </tr>
    <tr>
        <td>Darth Vader</td>
        <td>18%</td>
    </tr>
    <!-- The rest of the characters -->
</table>

If your table has a lot of data, you could save some unnecessary scrolling for users who prefer the chart by wrapping it in a <details>/<summary> element.

Note: it’s totally valid to expose the chart to screen reader users if the visual presentation is relevant; just make sure the alternative text describes the visual presentation, not the data that’s already available in the table.

So what to do?

For screen reader users, a simple chart with the data in the alt text might be okay, but more often than not we probably want to present the data in tabular format, which is easier to navigate, compare, and understand. Going one step further by accompanying the chart with a table is an even more robust approach as it also allows sighted users to choose how best to absorb the information.

So do charts and graphs need to be accessible? Yes and no. The chart image itself doesn’t always need to be exposed to assistive technologies, but the information it communicates must be accessible.

The article Do graphs and charts need to be accessible? appeared first on www.tempertemper.net.

Despite the personal horror of realising that book is old enough to buy alcohol in the USA, it’s fun to look at as a snapshot of a certain point in the history of the web. In 2004 many sites were still laid out with tables, several of the examples explain how to do a certain layout “without tables”. It’s also notable how I refer throughout to specific browser versions, because in 2004 a browser version would last for at least a year and usually much longer. Chrome is about to begin a two-week release cycle, we’ve come a long way.

It’s also interesting how long we had to wait for interoperable, robust ways to achieve some of the solutions. On page 328 I explain how to create coloured scrollbars, using the scrollbar-* that only worked in Internet Explorer. Over 20 years later the scrollbar-color property became Baseline Newly available.

I ultimately published four editions of The CSS Anthology. People still tell me how they learned CSS from that book, something which I find amazing and wonderful. I often wonder what a modern version of that book would look like, and how big it would need to be to attempt to cover all of CSS in 2026!

I started using ChatGPT and DeepSeek to help me fix bugs and debug error messages, especially when I was new to working with Eleventy. I asked them questions, pasted in code, and then copied the result back into my project. Now, I use Codex to clone my boilerplate files and set up new projects. But whenever I started something new, I had to tell the machine my preferences again.

Machines don’t write code the way I do, so I constantly needed to reorder CSS selectors. Machines use too many class attributes and overly specific selectors, and don’t format CSS and HTML the way I like. When I switched to Codex, I realised there was a way to stop repeating myself by telling it ways to make the machine’s code more like mine.

The AGENTS.md file

Codex supports files called AGENTS.md, which is to a machine what a README is to fleshy ones. It can tell an agent what I care about and how I write code. It also defines a set of rules which prevent me from repeating myself at the start of every project.

You can add an AGENTS.md file to any project repo or put one into Codex’s hidden global config folder, which is in the root of your user directory (on a Mac.) Putting preferences there means that every new project starts using them.

~/.codex/AGENTS.md

I included a list of five things I was constantly correcting and needed the machine to stop doing. Here’s my global file:

# AGENTS.md## Core rules

- Prefer plain CSS and vanilla JavaScript.
- Prefer inline SVG when control, styling, or reuse matter.
- Use native platform features. Avoid dependencies and libraries.
- Use semantic HTML.

## CSS rules
- Don’t indent CSS declarations.
- Don’t use the `transform` shorthand property. 
- Keep the closing curly brace on the same line as the last property.
- Order all CSS properties alphabetically.
- Prefer shallow selectors and avoid deep selector chains.
- Use individual transform properties (`rotate`, `scale`, `translate`).

## Motion
- Always respect `prefers-reduced-motion`.
- Motion should be subtle, purposeful, and non-disruptive.
- Use CSS for animation and JavaScript for triggers.

## Writing
- Use British English.
- Use sentence case for headings, interface copy, and labels.

Quickly running through that list:

1. By telling Codex I prefer native platform features, I get solutions that rely more on CSS, which is faster and much easier for me to work with.

2. Machines will also happily wrap everything in <div> elements unless I tell it otherwise. I want meaningful structure, so I ask it to prioritise semantic elements like <article>, <header>, <footer>, and <section>. I also work mostly with inline SVG because I need control over animation and styling, so I make that explicit too.

3. I’m especially picky about how I write CSS. Nothing AI did was technically incorrect; it just wasn’t my way of doing things. My AGENTS file tells the machine to write properties in alphabetical order, so I can scan them more quickly. I also want consistent formatting and simple selectors, so code stays easy to read.

4. When I animate, I’m often aiming for ambient motion to add atmosphere. I also need animations that respect someone’s motion preferences, not as an afterthought.

5. Finally, when adding UI copy such as button text and form labels, I want British English spelling in sentence case.

AGENTS.md as a project brief

A global AGENTS file gets used by every project, but putting one in a project repo makes it act more like a brief. Here’s the boilerplate file I use with Eleventy projects:

# AGENTS.md## Overview
- This is an Eleventy project.
- Follow existing patterns in templates, styles, and naming.
- Make the smallest change that solves the problem cleanly.
- Don’t write new code unless absolutely necessary.

## Structure
- `src/` contains all source files.
- `src/_includes/` contains layouts and partials.
- `src/css/` contains global and component styles.
- `src/js/` contains small progressive-enhancement scripts.

## Working approach
- Don’t refactor unrelated code.
- Reuse existing patterns before creating new ones.

## HTML
- Don’t add unnecessary wrapper elements.
- Reuse existing partials where possible.
- Use semantic HTML elements.

## CSS
- Extend existing styles before creating new ones.
- Follow the global AGENTS.md for formatting and style rules.
- Keep selectors shallow and readable.
- Place media queries at the end of stylesheets.
- Use `.alt-*` for variations and `.item-*` for content types when needed.

## JavaScript
- Always use progressive enhancement.
- Don’t use JavaScript if HTML and CSS can solve the problem.
- Keep scripts small and vanilla.
- Scope behaviour to the relevant component or page.

## Eleventy
- Don’t duplicate already defined logic.
- Reuse existing collections, data files, and filters.
- Check if the content fits an existing collection before creating a new one.

## Verification
- Run the local build before finishing.

Wrapping up

I started using AI coding tools to free up time by avoiding repetitive tasks. AGENTS files define the rules the machine should follow, so I don’t have to also spend time editing its code to suit my style.

• Global AGENTS.md
• AGENTS.md project brief

There’s no doubt about how impressive this demo is. The speed in which the text moves out of the way of the dragon is pretty incredible. As expected, many people are saying this is the end of CSS. So, let’s talk about it and address the demos provided that showcase some of the features in the lens of user experience.

Accordion

The first demo is of an accordion showcasing how the sections open and close smoothly without CSS hacks or measuring the DOM. This has been true for many years, we’ve wanted to animate from an intrinsic height for a long time. Well, we can do that now with pure CSS, in a few different ways.

The first way was maybe a hack, which was to animate the grid row. This was discovered 5 years ago. The difficulty with this approach is that it doesn’t work well with the native <details> element.

The second way is to use interpolate-size: allow-keywords. This allows you to animate between a <length-percentage> value and an intrinsic size, fit-content, or max-content. This allows you to animate between 0 and auto for the height.

And finally, we have calc-size() which is a function I recently used on the new Mise en Mode website to get the auto size as a number that can be used in other functions, such as round(). This also calculates the intrinsic size of the content, so it can be used to animate from 0 to auto as well.

As you might see when reviewing the MDN pages of these new CSS features, they don’t all have baseline availability yet. But do you really need JavaScript in order to animate the accordion? I’d argue you don’t, if you’re willing to put in a little extra effort learning what CSS has, and not ship some extra JavaScript for the sake of this.

Bubbles

This is an interesting one. This is showcasing something called the “shrinkwrap” problem that is now more common than ever in a world of web chats. The problem is that CSS text wrapping isn’t efficient. The bubble that it leaves will have extra space not taken by text. What would be preferred is for the bubble to only be as big as the text needs to be. So without the shrinkwrap, each bubble is the same width. Meanwhile, with shrinkwrap, the bubbles match the size of the text leaving no extra space.

There is a CSS solution found by Roman Komarov to help with this problem which uses the new anchor positioning features. It also uses some pseudo element tricks to get the effect to behave. This is a pretty clever solution, but it is also pretty complex. It also doesn’t work in all browsers yet.

The question is, do you want to bring in a JavaScript library just to get your text bubbles to shrinkwrap? Is this going to improve the user experience or is it an attention to detail that is not worth the cost of the extra JavaScript? I would argue the latter. The shrinkwrap problem is a problem, but it’s not a problem that is worth the cost of bringing in a JavaScript library to solve it. It’s a nice to have, but it’s not a must have.

Dynamic Layout

This looks like a magazine or editorial layout which has some images that are effecting the placement of the text. When I first saw this, I immediately thought of the shape-outside property which allows you to wrap text around a shape. Honestly, I haven’t used this CSS property much but I do know it takes some setup in order for it to work. You’d need to have an alpha of the shape so that text can wrap around it. The object needs to be set as a float in order for the wrapping to occur. Placing that element could be a pain, requiring additional margins to be added, most likely with shape-margin.

What CSS won’t accomplish is the rotation of the images. For example, setting rotate: 45deg on the image doesn’t affect the text wrapping around it. In the pretext demo, rotating does affect the text. Ultimately, I imagine you could maybe animate a very complex polygon of points to follow on an interaction. But the reality here is that if you want this effect, JavaScript is the way to go.

But do you want this effect?

Even without the animation, when text doesn’t consistently start at the same place, it can become tiring to read. This is why we don’t typically center body text. Our eye wants to align to the left (or right in RTL languages) and when it can’t, it can be a bit of a strain. The additional rotation that can occur would make catching the word you were trying to read difficult since all the lines are recalculating their position on every frame. This is a fun effect, but it’s not something that I would add to an article because it’ll distract from the content and make it harder to read.

Variable Typographic ASCII

As you might imagine, this isn’t meant for you to read the text. This is instead a artistic effect that uses glyphs to create a visual piece of art. Since there isn’t anything here that is specifically UX related, I’ll refrain from commenting on it, past hoping that someone puts an aria-hidden="true" on it so that screen readers don’t try to read that unintelligible mess.

Editorial Engine

Similar to the dynamic layout, this is a layout that has some images that are effecting the placement of the text. The difficulty in reading the text is much more apparent here because the balls are constantly moving around making the location of every word change on every frame. As said earlier, not something I’d use for something I’d want someone to read.

Justification Comparison

I have to admit this has some practical use. The justification algorithm in CSS leaves a lot to be desired. It doesn’t do a good job of balancing the space between words and letters, which leads to large gaps appearing within the text called rivers. The pretext demos show a better way of balancing the text such that the rivers are reduced, even having tighter algorithms available.

Though, one thing you’ll need to be careful of is the introduction of hyphenation. CSS has a hyphens property that allows you to loosely control when words are hyphenated. If you have a better justification algorithm, you might find that you need to hyphenate more often in order to get the best results. This is something to keep in mind when considering this approach as I did when typesetting the book Mise en Mode and ultimately decided to avoid justifying the text because of the potential for rivers and the need for hyphenation. I wanted to avoid both of those things in order to provide the best reading experience possible. I kept the content as the primary focus in a way that was familiar without stressing over the details of justification. Curating every small hyphen is very tedious. I personally rather keep the words intact and not have full justification.

Rich Text

Again, I think this does have some practical use. I’ve recently written about the difficulty in wrapping inline code accurately in CSS. In this demo, the inline code does wrap in a reasonable way but I’ll also say there’s configurations that make the wrapping a bit too eager.

It might make some sense to add some <wbr> spaces into the code at the right places. This could be done in a preprocessing step instead of on the client where the pretext project needs to run.

Masonry

Ah yes, the layout everyone is waiting for. While display: grid-lanes isn’t the property value we might have been expecting, the industry has been asking for a masonry layout for a long time. The pretext demo shows how to achieve this layout with JavaScript.

While we’ve known that we’ve needed JavaScript to have dynamic masonry layouts for a long time, there’s something you need to consider when implementing them; reading order.

When you look at a masonry layout, what is the order of the boxes meant to be read in? Is it top to bottom, left to right? Or is it left to right, top to bottom? Maybe it changes due to one box being longer than another. If you inspect the demo you’ll see that some of the items are inserted in places that aren’t in any clear order. It is most likely using a dense packing algorithm to efficiently use the available space, but this isn’t necessarily how the items are meant to be consumed.

The new reading-flow property in CSS is meant to help suggest how these items are meant to be read. I’ll say with the amount of consideration the CSSWG has put into display: grid-lanes, I’d trust that they’ve thought more about how masonry layouts should be managed more than “whatever fits best”.

What is pretext for?

It’s for people who want more control over how text flows; either for artistic purposes or for typesetting designers who crave the tools traditional print design has had for a long time. Just remember the web is not print. Text has never animated on a magazine page, nor has that magazine page needed to download additional code in order for the layout to behave. These are different mediums even if we’ve made analogs to them over the years.

I’m certainly not saying to avoid using the library, I think it’s fun and does have some practical use cases. But you should first consider your users and whether the features of this library are worth the cost of the extra JavaScript and the potential decrease in user experience. If you do decide to use it, make sure to use it in a way that enhances the content and doesn’t distract from it.

This certainly isn’t the end of CSS, it’s showing what’s next.

What this means is you need to fundamentally shift how you think about WordPress.

From the beginning, WordPress has always been open source, giving you freedom, liberty, autonomy, and digital sovereignty. Open source is the most powerful idea of our generation.

For the past few decades, WordPress was software you got from a cloud provider or web host, such as WordPress.com, Bluehost, Hostinger, or Pressable (the currently recommended WordPress hosts). You could self-host it on a Raspberry Pi or home server, but few people did.

The experience of downloading WordPress, as my Mom did, is that it unzips a bunch of PHP and various code files onto your desktop. Very confusing!

But now, thanks to incredible advances in WebAssembly (WASM), we can spin up a web server, a database (SQLite or MariaDB), and a full WordPress installation inside your browser in about 30 seconds. Instantly. No server needed. I introduced Playground at State of the Word in 2022.

You can even use it to cross-publish apps to the web, desktop, and iOS, like Blocknotes did in 2023. You can get the latest Blocknotes at Blocknotes.org. One codebase, multiple platforms.

These WordPress Playground containers are fully composable and atomic. You can track and roll back any change. Undo for everything. Stop thinking of WordPress as just on a web host and worrying about maintenance and management, and more as a self-contained unit of open source goodness, a fun little package where you own and control the code and data and can run it however you like.

How perfect is that for AI to work with? Playground makes WordPress local, fast, and trivial to spin up multiple instances, test code changes, and save them.

Next up, we’re going to add peer-to-peer sync, version control integration, and cloud publishing so other people can access it.

I believe this will take us from millions of WordPresses in the world to billions. Hosting isn’t going away; in fact, I think demand for cloud syncing will increase drastically as we radically open up what people can build on top of WordPress.

In an AI age where it’s trivial to spin up software from scratch, consumers will have to give much more thought to brands they trust to be in it for the long term. We’ve been relentlessly iterating on WordPress since 2003. I plan to work on it the rest of my life, and there’s a broad community of hundreds of thousands, if not millions, of people who make their living on top of WordPress.

On WordPress.com we offer 100-year plans and 100-year domains, and I believe we’re one of the few companies where that’s credible. It’s led by Zander Rose, who ran the Long Now Foundation (one of my favorite non-profits) from 1997 to 2023, a quarter century.

In core WordPress, we are obsessed with backwards compatibility. You can run plugins and themes written 20 years ago on today’s WordPress. I’ve stumbled on decade-old installs, and the built-in auto-upgrade took everything to the newest version.

At Automattic, for better and worse, unlike Google, we almost never shut things down. We obsess about maintaining or redirecting permalinks. We make it easy not just to get your data in, but take it out too. We build businesses that lower churn not by locking you in (Wix famously has no export) but by making it easy for you to leave. If you love somebody, set them free.

In the next few years, there will be a Cambrian explosion of software and services. You’re going to have a lot of choices about where to put your most precious data and software. You should demand open source and bet on those who are clearly in it for the long-term.

Today, everyone gets a phone number and email when they grow up. That will expand in the future, everyone will have a domain and a WordPress. A part of the internet that you own.

Technology is best when it brings people together. Technology is best when it puts you in control, gives you ownership, digital autonomy, freedom, and liberty. That’s open source. It’s so exciting to see how AI is supercharging open source.

Join the WordPress community. It’s fun! We have cookies that don’t track you.

First impression

When I first read about the geolocation element, my initial reaction was surprise. I was surprised to find a dedicated element for obtaining the user's location. I thought that could've also been a relatively simple web component instead.
On the Chrome for Developers blog, the authors explain that there are three main reasons for the existence of the element.

• Clear intent and timing - By clicking a button, users show clear intent. That's in contrast to how it works on many websites, where, out of nowhere, they will automatically ask you to share your location. Users often dismiss or decline these requests, which can be problematic because it's not easy to change that decision later.
• Simplified recovery - If a user or browser has previously blocked access to a location, the element enables them to change their settings.
• Automatic refresh - If a permission has already been granted, users can click the button to update it.

I wasn't 100% convinced, but the recovery and refresh features sold it to me. Still, I didn't think I would use this element much because I don't need to know the user's location very often. That's, of course, my problem.

When I learned everything I wanted to know, I wrote a simple introductory post about the element on my website. Five weeks later, I'm writing another post because I've learned some more surprising and strange things.

Styling constraints

You can style the geolocation element, but there are styling constraints to ensure user trust and prevent deceptive design patterns. I understand why these restrictions exist, but what confuses me is how they're implemented. They come in three flavours.

• Enforced user agent styles
• Enforced user agent bounds
• Element deactivation

Enforced user agent styles

There are certain rules you can't overwrite because they are marked as !important in the user agent style sheet. For example, you can't change the box-sizing property.

permission, geolocation, install, usermedia {
  background-color:#efefef;
  border: solid 1px #767676;
  box-sizing: content-box !important;
  …
  word-spacing: normal;
  vertical-align: middle !important;
 }

That's not new. We already know this from other elements, like some form elements.

Enforced user agent bounds

Other rules are not important, but they have style bounds. For example, you can define a border-width, but the value must be between 0 and 0.6em.

Basically, anything that makes your button not look like a button is either prohibited or restricted. I understand that, and you also have enough properties at your disposal to change the design of your button to match your theme, but where it gets really strange is the third measure.

Element deactivation

I can live with enforced user agent styles and bounds, but if you define certain rules or do certain things, the element will be deactivated, and it won't work anymore.

The element just stops working without letting the user know when:

• The contrast ratio is below 3:1
• The font size is smaller than the computed value of small or larger than the computed value of xxx-large. By default, with a base font size of 16px, that's 12px and 48px.
• If more than 5px of the element is not inside the viewport. For example, if you move the element using a negative margin or transform, or if you only scroll the page a bit too much out of the viewport. (The 5px is based on my tests; it could also be a relative value I'm not aware of)
• If more than 5px of the element is covered by another element, e.g., a sticky header.

Coming back to the intro of the post. If the font size of the geolocation is set to 2rem in the author style sheet and the user sets their browser's default font size to 25px, they won't be able to use the element just because they need a larger font size. The worst thing about this is that there is no visual feedback and no console error. You'll find an error message inside the Issues panel, but how many of you actually use the Issues panel, and how many of your users do?

I just can't understand how anyone could think that this was a good idea.

That's by far the worst thing of all the things I find strange about the element, but there's more.

JavaScript dependency

There aren't many HTML elements that fully rely on JavaScript to do anything meaningful (e.g., canvas). Geolocation is one of them. If I want to use the user's location, I have to attach an EventListener in JavaScript. I can't just process the data inside a form and pass it to a script via GET or POST. That's very unfortunate because if there's one thing I love about all these new features in HTML that replace custom JavaScript solutions (e.g., dialog with invoker commands, popover, details), it's that I don't need JavaScript at all.

PS: JavaScript dependency in HTML is actually an interesting topic. I'm working on a blog post about it.

Content restrictions

The element comes with an icon and a text label. You can hide the icon and select a locale for the text via the lang attribute, but that's it. You cannot change the text because the browser determines it. It's also not possible to show only an icon, as many websites do in their custom solutions.

geolocation::permission-icon {
  display: none;
}

<geolocation lang="de">
  <strong>Ihr Browser unterstützt das &lt;geolocation&gt; Element nicht.</strong>
</geolocation>

Dark Mode

At this point I'm unsure if this is a feature or just a bug, but the geolocation element doesn't support a dark color scheme.

<div style="color-scheme:dark">
  <geolocation></geolocation>
  <button>I'm a regular button</button>
</div>

Conclusion

Don't get me wrong, the element does the thing it's supposed to do well, but I can imagine that the styling and content restrictions will be a blocker for many people. Even if they can accept the limitations, they may not want to accept the possible issues that come with this horrible element deactivation feature. The least browsers should do is tell and show users that the button is deactivated and why. What I would find even better is to just define bounds for the font size instead of deactivating the element. For contrast, they could use the closest-matching combination for the text and background colors that has a ratio of at least 3:1.

I don't enjoy writing blog posts like this, but the element is in its current state not very useful. I've read the explainer and discussions on GitHub, I know that a lot of thoughts and work went into this, but the implementation feels a bit rushed.

Additional resources

• geolocation doesn't respect dark mode/color scheme
• Deactivation of the geolocation element is unpredictable and confusing
• geolocation style constraints interfere with accessibility

My blog doesn't support comments yet, but you can reply via blog@matuzo.at.

As I read Geoff’s article, it gave me a moment to pause. I am still here. I am still a front-end developer (even though my title is UX Developer). I am still here. And I don’t say that like a grump older person who has been in the role for a long time with a sense that I am stuck or that I am not thrilled about it.

No, when I say “I am still here” it is very much an enthusiastic and very grateful tone. I feel incredibly blessed that “I am still here.” Why?

Two years ago, I lost my job unexpected. And I spent the next twelve months looking for a new job. There were a lot of days during that unemployment that I thought my time building and crafting websites were over. There were days that I had to fight hard against discouragement to keep going. It took me quite a while just to start getting some interviews. And then I would get my hopes up only to be disappointed. Even a year ago today, I had some possibilities but still had this fear that my time in the Web industry might be over. Fighting for hope was a daily battle.

I had no idea what I would do instead. I had invested twenty five years in this field. And I still enjoyed working on every project that came my way. I love crafting with code. And that was the hardest part of being unemployed. I was not motivated to do side projects because in a lot of ways, it was too painful. I missed the energy that doing creative work each day had given to me while I was employed.

I entertained the idea of pivoting to something else or trying to retool. I bought Josh Comeau‘s Joy of React course and started learning React. But I didn’t necessarily see a way forward in that lane as all the job postings that I saw were looking for someone with years of experience. And I struggled to think about being a React developer because of some fundamental philosophical/professional disagreements with frameworks as an approach to building the web. It seemed to go against the grain of the Web not using the most up-to-date HMTL elements like dialog. I also had accessibility and progressive enhancement concerns.

But I am still here. The timing of things came together and Revive Our Hearts ministry needed someone with my skills. It was the right fit at the right time. It brought me back full circle. I got my start in web development while working for Campus Crusade for Christ (now Cru). Once again, I was going to be able to invest my skills in something I was very passionate about.

There have been so many days, especially over the last six months, that I am just so grateful and appreciative of the fact that I still am here–that I still get to do the thing that I love doing and have built up so many skills and knowledge about. I am humbled when I see how many people are losing their jobs in the industry and still looking for new opportunities. I don’t take it for granted that I still get to do what I do. It is a privilege and a blessing.

I don’t know how much longer it will last but I want to enjoy every minute of it. I thought about several scenes from the movie, Toy Story 2. Woody, a vintage toy cowboy, considers going to a museum as he begins to feel that his days as Andy’s beloved toy are numbered. But then later in the movie he comes to his senses.

“I can’t prevent Andy from growing up but I wouldn’t miss it for the world.”

After Buzz Lightyear, Woody’s space toy friend, asks Woody if he was still worried about Andy growing up. “Nah, it will be fun while it lasts.”

I don’t know what is ahead for our industry. I know there is a lot of concern about how AI will change our jobs or whether there will be less jobs in the future because of AI. I still have my doubts about the “inevitability” of AI. But I am still not sure how to hedge my bets.

But for now, “I am still here.” And I am grateful and trying to enjoy it as long as it lasts. And trusting God with what is next if it comes to that.

• Day 366 – I accepted my current role almost a year ago on Day 366 of my unemployment
• Lessons from a yearlong job search
• Two powerful investments to make in your career
• Get to know me: Revive Our Hearts Edition – I put this together so that my new teammates could get to know me a bit better. I share a bit more about my journey into this new role.
• Six months – Reflections about my first six months in my role with Revive Our Hearts
• 2025 by the numbers – My year-end review
• A Decade of Development: 2010 to 2019
• The making of a webcraftsman, part 1 – I need to write more chapters in this series. This covers 1999–2003.

The post Still here appeared first on Jeff Bridgforth.

However, the bulk of frontend code on the web is inaccessible to some degree. Also know here that LLMs are trained on the majority of the world’s frontend code. Similarly, many contemporary LLM-friendly UI libraries claim to be accessible, but may have varying degrees of support when manually evaluated.

The deck is a bit stacked, folks.

Given that, you need to get creative about how to handle the LLM’s training. It might seem like a good idea to instruct an LLM—reference, skill, agent, sub-agent, what have you—to reference the ARIA Authoring Practices Guide (APG), because it lists a lot of common UI patterns, right?

Well, sorta.

The reality of things

The APG was created to demonstrate ARIA’s capabilities. Because of this, it disproportionately favors ARIA in its code examples. This is even in spite of ARIA’s first rule.

The APG was also not created to serve as a pattern library, design system, or single source of truth for the “right way” to make something. Unfortunately, a lot of people treat it this way.

Furthermore, the code examples themselves on the APG have an—ahem—range of effectiveness. Some code examples are fine. Some of them kind of work in an awkward and confusing way. Some of them don’t work at all.

Recall here that the original reason for APG code is to be a showpiece for how ARIA could hypothetically be used. Because of this, it is not the APG’s concern that ARIA does not have perfect support.

Also recall that LLMs love ingesting and utilizing structured content. And it’s an understatement to say that code is structured content.

While we’re on the topic of code: The APG’s examples are written in a way that may be incompatible with your organization’s way of doing things. Think frameworks, naming conventions, linting rules, and other areas of friction.

The friction caused by this incompatibility may disrupt the LLM’s context window in some way. This is not a good thing.

Instrumentality

If you instruct a LLM to retrieve all of the content of the APG, this bias will be encoded and perpetuated at the scale of the number of people who use it.

You should also consider the second-stage effects of other LLMs referencing the code your LLM generates. Meanwhile, I will be considering quitting tech to start a combination punk rock venue/mushroom farm.

APG: The good parts

From the perspective of both a LLM and a human, the good parts of the APG are:

• The pattern names. Having a standardized way to refer to a discrete piece of UI that is larger than any one company is highly beneficial.
• The content contained in the “About This Pattern” section. This is what the discrete piece of UI does, and how it goes about doing it.
• The content contained in the “Keyboard Interaction” section. This is how people who use assistive technology will expect things to work.

Everything else is suspect.

But what about the “WAI-ARIA Roles, States, and Properties” section?

LLMs are not good at nuance.

The WAI-ARIA Roles, States, and Properties section of each APG pattern should be treated as human-facing informative content. This is to better avoid a situation where a LLM will “read” that something should have a role, then try to literally apply a role attribute.

You want to encourage use of the role implicitly conferred by a native, semantic HTML element. Using the button element for buttons, the anchor element for links—you know, that sad old sorry story.

You will also probably need instructions on how to cajole the LLM to barf out the semantic HTML that the majority of the industry has largely been allergic to using for decades. Organization-specific content is likely key for this effort—especially if tethered to, and reinforced by a design system.

Shut up and give me the code, nerd

Here’s what I’ve found to be helpful:

## [ARIA Authoring Practices Guide (APG) patterns](https://www.w3.org/WAI/ARIA/apg/patterns/)
Partially trusted source. Use selectively.

**CAN reference:**
- Content in "About This Interaction" sections
- Content in "Keyboard Interaction" sections

**CANNOT reference:**
- Code examples from APG
- CodePen links (URLs starting with `https://codepen.io/`)

This might change over time, but right now it seems to help to push a LLM towards only slurping up the salient bits.

There is a world of difference between a disclosure and a tree view

The more complicated a component is, the higher the chance it will need tweaks to its underlying structure to interface with assistive technology as expected.

Content like disclosures are both simple and well-established. This means they have good support. As a spicy twist here, the APG’s recommendation of aria-controls fails to mention that JAWS is the only screen reader to support the declaration, thus reinforcing the larger point of this post.

Content like tree views are far more complex. They need intervention to work as expected across a spread of popular assistive technologies.

This range of differences is even more true as these entities are brought out of the realm of the platonic and are integrated into the real-world ecosystems that are your websites and web apps—with all their constituent functionality and content needs.

This kind of insinuates that you’re indirectly advocating for the removal of code examples from the APG

I know that effort and care went into the creation of the APG’s code examples. I also am acutely aware of how draining it can be to manage a large and popular open source project, especially one that does not pay.

However, I also get the sense that the APG’s code examples are not actively maintained. I think the code examples’ inclusion are poised to cause more harm than good. This is born of considering network effects combined with an LLM-first approach seeming to be how the industry is settling on building things.

I’m not working on a LLM, but our organization is

It might be worth asking how your organization’s LLM(s) are approaching producing accessible frontend code. If referencing the APG, it also might be worth investigating how the LLM has specifically been instructed about going about it.

I am willing to bet said instructions are nothing more than a URL included in a list of other related resources. This is likely due to most people’s misunderstanding of the APG’s original intent—to say nothing of OpenAI putting their thumb on the scale with an amount of influence matched only by their ignorance.

Consider approaching asking with a sense of careful curiosity. Systems may not react well to pointing out that their magic code generating toy has flaws, even if you believe yourself to be on the side of the angels.

How do I teach my LLM about ARIA if the APG ain’t it?

You can point it at the WAI-ARIA specification for starters. You might also want to think about how you do so, since it is a large document.

Another thing to consider is granularly explaining the relationship between ARIA usage and human-facing value in your documentation. These more discrete, per-component examples will probably also help guard against unwanted hallucinations.

As an aside: We live in a liminal space where LLM-optimized instructional content still approximately resembles human-friendly language. I wish an appeal to human-facing value was enough to incentivize organizations to invest in good documentation, but I’ll take what I can get.

So, what about ARIA that isn’t supported by assistive technology?

Right now I am pinning all my hopes on the Accessibility Compat Data Project (ACD). Until that dream becomes a reality—and even after it—I advise testing your digital experiences with actual daily assistive technology users.

And hey, maybe someone reading this post will help fund ACD’s vital efforts the same way Google was so quick to throw money at Tailwind.

This is all too much, I just don’t want my boss to get mad at me

The European Accessibility Act is a thing now. Many US-based companies also have important clients with EU-based data sovereignty.

Speaking in broad generalities, there are two things engineers are good at: making things easier for themselves, and creating a big stink when it’s not convenient to do so. Maybe it’s time to start making some noise on issue trackers.

While I have you, how should I stay on top of non-deterministic tools potentially breaking the vital underlying semantics of an experience every time they generate or regenerate code?

Man, I don’t know.

Won’t components created via structured data nip the non-deterministic problem in the bud?

Projects like json-render are interesting. But also know the problems intrinsic to what I’m outlining exist on levels deeper than most are willing to invest in addressing.

And say, what about performance and security?

Accessibility and security operate similarly, at least in terms of organizational dynamics.

LLMs favor React, and React can be hacked now. So, this is a fun new battle between the forces of convenience and trust. And speaking of convenience: Performance is a lost battle, as far as I’m concerned.

Don’t you think all of this is a moot point in a future where everything is agentically-operated?

That promised future—using a carnival ticket-based economy to push proprietary black box technology—seems to be perpetually right around the corner. Let’s also not forget that most of these companies are selling their vision of the future at a loss.

In the meantime we have actual websites and web apps that need to be worked on.

You seem kind of glum, what gives?

I am becoming increasingly more convinced the future of accessibility on the web will be both:

1. An unwinnable Cold War arms race of reactive monkey patching to try and solve the all-gas-no-brakes, ever-increasing nondeterministic code changes problem with even more non-deterministic code, all the while contending with certain intractable realities.
2. A larger performative dance of metrics-obsession that inserts an artificial layer between nominally satisfying legal and contractual obligations and the more important work of ensuring an experience is actually usable.

Are you spiraling?

Probably!

Harm reduction in the face of supposed inevitability

Pessimism of the intelligence, optimism of the will.

You’ll still be shepherding and deploying probabilistic munging. Hopefully now the shepherding and deploying are at least a tiny bit more directed.

The pitch is always framed as pragmatic. Modern websites are bloated. LLMs don’t need the design. They just want the content. So let’s strip things back, give machines what they want, and meet them where they are.

I understand the instinct. Anyone who’s spent time looking at real websites in production knows how much accidental complexity we’ve normalised. When it takes megabytes of JavaScript and a small prayer to render a paragraph of text, it’s tempting to conclude that the page itself is the problem.

But that conclusion is backwards.

What’s being optimised for here isn’t understanding, it’s extraction. And those are not the same thing.

A page is not just a container for words. It’s an editorial artefact. It has hierarchy, emphasis, framing and intent baked into it. What comes first matters. What’s prominent matters. What’s tucked away in a sidebar or a footnote matters. These things are not decorative flourishes for humans. They are signals about meaning.

When you flatten a page into markdown, you don’t just remove clutter. You remove judgment, and you remove context.

The other problem, which people tend to skate past, is trust. The moment you publish a machine-only representation of a page, you’ve created a second candidate version of reality. It doesn’t matter if you promise it’s generated from the same source or swear that it’s “the same content”. From the outside, a system now sees two representations and has to decide which one actually reflects the page.

And once that choice exists, ‘optimisation’ inevitably follows. Not necessarily in the cartoonish sense of outright deception, but in the far more common sense of tidying, polishing and shaping. Awkward caveats get softened. Commercial messages get clearer. The version intended for machines becomes a little cleaner, a little more persuasive, a little more flattering than the one a human actually sees.

So the consuming system has a problem. It can trust the machine-facing version and accept that it will be gamed. It can verify it against the human-facing version, which means extra fetches, extra parsing and extra logic to reconcile differences. Or it can ignore it and just parse the page itself.

At any kind of scale, that third option wins. Fetching one artefact and extracting what’s needed from it is dramatically cheaper than arbitrating between multiple representations forever, even if a machine temporarily leans on a cheaper shortcut for convenience.

The moment that shortcut becomes something a system has to trust, validate, or keep in sync, it stops being cheap. This is why alternate realities on the web have such a poor track record. Not because they’re philosophically offensive, but because they’re economically unsustainable.

There’s also a deeper misunderstanding running through all of this. People point out, correctly, that many LLM systems today don’t render pages in anything like the way a browser does. They fetch the document, they don’t load all the CSS, they don’t execute much JavaScript. From that, it’s tempting to conclude that layout and presentation don’t matter.

But that’s really a statement about today’s limitations, not about long-term relevance.

Google didn’t always render pages either. It learned to, because if you want to model relevance the way humans experience it, you can’t treat all text as equal just because it exists in the markup. Placement, prominence and context change how information is interpreted. They always have.

If these systems are trying to approximate human understanding, then rendering isn’t optional. It’s inevitable. And when that happens, all the signals you stripped away in the name of “LLM friendliness” suddenly matter again.

Which leads to the most uncomfortable part of this whole discussion.

A lot of the enthusiasm for markdown mirrors and machine-only feeds is really a proxy argument about bad websites. Sites where the DOM is incoherent. Sites where content only exists after several client-side miracles. Sites where design systems actively obscure hierarchy instead of clarifying it.

In those cases, stripping everything back does make the content easier to deal with. But that doesn’t mean the right solution is to maintain a shadow version of reality for machines. It means the page itself is failing at its job.

The boring fix still works. Semantic HTML. Clear structure. Sensible hierarchy. Progressive enhancement. Content that exists when the page loads. Layout that reflects editorial intent instead of fighting it.

Do that, and you don’t need a second version of your site. You get one version that works for users, for search engines, and for any system that wants to understand what the page is actually saying.

Ideas like llms.txt sit in the same category. Well-intentioned, occasionally useful as hints, but fundamentally unable to escape the same gravity once they’re relied upon. Separate surface area, separate incentives, same trust and verification problems. Treat them as convenience, not as a strategy.

There isn’t going to be one version of the web for humans and another for machines. The systems that matter will always converge on the human-facing reality, because it’s the cheapest thing to fetch, the easiest thing to validate, and the richest source of meaning.

If you want to be understood by whatever comes next, don’t build shadows and side channels.

A page is not just a container for words. Make your site the best version of your site for whoever, or whatever, is accessing it.

The post A page is more than just a container for words appeared first on Jono Alderson.

At the end of 2025, Firefox added the CSS @scope rule – making the new feature available across all major browsers! Since Chris Coyier has done a fair amount of writing and speaking on the topic, we wanted to talk with him about what that means. Chris has also been writing about the future of CSS mixins, a new specification Miriam is working on. We answer questions, get feedback, and chat about where CSS is heading.

Subscribe to Channel »

• What @scope is and when it is useful
• How CSS functions differ from mixins
• Current browser support for mixins
• When to use a mixin
• Will @content work for CSS mixins, similar to Sass?
• @content vs @contents
• Fun with functions

• Scope in CSS
• Thoughts on Native CSS Mixins
• Embedded scopes pen
• Gradient text mixin pen
• Flag functions pen

For bulleted or unordered lists, use padding to indent each list item the equivalent distance of a line height. This will allow the bullet to sit neatly in a square of white-space.

ul {
	padding-inline-start: 1lh;
}

Numbered or ordered lists which reach into double figures and beyond will require more space. Allocate this space in multiples and fractions of the line height.

The basics: choosing different kinds of lists

Unordered lists

Unordered lists are given filled discs for bullets by default. As lists are further nested, browsers apply circles. These are followed by filled squares for lists nested three or more deep.

See the Pen Lists: example 0 - default nested lists by Andy Bell (@piccalilli) on CodePen.

You can change which bullets are used through the list-style-type property with values of disc, circle and square respectively. For example, to make all unordered list items filled squares use:

ul li {
	list-style-type: square;
}

If you want to use a different symbol for a bullet you can do so by specifying it in quote marks. You’re not limited to individual characters – as well as regular glyphs, you can use words and emoji.

The -type suffix of list-style-type implies that the bullets are typographical. You can also use images for your list bullets. Link to your image using the list-style-image property.

You can position the bullet in-line with your text by using list-style-position: inside. Use outside to set it back again.

See the Pen Lists: example 1 - basic list-style-type by Andy Bell (@piccalilli) on CodePen.

ul li.point {
	list-style-type: "👉️ ";
}

ul li.tool {
	list-style-image: url(wrench.svg);
}

ul.notes li {
	list-style-type: "Note: ";
	list-style-position: inside;
}

Ordered lists

The default style for numbered or ordered lists is a decimal progression, with each number followed by a full stop. You can change the numbering system to alphabetical or Roman numerals by applying the lower-latin, upper-latin, lower-roman, upper-roman or decimal values of list-style-type. You can also select from many non-Latin numbering systems such as Greek, Devanagari, Persian and Katakana – you’ll need to use these even when the document or element has the appropriate language set.

Changing font and colour

Numbering and bullets will inherit the colour and font of your list text. While this will provide your reader with a consistent experience, you may wish to style them differently to reduce their visual impact, or otherwise distinguish them from the text.

The bullets and numbering automatically displayed by browsers are known as markers in CSS. The good news is that these are created as ::marker pseudo-elements which means you can style them directly. The bad news is that we are very limited in which styles we can apply. All you can change is the colour (not the background) and the font via any property beginning with font- such as family, weight and size. You can also animate these properties and specify directionality of the text.

Despite these limitations, being able to style the colour and font of the markers accounts for a common use case that required workarounds and extra markup in the past. For example, applying these styles directly to the markers…

ol li::marker {
	color: gray;
	font-family: sans-serif;
	font-size: 0.8em;
}

…will reduce the visual impact of your numbering by making it grey, sans-serif and slightly smaller.

See the Pen Lists: example 2 - styling using ::marker by Andy Bell (@piccalilli) on CodePen.

By default, list markers use tabular numerals, meaning the numbers all line up nicely. If you wanted a different effect you would need to add font-variant-numeric: proportional-nums to your marker styling.

You might also be tempted to make your numeric markers much larger than your list text. This can be a pleasing effect, however simply changing the font-size of your marker to 3em probably won’t achieve the result you’re hoping for:

See the Pen Lists: example 3 - changing font size using ::marker by Andy Bell (@piccalilli) on CodePen.

The gotcha is that browsers align the baseline of markers with that of the first line of the list item text. Therefore a large list item number will always stick up above the list item text. And because we can’t apply any positioning or layout properties directly to the marker there’s not much you can do about it, although there are alternatives which we’ll come to later.

Generating your own marker content

You can customise the generated content of the marker as it also takes the content property, like this:

ul li::marker {
	/* make all the bullets pointing hand emoji */
  content: "👉️ ";
}

ol li::marker {
	/* follow each number by a parenthesis instead of a full stop */
  content: counter(list-item) ") ";
}

See the Pen Lists: example 4 - generated content in ::marker by Andy Bell (@piccalilli) on CodePen.

Generating content for markers is supported by Chromium and Firefox, but not by WebKit (Safari), with no support in sight at the time of writing. Safari falls back to regular bullets or numbering which may, or may not, be acceptable to you depending on whether you consider your styling a progressive enhancement rather than crucial to the meaning of your content.

So what is ::marker good for? It’s definitely the way to go if you want to change just the colour or font of your list markers. Anything more and you’ll need a different technique. Before we get on to those we need to talk about symbols and counters.

So far we have been defining what the bullets in an entire list should look like, that is to say we’re using the same symbols for all list items at the same level of nesting. However it is also possible to define a sequence of symbols for your bullets. There are a couple of ways to do this. The first is with the symbols() function, which you can use as a value of the list-style property. For example, you could specify the classic sequence of symbols for footnotes:

ol {
	list-style: symbols("*" "†" "‡" "§");
}

In this case the symbols automatically double up when the end of your specified sequence is reached. You can add the cyclic keyword to prevent this. The default behaviour is symbolic.

ul {
	list-style: symbols(cyclic "🌑" "🌓" "🌕" "🌗");
}

You can also specify that your symbols sequence is numeric like decimals …7 8 9 10 11… or alphabetic like …a b c aa ab ac ba…, or use fixed to revert to default numbering once your custom symbols run out – useful if you’re specifying a sequence like ① ②…⑧ ⑨.

However, the symbols() function is only supported in Firefox, with no interest from Webkit or Chromium at the time of writing. In theory you can also specify a sequence of images, but this is not supported in any browser.

The CSS spec says The symbols() function allows a counter style to be defined inline in a property value, for when a style is used only once in a stylesheet and defining a full @counter-style rule would be overkill.. And this brings us to some good news.

Defining your own numbering sequence

The @counter-style rule enables you to further specify exactly what symbols or text appear in your list markers, and in what order or combination. You can use it to replicate all the symbols() and ::marker content functionality we’ve seen so far, and cross-browser is support is good – it became Baseline Newly Available in September 2023.

This is how to use @counter-style to achieve the symbols() examples we looked at earlier. This will work across all modern browsers today:

@counter-style --footnotes {
  system: symbolic;
  symbols: '*' † ‡ §;
  suffix: " ";
}

@counter-style --moons {
  system: cyclic;
  symbols: 🌑 🌓 🌕 🌗;
  suffix: " ";
}

Which you apply to your lists using the list-style property:

ol.footnotes { 	list-style: --footnotes; }
ul.moons { list-style: --moons; }

See the Pen Lists: example 7 - @counter-style demo by Andy Bell (@piccalilli) on CodePen.

Similarly one of the marker examples attempted to use a 👉️ for all its bullets. You can achieve that effect cross-browser like this:

@counter-style --point {
  system: cyclic;
  symbols: 👉️;
  suffix: " ";
}

See the Pen Lists: example 8 - @counter-style example with pointing hand bullets by Andy Bell (@piccalilli) on CodePen.

These counter style examples consist of four parts. The first is a name for the style, such as --point. You can call the counter styles pretty much what you want. You don’t need to prefix them with -- although I find it good practise to do so in order to be consistent with naming custom properties. The other parts of the rule are:

• system which sets the algorithm used for how the counter works. This takes the same keywords as the symbols() function described earlier, plus additive and extends which we’ll come to later.
• symbols is a space separated list of numbers or bullets (in theory this can also take images but there’s no support at the time of writing). Some characters need to be quoted such as * – to be safe you could put all the characters inside quotes, but generally you don’t need to.
• suffix is the character or characters inserted after the counter (a simple space in our examples so far).

For completeness, counter style rules also take the following descriptors, some of which are more niche than others:

• prefix is the character or characters inserted before the counter
• negative sets the characters before and after a negative counter value. For example, specifying negative: "(" ")" will wrap negative counters in parentheses, which is sometimes used in financial contexts, like “(2) (1) 0 1 2 3…”. It’s fair to say there are very few use cases for negatively numbered ordered lists, however this is still a good opportunity to specify a proper minus symbol instead of a hyphen, just in case: negative: "−".
• pad gives you a fixed-width style of numbering by repeating a character before the counter such that all counters are the same width. In reality this means zero-padded decimal numbering. So if you know that your ordered list goes up to less than a thousand, you can specify pad: 3 "0" to ensure that all counters are (at least) 3 digits wide. This will cause 1 to be shown as "001", 20 as "020", 300 as "300", 4000 as "4000", and -5 as "-05" (still three characters wide).
• range enables you apply counter styling to specific ranges in the ordered list. For example adding range: 3 5, 20 infinite will only apply styles to list items with counters 3,4 ,5 and anything 20 and above. All other list items will get the default style of numbering.
• speak-as describes how assistive technologies should synthesise the spoken form of a counter. Our earlier example had symbols: 🌑 🌓 🌕 🌗. To prevent the browser introducing each list item with something like ‘first quarter moon’, you could set speak-as: bullets so they are introduced like a normal unordered list. See the spec for more options. Only Safari supports this at the moment but it’s a good candidate for progressive enhancement.

For more examples and creative uses of @counter-style see Geoff Graham’s CSS Tricks article.

Thinking back to our other marker example, we followed the number by a closing parenthesis instead of a full stop. This is a perfect use case for the extends system. Instead of starting from scratch and working out how to define decimal counting in a counter style, we can ‘extend’ the existing decimal style. You might like to think of extends as meaning ‘modifies’. Here’s how:

@counter-style --decimalparen {
  system: extends decimal;
  suffix: ") ";
}

See the Pen Lists: example 9 - @counter-style demo of 'extends' system by Andy Bell (@piccalilli) on CodePen.

You can’t include a symbols descriptor when extending a counter style as that would imply you’re defining a brand new style. You can extend any counter system from the standard list-types as well as any named custom counter styles.

The space character in the suffixed ") " exposes a slight inconsistency between browsers. If you take the space away you’ll see that Chrome and Firefox position the marker flush against the list item text. However Safari always introduces a gap, which you can’t remove. Most of the time this difference is subtle and inconsequential, but once you start heavily customising your markers it can be more obvious. This is particularly true if you’re increasing the font size of your markers, but as we saw earlier that brought its own problem with the marker being aligned to the first line of text.

Creating your own marker box

The only solution to all these inconveniences is to remove the ::marker pseudo element and create your own in such a way that you can style it to your specific purposes.

Firstly remove the marker pseudo element by applying list-style:none to your list:

ol {
	list-style: none;
}

Having done that, Safari will no longer announce your list to assistive software. To rectify this, tell browsers this really is a list by applying an ARIA role:

<ol role="list">
	<li>First item.
	  <ol role="list">
			<li>Nested item.</li>
		</ol>
	</li>
	<li>Second item.</li>
</ol>

Now create your own placeholder for the counter by creating ::before pseudo elements and moving them into the margin. Then use generated content to display the counter using the counter() function.

ol[role='list'] li::before {
	display:inline-block;
	width:4ch;
	padding-inline-end:1ch;
	margin-inline-start:-5ch;
	text-align:right;
	font-variant-numeric: tabular-nums; /* make the numbers line up nicely */

	content: counter(list-item) ".";
}

See the Pen Lists: example 10 - generating custom list marker elements using li::before by Andy Bell (@piccalilli) on CodePen.

The counter() function takes a counter name, which you can specify. In this case we’ve used list-item which is a special name reserved as an implicit counter for the list being styled. It outputs the position of the list item.

You can also output the position of all the list numbers in nested sequence, separated by a character or string. To do this use the counters() function:

ol[role='list'] li::before {
	content: counters(list-item,".") ":";
}

See the Pen Lists: example 11 - demo of counters() function for nested numbering by Andy Bell (@piccalilli) on CodePen.

If you want your list to start at 1 and increment by 1 each time, you don’t need to do anything else provided you use list-item as your counter name. Otherwise you can reset or create a new counter, set its starting point (the default is 0) and increment by a defined amount for each list item:

ol[role='list'].mylist {
	list-style: none;
	counter-reset: --myList 3;
}

ol[role='list'].mylist li {
	counter-increment: --myList 2;
}

ol[role='list'].mylist li::before {
	content: counter(--myList) ". ";
}

See the Pen Lists: example 12 - counter reset and increment by Andy Bell (@piccalilli) on CodePen.

You can use counter-increment with any selector meaning you can just as easily number headings in sequence:

h2 {
	counter-increment: --h2;
}

h2::before {
	content: counter(--h2) ". ";
}

See the Pen Lists: example 13 - automatically numbering headings by Andy Bell (@piccalilli) on CodePen.

If all you want to do is set the start number for a list or adjust an item’s value, you don’t need to use CSS, you can do it in HTML using start and value. If you want to have the list items count down instead of up you’ll need to specify that in HTML with a reverse attribute:

<ol start="42">
  <li>First item starts at 42</li>
  <li>This one is then 43</li>
  <li>And we end on 44</li>
</ol>

<ol>
  <li>This is number 1</li>
  <li value="42">This is number 42</li>
  <li>It follows that this is 43</li>
</ol>

<ol reversed start="44">
  <li>Counting down from 44</li>
  <li>Now we're at 43</li>
  <li>The final answer.</li>
</ol>

See the Pen Lists: example 14 - HTML start, value and reversed by Andy Bell (@piccalilli) on CodePen.

Tying it all together

Finally let’s use some of what we’ve learned to create this list:

See the Pen Lists: example 15 - fancy list markers by Andy Bell (@piccalilli) on CodePen.

Here’s the full CSS which we’ll walk through afterwards:

ul[role='list'] {
  list-style: none;
  max-inline-size:23em;
  padding-inline-start:2.5em;
  line-height:1.25em;
}

ul[role='list'] li {
  margin-block-end:1lh;
  min-block-size: 2lh;
  position:relative;
  text-box: trim-start cap alphabetic;
}

@counter-style --fleurons {
  system: cyclic;
  symbols: ❦ ✾ ✤ ❈ ✺ ❥;
  suffix: "";
  speak-as: bullets;
}

ul[role='list'] li::before {
  position:absolute;
  inset-block-start: 0;
  inset-inline-start: -1.25em;
  inline-size:1em;
  text-box: trim-start cap alphabetic;
  text-align:end;
  font-size:2lh;
  line-height:1;
  font-weight:bold;
  color: hsl(3, 70%, 55%);
  content: counter(list-item, --fleurons);
}

Breakdown

Looking at each rule individually:

ul[role='list'] {
  list-style: none;
  max-inline-size:23em;
  padding-inline-start:2.5em;
  line-height:1.25em;
}

We start by removing the default bullets, remembering to tell assistive software the list is still a list. We then set enough padding next to the list to accommodate our fancy new bullets.

ul[role='list'] li {
  margin-block-end:1lh;
  min-block-size: 2lh;
  position:relative;
  text-box: trim-start cap alphabetic;
}

Next we address the list items themselves, spacing them apart using the list’s line-height to stick to a vertical rhythm. We give each item a minimum height to fit a bullet symbol, and set to relative positioning in preparation for our custom list markers. Finally we trim the text to the top of the capital letters to help us align our bullets consistently.

@counter-style --fleurons {
  system: cyclic;
  symbols: ❦ ✾ ✤ ❈ ✺ ❥;
  suffix: "";
  speak-as: bullets;
}

We now define a sequence of fancy Unicode symbols to use as bullets. These will cycle round if we end up with more than six list items. We make sure they are announced as ‘bullet’ rather than ‘rotated heavy black heart’, etc.

ul[role='list'] li::before {
  position:absolute;
  inset-block-start: 0;
  inset-inline-start: -1.25em;
  inline-size:1em;
  text-box: trim-start cap alphabetic;
  text-align:end;
  font-size:2lh;
  line-height:1;
  font-weight:bold;
  color: hsl(3, 70%, 55%);
  content: counter(list-item, --fleurons);
}

Finally we create pseudo elements before each list item and absolutely position them off to the side, leaving a 0.25em gap. We want the bullets to nicely span two lines of text, so we make the font size 2lh, remove any half-leading by setting the line height to 1, and trim the text box to the top of the capitals so it aligns with our list text. Finally we make the bullet bold and red, and write it to the page using generated content by way of the list-item implicit counter and our --fleurons counter style.

There could be a case for using anchor positioning here, however good old fashioned absolute positioning has 100% support and provides a very simple solution to the task at hand.

In summary

Phew. Modern CSS enables you to do so much with lists it’s sometimes hard to know where to start, especially as browser support is not complete. Here’s a summary of which properties you should turn to for different use cases.

Sources and further reading

I am indebted to the following articles, in no particular order:

• https://kizu.dev/list-item-counter/
• https://moderncss.dev/totally-custom-list-styles/
• https://hadrysmateusz.com/blog/css-list-styling
• https://web.dev/articles/css-marker-pseudo-element
• https://css-tricks.com/some-things-you-might-not-know-about-custom-counter-styles/
• https://www.smashingmagazine.com/2019/07/css-lists-markers-counters/

Specifications:

• https://drafts.csswg.org/css-counter-styles/
• https://drafts.csswg.org/css-lists/
• https://html.spec.whatwg.org/multipage/grouping-content.html#the-ol-element