/reader

• Well, I think I'm done. I've got the outline for the slides complete. I can't possibly talk about all the stuff that's in the slides. Once I leave tomorrow I think perhaps I'll post a link for the slides and maybe offer a place to comment. Maybe. #
• I get very nervous about these things and then remember when I've prepared as much as I have for this, the talk goes quickly and people generally are nice, though I've been ambushed a few memorable times. Let's see -- Austin, Cambridge, San Francisco and Nashville come to mind. ;-)#
• In Austin it was because I was privileged. I was being honored because it was the 25th year of my blog, and I was one of the keynoters. I told the promoter his people wouldn't like me, and then I forgot I said it when it happened. I was stuck, I didn't want to get into a public argument with anyone. (Had I wanted to rebut, I would have said everyone in this room is privileged, just look around at how well fed and educated everyone is. We all flew in here. We live in a rich country where we are the elite of the elite. Now STFU, in my dreams.) #
• There have been times when I welcomed an argument...#
• In San Francisco, I was invited to lead a panel from the music industry about how great Napster was. This was probably in 2000 or 2001 when Napster was at its peak. It was an ambush. All the panelists made me the issue, and then they voted to kick me off the stage. I stayed there and waited until they exhausted their rage, and then asked them a question about music and Napster. Acted like nothing had happened. I had earned my place there, I was a very early industry adopter of Napster. I loved what it did for us. Imagine until then you either had to buy an album to listen to music, build a collection, or wait until it was played on the radio. (What is radio? Kind of an early form of podcasting.) People were talking about music in supermarkets and airports. This could not be stopped, I was sure of it, and they were acting like babies. I stood up and prevailed.#
• In Nashville, I was invited to be a sort of keynoter for a conference that was patterned after BloggerCon. I did not organize it, but I led a session, which was attended by a famous right wing blogger who I had invited to the Harvard BloggerCon. He brought a bunch of his friends, and they each said no one was listening to them but we were listening to them. I eventually sat down and let them have a session dominated by a few people repeating themselves. It was boring. #
• Finally I was set up by the promoters of a CMS conference which Berkman hosted at Harvard. I was the master of ceremonies. No one told me that one of my most virulent trolls was there, and when he got up to rage at me I asked him to sit down, but Charlie Nesson who was the senior educator there, and kind of naive about internet trolls, said he should speak his mind. I should have walked out at that point. I knew what was coming. It really shook me. #
• In Nashville a columnist in a local paper who said I caused the riot, btw. I swear to god I always take my discussion leader role seriously. I gave them all a chance to talk and they all said the same thing, almost as if they had been told to say it. #

Unfortunately, I can’t link you these observations because at some point after publication they completely rewrote the post into a completely different set of observations, with no trace of what I’d found to be the critical bits of criticism that had given me something onto which to latch.

(We all know my strident opinions on the matter of editing old posts, and they basically extend to new posts as well. I’ve said that I do have a window of as much as a day or so when I will make minor edits or suddenly remember an entire paragraph I’d forgotten to include, after which time I either add an addendum to the post or I write an altogether new one. What I don’t do it leave the post in place, at its original URL, and completely replace its text. To be clear: any given blogger can do whatever they damned well please. It’s just that this is a particular thing over which I cannot help but be quite peevish.)

At any rate, the issue the now etherized text raised which helped clarify my reservations as to Manu’s post basically was that Manu didn’t bother to include any actual, real-world examples of his point of contention, opting instead to offer an “out there” hypothetical regarding the kicking of puppies. In this scenario, there are strident supporters of kicking puppies and strident opponents of doing so.

But what if the pro-puppies camp you hear from online doesn’t stop at "puppies should be loved" but also argues that people who kick puppies should all die now and be dissolved in acid and their families be shot into the sun? You clearly are supporting the puppies' cause, but you are definitely not on board with all the rest of the nonsense.

What do you do then, when someone screams at you, asking which side you are siding with? You clearly love puppies, but you also don’t want to support drowning people in acid. So you’re fucked. You could try to explain your position, but nobody got time for that. Chances are, you say nothing, and you silently move away from the public discourse space, never to be seen or heard again.

The problem with limiting the discussion of the “two sides” to an outrageous hypothetical is that it’s tough to translate into whatever actual, specific, real world scenarios might have set Manu off down this path. If there’s any such extremities to the positions of people generally on the side of the right and the just, in that they are calling for their opponents to “die now and be dissolved in acid and their families be shot into the sun”, they are outliers and in the small minority.

What we tend to have in the real world is more like the recent situation on Bluesky where the CEO mocked people’s concerns about a transphobe’s continued presence on the site, and the attendant, ensuing situation wherein with a complete lack of curiosity as to the specifics of the matter the maker of another microblogging service reflexively defended the Bluesky CEO and CTO against criticism.

In this non-hypothetical situation, few if any were calling for death, acid, and the solar expulsion of family members. What they called for was, in the case of the CEO and CTO, a recognition that (to use Manu’s hypothetical) they should ban proselytizers of puppy kicking even if they haven’t yet proselytized about it on Bluesky itself; and, in the case of the owner of micro.blog, some sense of desire for awareness outside his preferred class bubble.

It’s true that in many cases their critics were attempting to shame them into a more expansive and magnanimous view of the issue at hand, but that’s because outing shameful views is part of how we live in a society—or at least how we live in one that’s going to be functional for the widest possible numbers of people and groups of them.

“It’s bad when a lot of people are scared to express what they think because they are scared of the repercussions,” writes Manu. “Because you can’t have a healthy society without open dialogue.” What this gets wrong in its assumptions is the idea that shame is not meant to be part of open dialogue. If we are placing shame, and its kissing cousin shunning, somehow outside the bounds or beyond the pale, then we aren’t at all in an open dialogue in the first place because open dialogue necessarily includes being both called in and called out, to be confronted by why you’re wrong.

As I wrote just yesterday about two writers for The Atlantic acting as apologists and hagiographers for the boot-licking Bari Weiss (one of whom was ranting about the alleged dangers of some leftist “thought-police”), there is right now only one side actively plotting actions which amount to the idea that certain people “should all die now and be dissolved in acid and their families be shot into the sun”—the other side meanwhile still mostly just continues to wonder why the cruelty and wishes that people who aren’t that extreme in both their words and deeds would simply be more careful about what they believe, say, and do, and a little more curious about the effects their own beliefs, words, and actions might be having upon other people already fighting for their lives.

All of which is just to say that in the current environment, blithely disregarding the concerns of trans people (in the one real-world example) or reflexively and incuriously feeling solidarity with other tech bosses (in the other real-world example), does contribute energy to the “wrong side”. In an open dialogue, we get to explain this to them. In a truly open dialogue, they’d also be open to change.

Absent any specific, non-hypothetical situation offered up by Manu himself, this is the only way I can think to respond to his concerns. The problem is that in refusing to discuss actualities, you really just end up saying nothing. The simple truth of things is that words are actions upon the world, and we have every right to shame and shun those whose actions—regardless of intention—disappointingly amount in the end to just so much more senseless punching down.

Reply by email • Tip $1/month • Thank you for using RSS • Oct. 18: #NoKings

It wasn't just that blogs hadn't been updated in a while, I noticed that I was marking things as read just to get the numbers down. There was a sense of guilt that I wasn't reading certain things because I didn't have the headspace for them.

There were posts I wanted to read that sat in /reader while I dismissed those around them, and I never got around to reading them.

There were a few other blogs that I no longer "vibed with" so they went too. It's not a comment on the authors, just that my tastes or priorities changed.

Recently, I have seen a number of people blogging about blogging: Should they stop? Why blogs are/aren't isolated. Why they hadn't posted in a while. Nostalgia for the "old web", and the like.

There seems to be a growing dissatisfaction with the internet. Whether it's due to the state of the world right now, or politics and the division it causes, or merely resentment of the centralised platforms. It's as though a malaise is seeping through the web and we're all being impacted by osmosis.

It reminds me of 2016 when Brexit and the first Trump election were the prevailing winds on the web. It didn't matter how much you tried to avoid it all, it always got through.

I say that a lack of posts is usually an indicator of mental health. I wouldn't say I'm particularly depressed at present, more bored and exasperated. Bored of my job, exasperated at the state of (waves hand) all of this.

It's all just a bit … meh.

As I wrote a couple of years ago about that time:

You were told you were following the wrong people but, suddenly, just about everyone became the wrong people. Social was no longer about having fun, it was a place for outrage and division.

The more things change, the more they stay the same.

This isn't me saying, like I have on more than one occasion, that I'm stepping away from it all. No, I'm staying around but trying to limit what I'm exposed to.

Whether this means trying to extricate myself from the 24 hour news cycle, or muting a bunch of words on Bluesky, I don't know.

I do know, however, that I have let this affect me for too long and that I have neglected the blog. I fully intend to post more often.

We'll see how it goes.

So I found a seat in the lounge, grabbed a cup of coffee (there’s always free coffee at car repair places here in Sweden, it’s practically a law), and opened my laptop. By the time my car was ready, so was the little thing I’d built while waiting: a new notes section ¹.

Those two hours flew by. Honestly, I wouldn’t have minded if they’d said it would take an extra hour.

Hobbies are important. We all need a hobby — and if at least one of them works anywhere, that’s a win.

 

One unsung feature in the web components space that I don’t think gets enough attention is the Custom Elements Manifest initiative. I think it’s the killer feature of web components.

Known as “CEM” to its friends, a CEM is a community standard JSON format that surfaces information about your component APIs. The analyzer scans your class-based component to build up a “manifest” of all the methods, events, slots, parts, tag name, and CSS variables you want to expose. It works on a single component or an entire system’s worth of components. If you want to surface more details to consumers (like accepted attributes or CSS custom properties), you can provide more context to the analyzer through JSDoc comments and/or TypeScript types – which is good code hygiene and a favor for your future self anyhow. Here’s an example from the playground:

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the color of bar
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {Event} typed-event - some description for typed-event
 * @event {CustomEvent} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

The JSDoc notation is forgiving (it supports both @cssprop and @cssproperty) and with the ability to document your ::part() and <slot> APIs, it’s more descriptive than what you’d get with a basic TypeScript interface. Eagle-eyed observers will notice there’s a distinction made between an @attribute and an @property, that’s because those are different concepts in HTML, ergo different in Custom Elements. Attributes (strings, numbers, booleans) tend to reflect, properties don’t.

After that thin layer of documentation, it’s a two-liner to generate the manifest:

npm i -D @custom-elements-manifest/analyzer
cem analyze

This will generate a file called custom-elements.json in your package directory.

{
    "schemaVersion": "1.0.0",
    "readme": "",
    "modules": [
        {
            "kind": "javascript-module",
            "path": "src/my-element.js",
            "declarations": [
                {
                    "kind": "class",
                    "description": "",
                    "name": "MyElement",
                    "cssProperties": [
                        {
                            "description": "Controls the color of foo",
                            "name": "--text-color"
                        },
                        {
                            "description": "Controls the color of bar",
                            "name": "--background-color",
                            "default": "red"
                        }
                    ],
                    "cssParts": [
                        {
                            "description": "Styles the color of bar",
                            "name": "bar"
                        }
                    ],
                    "slots": [
                        {
                            "description": "This is a default/unnamed slot",
                            "name": ""
                        },
                        {
                            "description": "You can put some elements here",
                            "name": "container"
                        }
                    ],
                    "members": [
                        {
                            "kind": "field",
                            "name": "disabled"
                        },
                        {
                            "kind": "method",
                            "name": "fire"
                        },
                        {
                            "type": {
                                "text": "boolean"
                            },
                            "description": "some description",
                            "name": "prop1",
                            "kind": "field"
                        },
                        {
                            "type": {
                                "text": "number"
                            },
                            "description": "some description",
                            "name": "prop2",
                            "kind": "field"
                        }
                    ],
                    "events": [
                        {
                            "name": "disabled-changed",
                            "type": {
                                "text": "Event"
                            }
                        },
                        {
                            "description": "some description for custom-event",
                            "name": "custom-event"
                        },
                        {
                            "type": {
                                "text": "Event"
                            },
                            "description": "some description for typed-event",
                            "name": "typed-event"
                        },
                        {
                            "type": {
                                "text": "CustomEvent"
                            },
                            "description": "some description for typed-custom-event",
                            "name": "typed-custom-event"
                        }
                    ],
                    "attributes": [
                        {
                            "name": "disabled",
                            "type": {
                                "text": "boolean"
                            },
                            "description": "disables the element"
                        },
                        {
                            "type": {
                                "text": "string"
                            },
                            "description": "description for foo",
                            "name": "foo"
                        }
                    ],
                    "superclass": {
                        "name": "HTMLElement"
                    },
                    "tagName": "my-element",
                    "customElement": true,
                    "summary": "This is MyElement"
                }
            ],
            "exports": [
                {
                    "kind": "custom-element-definition",
                    "name": "my-element",
                    "declaration": {
                        "name": "MyElement",
                        "module": "src/my-element.js"
                    }
                }
            ]
        }
    ]
}

API extraction through TypeScript or JSDoc isn’t a novel concept, but what I find novel is the community tooling built around it. With a Custom Element Manifest, community plugins can use that information to generate files, populate dropdowns, add red squiggles, provide autocomplete, and automate a lot of the mundane meta-system DX work that comes with supporting a component library:

• API Documentation - Your CEM can power your readme.md and component-level documentation.
• Storybook - Using the Storybook plugin you can use your CEM to automate the generation of your Storybook stories.
• Language Servers - It can be frustrating to not have your editor recognize the HTML you invented. CEM-powered language servers solve that issue. A few options here.
• Linter - Want to lint HTML before shipping? CEM can power this.
• React Wrappers - React 19 supports web components, but if you’re trying to use web components in a React <= 18 project, you’ll need little wrapper shims. Creating these by hand isn’t fun and we can hand this work off to the CEM.
• Other Framework Wrappers - Shims for SolidJS, Svelte, and Vue.js.
• JSX Types - JSX isn’t happy unless you add new interfaces to the JSX namespace. CEM can generate this for you.
• Jest Mocks - If you’re still using Jest in the year of our lord 2025, I feel bad for you but there are plenty of people in this situation. Jest hates Custom Elements because Custom Elements are real DOM and not VDOM. No plugin to link to (sorry!) but I have seen teams using CEM to generate Jest mocks to smooth over the process when integrating with legacy testing solutions.
• Figma Code Connect - If you want to connect your web components to Figma, you can automate that as well.
• MCP Server - If you want to give your AI Agents insights into the components available in the current project, you can install an MCP Server that parses your CEM. (Couple options here)

Burton Smith who runs WC Toolkit has been helping us roll out some of our CEM work and we’re starting to turn some of these capabilities on. One pain point I’m hoping to solve is too much boilerplate. We have a lot of files in our individual component packages to power assorted tasks and integrations and I can see a world where we generate nearly all our readmes, storybooks, and even some low-level test coverage from the CEM at build-time or run-time.

From a single file we get the following outcomes…

• Spend less time/energy maintaining and schlepping boilerplate code
• Improve baseline test coverage and make it more predictable
• Make new components easier to create, ideally speeding up development
• Reduce cognitive overhead when jumping into the project
• Provide a forcing function for more/better documentation
• Potentially improve the design-developer bridge through Figma Code Connect and MCPs

Again, I want to applaud the web components community here. There’s no VC-funded corporate overlord roadmap driving the Custom Elements Manifest initiative, just fellow enthusiasts. From a community perspective, that’s a positive signal for me. Adding it to your project is low-effort, high-impact type work and I probably only covered about a quarter of what a CEM can do for you, which goes to show a community agreeing on a standardized way to describe components is a powerful tool.