AAADAAAM

Vinyl is dead. Long live vinyl.

2016-01-01T00:00:00Z

My latest obsession is a very pretty, very shiny Pro-Ject Audio Carbon Debut DC turntable. Listening to music on it has quickly become my favorite way to listen, and not just because I get to use words like “plinth” in casual conversation.

I’m not alone. Amidst the sea of depression that defines the current state of the music business lies an interesting curiosity. While physical and digital album sales have been locked in a downward spiral since 2005, vinyl sales have exploded. In 2014 alone, digital sales declined 9.5% while vinyl sales increased by 52%.

The reason why may not be immediately obvious. After all, if you’ve spent any amount of time around a turntable you’d know exactly why vinyl was largely abandoned in favor of other formats.

Despite claims from many a vinyl purist, it doesn’t sound objectively better. It’s more expensive, less convenient, non-portable, requires more maintenance (both media and turntable), requires fiddly adjustments for best playback, can’t shuffle, repeat, or do much of anything. You can’t buy music for it instantly, etc. And for a minimalist model like mine, the only luxury is a tone arm lifter, which is really more for the benefit of your records instead of a convenience for you.

In other words, it’s not a terribly logical preference.

So then what’s the deal? Mass delusion? Those darn hipsters and their silly nostalgia? It comes down to one word. Experience.

As convenient and portable as digital music is, it has a singular flaw. It has no physical presence. You can’t see it, touch it, smell it. People who are choosing vinyl tend to be music lovers who are looking for a more emotional and personal connection to the music and artists they love. They also tend to have grown up in a digital only world, which is why experiencing vinyl is roughly equivalent for them to meeting a human in person for the first time when you’re only other contact with humanity has been telephone calls. There’s just no comparison.

But hey, what about CD’s? They’re physical media for sure, and the packaging can do some serious heavy lifting on the experience side of things when done right. But once you slap that disc in, you might as well be playing a digital file. It’s just another dead black box, and nothing like playing a record.

The satisfying thunk of the power switch as the record slowly spins up to speed. The few seconds of suspense as the tone arm slowly descends towards the platter. The thump that pumps from your speakers when it finally does. The few seconds of silence punctuated only by the occasional crackle or pop before the music starts. The fact that I have to get up and flip sides. The fact that I can’t just skip songs. The Rube Goldberg-esqueness of it all. And yeah, nostalgia is in there too.

On top of that, artists have recognized this new wave of vinyl enthusiasts and are pressing custom color vinyl to double down on the experience front. You know what’s better than a modern and minimalist turntable? A modern and minimalist turntable with a transparent red record spinning on it.

The Rider and The Elephant

The resurgence in vinyl despite the shortcomings of the format is handily explained by a behavioral psychology mental model called “The Rider and The Elephant”. The model was developed by Jonathan Haidt and is incredibly useful to explain how and why humans make decisions.

The rider represents your rational side, and the elephant represents your emotional side. The rider is in control, but that control is precarious. If the elephant decides to go in a different direction than the rider wants, the rider is powerless to do anything about it.

In the case of vinyl, that’s exactly what’s happening. Your rational mind may say “inconvenient!”, “expensive!”, “definitely do not buy this!”, but your (well, my) emotions say “honey badger don’t care”.

If you’re attempting to persuade someone to do something, you’re chance of success is much, much higher if you can convince both the rider and elephant.

When you don’t is when you hear statements like “I know it’s good for me (rider), but it looks and tastes gross (elephant)”, or “it fits my needs (rider), but I just don’t love it (elephant).”

When you do is when you hear statements like “shut up and take my money!”

Various industries tends towards trying to persuade the rider or elephant to differing degrees. The alcohol industry for example almost exclusively appeals to the elephant. People will want to sex you!” is the baseline pitch of 99% of alcohol advertising.

The automotive industry tends to do both. They make cars and marketing that appeal to your emotions, but then back it up with MPG, 0-60 times, safety test results, etc.

And then there’s the software industry. For most of its history the software industry has barely noticed the existence of the elephant. It’s been all rider, all the time. Apple’s rise to dominance was the event that finally had the industry stand up and say “OK, I guess experience really does matter”, but the lesson hasn’t fully sunk in yet. That’s why you still see site after site focusing on features instead of benefits. That’s why anything that’s not a bullet point feature tends to end life as an inglorious sacrifice on the altar of MVP.

But there’s an upside here. If you can identify and speak to the emotional drivers your customers have, you can compete handily against entrenched players in your space. Even if they have bigger budgets and more robust offerings. So acknowledge the elephant in the room. You’ll be better off for it.

Are you sure?

2017-03-01T00:00:00Z

I was Twittering away the other day, and Prettier came across my feed. Prettier turns the conceptual moorings of linting on its head. Instead of “Well, actually”-ing you when you make a commit and forcing you to fix whatever pedantic issues it’s complaining about, it just… fixes them.

As you can guess, I have an uneasy relationship with lint. I value what linting brings to the table, but I don’t like my tools saying, “You need to do x before I’ll do what you want.” Who’s serving who here? You’re a hammer. Swing.

This is a niche example of software behaving inconsiderately. A common example takes the form of three words guaranteed to upend the user / tool power dynamic with every invocation: “are you sure?”

It seems like an innocuous enough question to ask before you complete an action on their behalf, but think about how it would play out in real life.

Person A: “I’ve got my hands full with all this stuff. Mind opening the door?”

Person B: “Are you sure you want to open the door?”

Person A: “Uh, yeah. I wouldn’t have asked if I wasn’t.”

Person B: “OK, I’ll open the door.”

Person A: “Great, can you close it after me? I don’t want the dog to get out.”

Person B: “Are you sure you want me to close the door?”

Person A: “I really fucking hate you right now.”

You’d never do this in real life, but it happens all the time in software. Alan Cooper nails exactly what’s wrong with this question in his seminal book, About Face:

“Interactive products should stand by their convictions. If we tell the computer to discard a file, it shouldn’t ask, “Are you sure?” Of course we’re sure; otherwise, we wouldn’t have asked. It shouldn’t second-guess us or itself.

On the other hand, if the computer has any suspicion that we might be wrong (which is always), it should anticipate our changing our minds by being prepared to undelete the file upon our request.

How often have you clicked the Print button and then gone to get a cup of coffee, only to return to find a fearful dialog box quivering in the middle of the screen, asking, “Are you sure you want to print?” This insecurity is infuriating and the antithesis of considerate human behavior.”

—Alan Cooper

Self-confidence is one dimension of Cooper’s core design principle: Software should behave like a considerate human being.

What are some of the other dimensions that make a human (and software) considerate? They use common sense, don’t ask a bunch of unnecessary questions, keep you informed, help you avoid awkward mistakes, fail gracefully, anticipate the needs of others, and are preceptive and conscientious.

If you’re trying to make considerate software, don’t ask your user if they’re sure. Assume they’re competent humans who mean what they intend. If the action is potentially destructive, give them a way to gracefully recover if they change their mind (undo/redo, archive states, auto-save drafts, etc).

If you’ve fallen into the “Are you sure?” trap, well, welcome to the club. I certainly have, and so have a bunch of others. Sometimes you don’t realize you’re doing something inconsiderate, and sometimes time and money dictate other choices.

But next time you find yourself reaching for that question, take a step back and think about what you’re trying to accomplish. Do you really need to ask the user that? Is there another approach you could take that would be more considerate? If so, take it.

There’s such a thing as “too helpful”

2017-03-22T00:00:00Z

Not too long ago Jason Fried wrote about his experience shopping at Apple Stores, in which he described the common occurrence of walking into a store and being immediately set upon by a too helpful Apple rep (the “bouncer”).

In trying to be as attentive, helpful, and friendly AS HUMANLY POSSIBLE, this bouncer ended up being too helpful. Aggressively helpful.

What’s it mean to be aggressively helpful? It means that in your attempt to be as helpful as possible, you’ve prioritized that goal over the customer’s own desire. They don’t want your help right now, but by Grabthar’s Hammer, you’re going to give it to them.

If you’ve ever set foot on a car lot, you know exactly what aggressively helpful looks like. It’s personified by the ill-suited, slick-haired vultures with a plastic smile who swoop in the instant your toe touches pavement. Just wanted to look around? TOO BAD! You’re getting help!

Once largely confined to used car salesmen, aggressive helpfulness is making fast inroads among startups. Paradoxically, startups that genuinely care about customer experience (or at least purport to) seem to be the most susceptible to it.

Visited the website for a startup recently? If so, this will probably sound familiar. You land on the site and BLAMMO! Up pops a chat notification, with whomever-in-charge-of-customer-razzmatazz offering enthusiastically!!! if they can help you with anything?

In an effort to engage customers and serve them better, they’re often accomplishing the opposite. Just like it doesn’t feel great to be accosted the moment you step onto a car lot or into an Apple Store, it doesn’t feel great to be “engaged with” the moment you land on a website.

Rule #1 of being genuinely helpful: Respect the wishes of the person you’re trying to help.

It’s an innocent mistake to make. If you think of helpfulness and un-helpfulness as two ends of a spectrum, you can only do more good by adding more helpfulness, right?

But that’s not how it works. In reality, those two ends aren’t ends at all. Trying to be more helpful by violating rule #1 pushes you right back towards being unhelpful.

So what do you do if you’ve veered towards too helpful? Instead of unleashing an unrelenting fury of helpfulness when someone walks in your virtual door, chill for a minute.

Let the customer poke around, kick some tires, form some thoughts.

Be there, waiting. Ready to spring into action at a moment’s notice. Make getting your attention easy and obvious. Maybe offer some help if someone’s wandering around with a scrunched look on their face (or the digital equivalent thereof).

Just don’t let your desire to be as helpful as possible override what your customer actually wants.

Everything I know about marketing I learned from the 1990 movie “Crazy People.”

2018-01-11T00:00:00Z

For many many many people, the term “marketing” is interchangeable with words like “spin,” “flim-flam,” “malarkey,” and of course, “bullshit.”

You can’t really blame people who think this way. A huge amount of marketing is reality-ignoring bullshit/spin/hokum/snake oil.

This fact — that marketing is mostly poppycock — is the foundation that the movie Crazy People builds on. For anyone unfamiliar with the movie, here’s the quick synopsis (I swear this is relevant):

In Crazy People, Dudley Moore’s character is an advertising executive who does something absolutely unthinkable — he creates a series of ads that tell the truth. Here’s a few examples:

“Volvo — they’re boxy but they’re good.”

“Metamucil — it makes you go to the toilet.”

His agency rejects the ads and checks poor Dudley into a sanitarium thinking he’s taken leave of his senses. A mistake leads to the ads running in newspapers across the country anyway, at which point the unexpected happens. The ads work. Really well.

It’s tempting to write this off as nonsense movie hijinks, and it mostly is. But there’s a pearl of wisdom in there. As it happens, marketing and advertising that tells the truth can be incredibly powerful.

Truth-based marketing in the wild

Here are a few real-world examples of truth-based marketing:

This video from Saddleback Leather is one of my favorite examples. All he’s doing here is describing in detail how to knock off one of their bags. But the message is crystal clear: they put a ton of time and attention into making a bag that lasts. If you’re tired of bags that fall apart, Saddleback is for you. So good.

Apple may be well know for their “reality distortion field,” but Steve Jobs provided a fantastic example of truth-based marketing when he introduced the original iPod:

“The coolest thing about iPod is that your entire music library fits in your pocket. OK? You can take your whole music library with you, right in your pocket. Never before possible. So that’s iPod.”

They could have marketed the iPod a hundred different ways. But the product was so groundbreaking, they knew that that the best thing they could do was get out of the way and state this simple fact. 10/10.

Finally, a classic from Fiat. It would have been laughable to claim that a Fiat was just as good as a Ferrari, so they didn’t. Instead they call out the fact that a person with well established taste in cars (Mr. Ferrari himself!) chooses Fiat as his practical car of choice. Genius.

As you can see, you don’t have to sling baloney or shovel hooey to do marketing right.

How to make truth-based marketing work.

If you’d like to give truth-based marketing a try, you’re in luck. It’s remarkably straightforward! Here’s how it works:

Find a unique, desirable outcome that your product or company delivers to customers.
Talk about that thing.

People tend to not believe it’s this simple, so let’s run through some common questions:

“What if my product doesn’t solve any problems or have any real value?”

No marketing your way out of this one. Just ask Juicero.

Instead, you need to do the sounds-simple-but-is-incredibly-hard thing and make a better product or service. And while you do that, focus your marketing on a truth that’s appealing, but possibly not unique. Do you have great customer service? Talk about that.

“What if we don’t know why people are buying our product?”

This is a good place to be, but you’ve got some work to do. And plenty of customers to talk to. Just keep in mind that the reasons people tell you aren’t necessarily the real reasons they buy. Frameworks like Jobs to Be Done can help you figure it out.

Any other questions? No? Good.

I heartily recommend giving truth-based marketing a try. Not only will your company reap the benefits, but you get to wake up in the morning energized by the fact that you’re not adding to the ever-increasing volume of bunk, hogwash, and hot air in the world. It feels nice!

Death to process machines!

2018-04-04T00:00:00Z

You hear a ton of different advice on the right and wrong way to go about designing an app or website.

“You should be using Figma.”
“Design Systems or GTFO.”
“Real Designers design 100% in code.”
“Wireframes are a waste of time.”
“If you’re not making prototypes, you’re not doing it right.”
“You need to start on paper.”

You’d think there’s no agreement whatsoever about the right way to design, but there’s one point that’s largely free of controversy — that your process should be linear.

The classic linear approach looks something like this: research → sketch → wireframe → static comps → prototype → code

It’s kind of like those Rube Goldberg-esque manufacturing machines they use to make Doritos and Ding-Dongs. Drop an idea into the process machine, and after getting mashed and molded into shape as it winds through the steps a finished product pops out the other side! Predictable! Efficient!

Kind of.

Process machines work, but only when they work. They don’t adapt, and that makes them fragile. All it takes is one little Sabot to grind your process machine to a halt.

Hank, a.k.a. “the Sabot”

I’ve been watching Finding Dory with my kid lately, and part of the “making of” footage keeps jumping out at me.

In the movie, there’s this octopus named Hank. Septopus, technically. His character model was so onerous to work with, they lopped off a tentacle to make animating him doable. Still, with 4,000 separate controls he was incredibly challenging to work with.

At this point in the process, they’re well past sketches and renderings and animatics — those lower fidelity stages that help you vet a bunch of ideas quickly and cheaply. They already Got Real too. The character rig was built, technical details worked out, fundamental questions answered.

They’re in the final animation stage — 3D models in 3D environments. They could have soldiered on at the expense of the production schedule and budget. Instead, they did something really interesting — they went back to sketching.

By sketching out the complex movement of Hank’s tentacles on paper, they could nail down the perfect, fluid animation they were looking for in a fraction of the time. Once they were happy with the sequence, they’d animate in 3D to match. They got a better product in less time because they chose to value process principles instead of a process prescription.

The cure for a prescriptive process

The Finding Dory team made a better product faster by making decisions that prioritized speed and quality instead of sticking to a fixed process.

You might choose other things to value, but if you’re working in a commercial setting, focusing on the sweet spot between speed and quality should be at the top of your list. Turning around great work quickly is kind of a big deal for professional designers and artists after all.

If you value speed, start a project by figuring out what the biggest, most fundamental questions are. In Getting Real, this is called “epicenter design”:

Start from the core of the page and build outward

Epicenter design focuses on the true essence of the page — the epicenter — and then builds outward. This means that, at the start, you ignore the extremities: the navigation/tabs, footer, colors, sidebar, logo, etc. Instead, you start at the epicenter and design the most important piece of content first.

Whatever the page absolutely can’t live without is the epicenter. For example, if you’re designing a page that displays a blog post, the blog post itself is the epicenter. Not the categories in the sidebar, not the header at the top, not the comment form at the bottom, but the actual blog post unit. Without the blog post unit, the page isn’t a blog post.

Only when that unit is complete would you begin to think about the second most critical element on the page. Then after the second most critical element, you’d move on to the third, and so on. That’s epicenter design.

Epicenter design eschews the tradtional “let’s build the frame then drop the content in” model. In that process, the page shape is built, then the nav is included, then the marketing “stuff” is inserted, and then, finally, the core functionality, the actual purpose of the page, is poured in to whatever space remains. It’s a backwards process that takes what should be the top priority and saves it for the end.

Here’s an example of why this is crucial. I was working on a little side project iOS app that used a unique, possibly unworkable audio interface. If I didn’t value speed, I could have spent countless hours designing the myriad details that rested on the foundation of this one oddball idea. Design comes before code in the classic linear process, after all.

Instead, I started in code to figure out whether or not this idea was viable. It wasn’t! So I adjusted my plans, and saved myself an enormous amount of time and energy.

Once you know the questions that need answers first, ask yourself: “Which medium gives me the clearest answer to my questions in the least amount of time?” A venn diagram of ‘clearest answers’ and ‘fastest to make’.

In the case of my side project, the answer was code. For a page on Basecamp.com, the answer is often text or a rough sketch. For you, it might be something else entirely.

Knowing when to change gears

That gives you a place to start, but how do you know when it’s time to switch to a different medium? When you hit resistance.

Think about driving a car. You’re cruising down the highway — engine purring away like a contented kitten. But then you start driving up a hill. The gear you’re in was great for cruising, but not for hill climbing. In order to keep up your speed, you shift into a new gear.

Same thing here. But unlike cars, there’s no rock solid indicator that you’ve hit too much resistance in your medium of choice. Luckily, most designers and artists have a solid handle on when you need to switch to a medium that offers more fidelity. This is the part that lines up with the classic low fidelity → high fidelity linear process after all. You know you’re ready to move on from sketching when sketching stops giving you useful insight.

Once you’ve hit this point, figure out the next most important set of questions and ask yourself again: “which medium gives me the clearest answer to my questions in the least amount of time?”

The second case — shifting back to a lower fidelity — is tougher. Both because people are less practiced at it, and also because it’s tricky. Take working in code. You’re working at 100% fidelity, so there’s no limit to the medium’s ability to answer questions. But there is a limit to its ability to answer questions fast.

When you feel yourself not pursuing paths because it feels like too much work, that’s a really good sign that you need to back out. When things feel like they just aren’t clicking like they should, it’s time to reassess. Be mindful, and you’ll start to develop a feel for it.

Using a medium to your advantage

There’s a third case for switching to — or sticking with — a medium. This one doesn’t care about resistance, it only cares about a fundamental truth; process influences outcome. Just like drawing something with a pencil is going to look different than drawing it with a marker, designing in browser is going to produce an different outcome than designing in Sketch.

The more you understand how a medium affects your work — the kind of tool marks it leaves — the more you can use it to your advantage. Want your design to be expressive? Probably better to work with a visual tool like Sketch, Illustrator, or even gasp Photoshop. Want a minimal, lightweight design? Stick to designing in code.

Hopefully this gives you some insight into how you can use principles to guide your process on case-by-case without feeling like you’re constantly reinventing the wheel.

Think about your process and the kind of work that you do. Define the principles that are important to you, focus on the big stuff first, and keep questioning if the medium you’re working in is the right one for the moment.

Generalists, specifically.

2020-11-05T00:00:00Z

A generalist designer, axiomatically, is someone who doesn’t specialize in any particular area of design. They’re not UX designers, UI designers, content strategists, illustrators, product designers, copywriters, graphic designers, front-end developers, or animators, even though their work may touch every single one of those roles. The proverbial “jack of all trades, master of none”.

That’s part of the reason why the industry mantra for decades has been “SPECIALIZE!, SPECIALIZE!, SPECIALIZE! THE MORE SPECIALIZED THE BETTER! YOUR CAREER IS DOOMED OTHERWISE!”

I’ve spent years hand-wringing over this. Worrying that I was spreading myself too thin. Worrying that my love for all forms of designing and building and making and creating would make me irrelevant in an industry that’s charging headlong towards specialization.

But then I realized something; the industry… is wrong.

Well, two things actually; the industry is wrong, and generalists are, paradoxically, a kind of specialist. It just so happens that the specialty isn’t categorical, it’s situational. Generalists excel at helping smaller or newer companies leverage design faster, cheaper, and easier than an equivalent team of specialists. How?

Generalists live and breathe the Pareto principle (80% of the benefit comes from 20% of the effort). By focusing on 80-90% good, generalists can deliver work that that moves business goals forward in a tiny fraction of the time that it might otherwise take. Sometimes you actually need to get to 100% and hey, great time to call in a specialist. That last 20% is quite literally their expertise.
Generalists cut through organizational bloat like butter. Teams of specialists have to coordinate, confer, write specs, and/or have meetings at each handoff. That takes time. A lot of time. Oh, and let’s not forget the extra layers of people management you need to wrangle a larger staff. Generalists eliminate all of that because they’re doing it all themselves. It’s an order of magnitude more efficient.
The work of a generalist is seamless, by default. The product of one mind, one vision. With a team of specialists, everyone is focused on their own domain and it’s easy for the end product to feel like what it is; a bunch of disjointed parts glued together. High-functioning teams are great at avoiding this, but it takes work to really pull it off (and usually another specialist).
Generalists view work from a multitude of perspectives, where specialists tend to fall victim to Maslow’s hammer (if all you have is a hammer, everything looks like a nail). A specialist brand designer probably isn’t considering how their design explorations might or might not translate to efficient web assets, for instance. Generalists see the entire forest, and the work is better for it.

That’s all to say; most companies that aren’t Google or Apple-scale would be far better served by hiring generalists instead of specialists. If you’re starting a company, generalists are your best friend. If you’re trying to get more done without working longer hours, generalists are your jam. If you’re trying to stay lean, generalists are what’s cookin’.

The best part? Working as a generalist is satisfying. Variety is the spice of life, and working as a generalist is very, very spicy. The idea of a job that’s nothing but drawing boxes in Figma interspersed with meetings about the boxes you draw in Figma fills me with dread. Humans are hardwired for novelty. We wither when we emulate robots. Working as a generalist is the more human way to work.

Viva generalists.

P.S. I’m not the only one who’s realized all of this:

On brand

2022-03-09T00:00:00Z

Across the clients and companies I’ve worked with, more often than not I’ve had to sell the value of hard to measure stuff like branding and designing for emotion. Chances are good I’ll have to keep selling folks on this subject, so I thought it’d be handy to have a link I can send folks that outlines my thoughts. This link, specifically.

Let’s start at the very beginning and review the purpose branding plays in the context of a tech startup. Does it even matter? Can’t you just use off-the-shelf design systems or copy what everyone else is doing or do nothing at all? The short answer; sometimes, but not all the time, and usually not forever.

“The only problem with Microsoft is they just have no taste”
— Steve Jobs

You can look at early Microsoft or Google for examples of when brand identity (and more broadly “good design”) isn’t a vital strategic pillar. When you have a product that is category defining or wholly unique in the value it delivers, you can build an incredibly successful business without investing in branding or experience. At the time, the hardware-independent model offered by the Windows ecosystem was impossible to beat. It didn’t matter that Microsoft had no taste. They eventually invested in branding of course. But what made them start?

As novel technologies become commodity or you directly enter a competitive market, branding and experience design become increasingly valuable strategic levers. Slack is a classic example of a company that saw massive success in large part due to branding and experience design. Slack wasn’t a notable standout feature-wise compared to contemporaries like HipChat or Campfire when it entered the market, but it had a cool name, a fresh brand identity, a beautifully designed app, and an amazing onboarding experience. My team was using Hipchat when it launched, and we couldn’t switch fast enough. It felt like a breath of fresh air.

When you get branding right, it’s a multiplier on everything you do. It’s the salt that intensifies flavor, a wind at your back. Hiring is easier, customers are more satisfied, prospects more enthusiastic.

As to why that’s true, you have to remember that humans make decisions through a combination of conscious logical reasons and unconscious emotional reasons. Features, benefits, and value appeal to the logical self, whereas branding and “experience” focuses on the emotional self. As I described with Microsoft and Slack, you can compete on one or the other, but when you get both right, magic happens. For a deeper dive on this phenomenon, read on.

What constitutes a “good” brand identity?

Good brand identities are inherently contextual. Good for one company could be bad for another. For instance, the identity for Monster works for an energy drink, but it’d be disastrous for a mortuary. There are a few common “good” characteristics that apply to most businesses though:

A good brand identity inspires confidence. At minimum, a brand identity must immediately identify you as legitimate. A good brand identity takes that several steps further, instilling confidence that you can solve the problem potential customers have.
A good brand identity stands out. In 2022, it’s basically impossible to wholly unique, but it’s vitally important to not be blandly forgettable. If a customer is competitive shopping, do you want to be that one Zebra standing in the middle of a pack of identical zebras? Or do you want to be that one Zebra with pink stripes? Always the latter. This is where most tech companies go wrong. They think they have to “look like a tech company” and don the homogeneous “tech look”.
A good brand identity shines in the primary medium. For a tech company, that usually means websites and apps.
A good brand identity is consistent, but not monotonous. Evolutionarily speaking, humans are wired to respond to novelty. If you spot that tiger in the bushes, you live. If not, tiger snack. In music terms, you want a song with rise and fall, not a monotonous single tone.
A good brand identity should make you feel… something. Ideally a positive something.

A closing thought; consider that on any typical day there is no functional difference between a $20,000 Kia Rio and a $100,000 luxury car. They both get you from A to B safely. They both crawl through traffic at the same rate. What is it that people are paying 5x more for?

Fundamentals

2022-11-08T00:00:00Z

The pendulum swinging back from “recreate everything in [insert SPA framework]” to “multi-page apps are pretty good, actually” is a timely reminder that focusing your energy on mastering the fundamentals is usually a smart bet.

Early in my career I was more of a Flash person. In terms of creative expression, it felt like a breath of fresh air compared to compared to sliced up images and table hell. But then CSS Zen Garden came along and opened my eyes to a radically different way. Not just a different way of building websites via semantic markup and external stylesheets, but a different way of thinking about them. A unique, living medium with its own inherent character and beauty. I was hooked, and left Flash in the rearview mirror.

Roughly 20 years later, I can say with confidence that focusing on the fundamentals — markup, CSS, and vanilla javascript — was the right choice. All that Flash-specific knowledge that I spent countless hours accumulating? Useless. Meanwhile, my web standards knowledge has stayed consistently relevant, useful, and in-demand. Tools change, fundamentals don’t.

Extending 11ty’s page variable

2022-11-20T00:00:00Z

I’ve had my eye on Astro, so I thought I’d take it for a spin by re-building this here website. I stuck with 11ty in the end for a variety of reasons, but the experience inspired me to see if I could replicate a few Astro niceties in 11ty. Turns out yes, thanks to 11ty’s page variable.

single file templates, kind of

11ty’s new WebC format uses single file templates out of the box, but Liquid and Nunjucks require a little more creativity. My use case for single file templates is more about having an easy place to drop little bits of page-specific CSS vs. a full-blown asset pipeline. Totally doable by extending 11ty’s page variable.

Step one is creating a paired shortcode to the 11ty config. I like to keep my filters and shortcodes in separate files to keep things tidy:

const postcss = require('postcss');
const nesting = require('postcss-nesting');
const csso = require('postcss-csso');

module.exports = function style(content) {
  postcss([
    nesting,
    csso,
  ]).process(content, { from: 'undefined' }).then((result) => {
    this.page.style = result;
  });
  return '';
};

I’m using PostCSS for nesting syntax and minification, but you can skip that and return plain CSS if you want. Now we need to tell 11ty about our new shortcode:

module.exports = function(eleventyConfig) {
  const style = require("./_source/_utilities/style.js");
  eleventyConfig.addPairedShortcode('style', style);
};

Finally, add little conditional code in your layout file’s <head> element:

<head>
  {% if page.style %}
  <style>
    {{ page.style }}
  </style>
  {% endif %}
</head>

That’s it for plumbing. Here’s how you use it in a Liquid template:

<!-- front matter and template content -->
{% style %}
  .foo {
    position: absolute;
    top: 0;
  }
{% endstyle %}

Any CSS you write in the shortcode is added to a style tag in the head of the page. It’s a nice and simple way to add page-specific styles without bloating you main CSS bundle.

multiple slots

Another nice thing about Astro is the concept of multiple slots. Out of the box, 11ty only supports one content slot, which can made more complex layout needs hard to pull off without making markup concessions.

For instance, on this site I needed a way to include some markup outside of the main element where I’m rendering content. What to do? Once again, extending the 11ty supplied page variable with a paired shortcode is the answer:

module.exports = function setVar(content, name) {
  this.page[name] = content;
  return '';
};

Unlike our style shortcode, this variation allows for setting a variable name in order to support additional slots. Like with the style shortcode, we need to hook up our slot by adding a conditional where it’s going to be used:

{% if page.pattern %}
  {{ page.pattern }}
{% endif %}

I’m using pattern as the name since that’s what I’m using it for, but you can use whatever names make sense to you. Here’s how you use it in a Liquid template:

{% setVar 'pattern' %}
<random-pattern quantity="10" jitter="150"></random-pattern>
{% endsetVar %}

Worth noting here that Liquid.js does have a concept of multiple blocks but I couldn’t get it to work properly in my testing. Plus, this technique has the benefit of not wholesale changing how you do layout in your project.

Revisiting PJAX

2022-11-27T00:00:00Z

Personal sites are great venues for exploring those half-baked and high-contrast ideas that are illuminating, but impractical for commercial work. No funnels, no customers; just a blank canvas and the freedom to explore it.

Lately, the tension between functional attributes (performance, accessibility, DX) and experiential attributes has been the focus of my own exploration. On one side of the spectrum, you have bare HTML. Pure functionality (debatable!), a big zero experience-wise. Like a car stripped down to bare frame, this is “too far”. On the other side, you have pure js apps and sites. Rich, expressive, and capable, but complex and comparatively slow. Also “too far”. If these are both “too far”, what does “just right” look like? How far can you push on one without sacrificing the other? Is it even really a tradeoff? Can you have it all?

Most of my energy has been focused on pushing towards performance and simplicity, but this time around I thought I’d switch things up and focus on a marquee experiential features of SPA frameworks; app-like, animated page transitions. Frameworks and libraries are out. Too big, too complex, or both. So what’s left? Do-it-yourself PJAX.

PJAX as a technique isn’t remotely new, but as it turns out, modern javascript offerings like custom elements make it a heck of a lot easier to implement without help from a library. For example, one of the problems you have to solve with PJAX is that page events only fire on the first page visit, which causes all kinds of problems for scripts you might be running on various window events. Custom elements sidestep the problem completely thanks to baked-in lifecycle events like connectedCallback. They Just Work with the PJAX pattern, no extra code required.

Custom elements are a biggie, but the fetch API and host of other improvements all contribute to then end result of a lot less code. Here’s the final PJAX custom element I cooked up, that’s running on this website right now:

export default class PageTransition extends HTMLElement {
  async getPage(url) {
    try {
      const response = await fetch(url);
      const responseText = await response.text();
      const parser = new DOMParser();
      const doc = parser.parseFromString(responseText, 'text/html');
      window.history.pushState(null, null, url);
      this.transitionPage(doc);
    } catch (e) {
      window.location.href = url;
    }
  }

  transitionPage(doc) {
    const { head } = document;
    const newElements = doc.querySelectorAll('head > [data-swap]');
    const oldElements = document.querySelectorAll('head > [data-swap]');
    const newContent = doc.querySelector('page-transition').innerHTML;
    const containerStyles = getComputedStyle(this);
    const delay = parseFloat(containerStyles.transitionDuration.slice(0, -1));
    // transition out
    this.classList.add('transitioning');
    setTimeout(() => {
      // replace page elements
      this.innerHTML = newContent;
      oldElements.forEach((element) => element.remove());
      newElements.forEach((element) => head.appendChild(element));
      // transition in
      this.transitionable();
      window.scrollTo(0, 0);
      this.classList.remove('transitioning');
    }, delay * 1000);
  }

  transitionable() {
    // only act on relative urls
    const links = document.querySelectorAll('a[href^="/"]');
    links.forEach((link) => {
      if (link.getAttribute('listener') !== 'true') {
        link.setAttribute('listener', 'true');
        link.addEventListener('click', (e) => {
          if (!e.metaKey) {
            e.preventDefault();
            this.getPage(link.getAttribute('href'));
          }
        });
      }
    });
  }

  connectedCallback() {
    this.transitionable();
    // reload the page when history controls are used
    window.addEventListener('popstate', (event) => {
      window.location.reload();
    });
  }
}

window.customElements.define('page-transition', PageTransition);

56 lines of straightforward javascript that covers the basics and then some. It handles swapping all the <head> content that needs swapping and the exit portion of page transitions. The intro portion is handled by a separate, pre-existing custom element that handles scroll triggered animations of all types. This approach allows for more flexibility, and lets me skip handling back/forward controls without losing the entire transition.

Definitely a worthwhile experiment, and one that I’ll keep running for a while, but my big takeaway is that it’ll be a good day if and when the View Transition API makes all of this unnecessary.

Complexity creeps

2022-12-07T00:00:00Z

The thing about complexity is that the cost rarely seems obvious upfront. It usually starts as a reasonable desire, with a reasonable set of initial tradeoffs that make you think the benefit of taking on more complexity is worth the cost.

But then complexity does what complexity does, and creates entirely new problems you didn’t anticipate. So what do you do? Add even more complexity to solve that problem. And so on and so forth, each individual decision seeming perfectly reasonable and uncontroversial.

Hal’s attempt to change a lightbulb perfectly encapsulates how complexity creeps in. It happens so slowly and methodically that there’s no “before” anymore. However long things take, however much friction or maintenance or education something requires, that’s just normal. Meanwhile, you’re taking twice as long to get half as much done.

It’s so pernicious that the only sustainable solution is vigilance. Complexity is sus. Complexity is an iceberg. Complexity is a monkey’s paw.

Consistent with what?

2022-12-16T00:00:00Z

“Consistency” is a word you hear a lot in tech. Designers talk about it (do not play the “drink when you hear this word” game with this word at a design systems conference), developers talk about it, everyone! But when it comes to consistency, it’s important to recognize that consistency comes in different flavors.

Case in point; I was working on a piece of UI for a new feature, and after iterating on a few different expressions in both light and dark mode, I couldn’t reconcile the fact that the card looked “right” with a subtle drop shadow in light mode, but looked “right” with a subtle edge highlight in dark mode. My logic brain was screaming. “Inconsistent!” “Bad!”

But then it hit me; my faithful and trusty gut brain was focused on the fact that this inconsistent implementation is actually entirely consistent with the laws of physics, and how light behaves in the real world. If you shine a light down on a glossy white object that’s sitting on a white surface, you’re going to see shadow. Highlights are there, but they’re blown out because everything is white on white. If you use a black object on black surface, the shadow is very difficult to see but now the highlights stand out. Inconsistent from an implementation perspective, perfectly consistent from an “adheres to the laws of nature” perspective.

Another case where this is true is “mathematical centering” vs. “optical centering”. Logical-brain loves mathematical centering, and derides things like “magic numbers”. But take a look at this humble play button comparison, with the triangle mathematically centered on the left, and optically centered on the right:

You might be thinking to yourself right now, “there is no way that the option on the left is centered”, and you would be wrong. There is exactly as much space on the left side of the triangle as the right. But there’s also no question that the “perceptually consistent” version on the right looks “correct” and the “mathematically consistent” version doesn’t. Consistency is all well and good. Just make sure you’re picking the right kind.

Step into the light (DOM)

2022-12-19T00:00:00Z

For a long time I didn’t know what to do with web components. There wasn’t a lot of writing around them outside of the spec, all the stuff around shadow DOM and templates made it feel inaccessible, and I just didn’t see a compelling reason to bother with any of it (something something PWAs).

That changed the day @javan clued me in to the fact that it is totally OK, and often ideal, to just use the custom element part of the spec. No shadow DOM, no templates, just the regular old DOM, which we now get to call the much cooler sounding “light DOM”.

Why would you want to do such a thing?

Custom elements have the very cool ability manage themselves via connectedCallback and disconnectedCallback. These are the unsung heroes of the spec; the things that make web components the can-do workhorses that they are. The second you step out of a strictly MPA scenario, these are very, very handy.
Progressive enhancement is straightforward. Any markup you add inside your custom element is just… there, javascript or no. Wrap standard interactive elements like details, textarea, input, etc in custom elements that enhances them, and you’ve got yourself a solid progressive enhancement story.
Custom elements enforce good javascript patterns. This one took me a while to spot, but it’s the thing that’s made custom elements the default way I write vanilla javascript these days (take a peek under the hood for examples). Vanilla javascript always felt spaghetti-ish in my clumsy hands, but there’s only one way to write custom elements. There’s no making a custom element without writing it as a class. For me, it’s meant an overall improvement in code quality.

Here’s an example of a progressively enhanced details element called small-details that makes a details element expand into what looks like an unordered list with header once the viewport is wide enough:

/* ----------------------------------------------------------------------------
details element that defaults to closed @small and open @medium+
---------------------------------------------------------------------------- */

export default class SmallDetails extends HTMLElement {
  listen() {
    this.mediaQuery.addEventListener('change', (e) => {
      this.update(e.matches);
    });
  }

  update(matches) {
    if (matches) {
      this.details.open = false;
      this.summary.tabIndex = 0;
    } else {
      this.details.open = true;
      this.summary.tabIndex = -1;
    }
  }

  connectedCallback() {
    this.details = this.querySelector('details');
    this.summary = this.querySelector('summary');
    this.mediaQuery = window.matchMedia('(max-width: 49.999em)');
    this.update(this.mediaQuery.matches);
    this.listen();
  }
}

window.customElements.define('small-details', SmallDetails);

And here’s how it gets used:

<small-details>
  <details>
    <summary>Only interactive @small</summary>
    <ul>
      <li><a href="/link-to-page/">a page</a></li>
      <li><a href="/another-page/">another page</a></li>
    </ul>
  </details>
</small-details>

Nothing fancy or complicated. Just clear, simple, and durable code, and a great progressive enhancement story. Custom elements are good.

“Craft at scale” is a white whale

2023-03-29T00:00:00Z

Designers and product-folk like to think of ourselves as craftspeople. We care about making things great. Is it possible to do it at scale? Shot and chaser:

The Cost of Craft - Longtime Meta designer George Kedenburg III did us all a favor and exhaustively documented the challenges of delivering “great” at scale. It’s well worth your time.
Big Tech’s big downgrade - in this Business Insider piece, Ed Zitron details how and why the largest tech companies — like Meta — are actively making their products worse for users.

George nails the problems, and in credit to his fortitude and optimism, leaves you with the idea that craft at scale is possible. I’m less optimistic. If you look at the available evidence, “craft at scale” is mutually exclusive with the kind of rapid and unending growth that’s the baseline expectation for traditional startups and public tech companies.

We’d say that’s obvious in other industries. Budweiser isn’t craft beer. IKEA isn’t heirloom-quality furniture. But we tend to treat software as immune to the typical relationship between quality and quantity. It’s software! It can infinitely replicate!

There’s some truth to that idea. Moving from making 100 sandwiches a day to 100,000 requires a fundamental shift in tools and process that inevitably leads to quality loss. Meanwhile, an indie dev can ship the same software to 100 or 100,000 people without doing anything different. As George points out, the tension between craft and scale in tech has much more to do with the size of the product you’re building and the speed at which you’re trying to build it.

Funded startups and public tech companies need to keep the high-growth engine running, which inevitably leads progressively larger and more complex product offerings that attempt to attract more and more users. No single team can deliver on that, which leads directly to disjointed and/or competing teams, and a steady erosion of vision that’s backfilled by process. This is the inflection point where you’re now “manufacturing” software.

Growing the surface area of the product only takes you so far though. You eventually hit some kind of saturation point, and what follows is the kind of shitification Ed outlines. The focus shifts from quality to “value extraction”, which leads to higher prices, worse customer service, manipulative or deceptive products, monopoly lock-in, etc.

If you’re a designer at a large tech company, you cannot and will not overcome this. If you look at Apple — arguably one of the few companies that’s been able deliver craft at scale for any amount of time — they did so because Steve Jobs was a true believer who did more that espouse belief; he hired, fired, inspired and cajoled his way to an org built around delivering on it. It has to come from the very top for craft at scale to be a remote possibility.

Jesper Kouthoofd of Teenage Engineering recognizes that craft and rapid, unending growth are fundamentally at odds:

We only want to make great products and when you don’t focus only on making money and have reached a certain level, everything becomes about quality. Right now, there is a certain cultural fascination with fast growth, IPOs and so on, but I want to go slow, really slow and think long-term. It takes time to do good things. You see, this cultural phenomenon of speed and growth at all costs is displayed in every startup, they all look the same, it’s like fast food: it looks good, its taste it’s consistent but then you feel horrible afterwards.

If pursuit of craft is what drives you, you need to find smaller, slower waters.

My framework for defining if something is “well crafted” or “a product of craft”:

Well made. Craft is the product of high quality ingredients, approach, and process.
Well considered. When something is imbued with craft, it’s obvious to the end user that every detail was thought through. The care and attention shines through.
Beneficial. Well crafted software/tools/food/clothing/buildings give more than they take. They solve problems, meet needs, grant abilities, delight senses and satisfy emotions. Time and energy invested is rewarded in multiples.
Opinionated. Craft has perspective. It thinks things should be just so. It’s heavily influenced by a vision that exists outside the tactical pursuit of mass appeal.

Building vs. optimizing

2023-05-19T00:00:00Z

Software — and software companies — break down into two distinct modes:

Build mode - you’re in blue sky territory, creating something where nothing existing before, trying to find product market fit.
Optimize mode - you have an existing product, and you’re iterating on it to grow your user base and increase revenue.

It’s an incredibly important distinction to recognize, for a few reasons. One is professional. In my experience, people strongly prefer working in one mode or the other. If you know which and pick jobs accordingly, your career will be better for it. Me? Build mode. The times in my career when I’ve been in optimization roles correspond 1:1 with professional low points.

The other reason is that techniques and practices aren’t one-size-fits-all. The trouble is, discourse is dominated by people working at larger companies that operate in the optimization mode. That’s led to the general idea that the best practices for optimization mode are the One True Way to Do Things.

Why is that a problem? Bringing optimization mode approaches to build mode is like bringing a knife to a gun fight; it puts you at a fundamental disadvantage, and the the likely outcomes range from bad to worse.

One example is the bit of conventional wisdom that dictates that you should have a measurable KPI for every project, every piece of design, every feature that you ship. Side-stepping the fact that you can’t measure most design outcomes holistically, this idea makes sense when you’re optimizing, since it mostly ensures that you don’t move backwards. It trades speed for reduced risk; pretty good calculus for mature companies.

The same approach applied to build mode leads to rudderless products, feature factories, bad decisions made on bad data, and a major blow to your ability to move quickly. Companies at Facebook can run A/B tests and have statistically relevant results the next day. At an early startup that day turns into weeks and months. That’s a kiss of death in a competitive space. In build mode, there’s simply no substitute for taste, vision, deep knowledge of the problem space, and direct user feedback.

Design system are another example. A strong focus on creating and maintaining a comprehensive design system makes perfect sense for a large, mature company. Design system are inherently a scale concern after all. But if your first move as a founding designer at a new startup is to establish a comprehensive design system, you’ve chosen unwisely. Priority one at an early startup is finding product-market fit. If you don’t have that, nothing else matters.

Pragmatically, you also don’t know what you don’t know. Building first lets you see where patterns form, then extract those patterns into a focused, just-enough design system. The end result is business that finds its footing faster, and an app that doesn’t feel like a bunch of LEGO parts stuck together.

Staying mindful of the mode you like and the mode you’re in makes work better.

View transitions + Quicklink

2023-05-28T00:00:00Z

A great thing about the multi-page view transitions spec (read this post from Dave Rupert for an intro) is that it’s pure progressive enhancement. If a browser doesn’t support it, things work the way they’ve worked since Mosaic.

One caveat is that they don’t always feel instant. It makes sense; you have to render what’s on the other side of a link if you want to smoothly transition between old and new. The lag between clicking and the transition starting is the time it takes your server to load the subsequent page. If you want to fix that, you’ve got two options:

Make your site or app faster. There’s a long list of reasons why fast is good. View transitions are another.
Use Quicklink. It pre-fetches pages based on links that are in your viewport, network conditions permitting.

These aren’t mutually exclusive options. This here website is lightweight and statically rendered (fast), and adding Quicklink turned fast into instant.

The great thing about Quicklink is that it’s also progressive enhancement. It’s about 1KB of non-blocking javascript that builds on top of how the platform works, instead of attempting to wholesale replace it like client-side routing alternatives. There’s no high-stakes failure mode where users can’t click a link. There’s no strange behavior with history or scroll position. Along with view transitions, you get most of the upside, none of the downside.

The “enhance instead of replace” approach pays in other ways too. Quicklink predates view transitions by years. It didn’t have to be updated to support the new spec, because building for the platform is building for the future.

Taming Tailwind

2023-09-19T00:00:00Z

I wasn’t a Tailwind fan. Between the heavy-handed approach, the needlessly antagonistic marketing, and a community prone to dog-piling valid criticism, I didn’t see much to be a fan of. But life comes at you fast, and I found myself starting a job at a company that was wrapping up a migration to – you guessed it – Tailwind.

So I set my hangups and pre-conceived notions aside, and did things the Tailwind way. For a solid year, I used it almost daily to design and build UI in a production Rails app. I know Tailwind, well and truly. Still not a fan.

Don’t get me wrong, there absolutely are bright spots. The structure and syntax of bread-and-butter utilities like margin, padding, and flex are clear, concise, and easy to work with, the color opacity system is emulation-worthy, and the documentation is excellent (praise be the type-CSS-to-get-Tailwind-CSS box).

Those bright spots just aren’t bright enough to distract from a weakly-held prior turned full-blown conviction; utility-only CSS doesn’t work.

The reality of utility CSS is that like 10% of properties – margin, padding, type sizing, color, showing / hiding things in different contexts – are doing 90% of the work. What that means in practice; a component CSS architecture with a narrow set of utilities to cover that 10% delivers almost all of the value that utility CSS can possibly deliver.

And the value is real. Utilities keep CSS small, components flexible, and architecture simple. But in a very cautionary tale kind of way, Tailwind proves that there really can be too much of a good thing. In order to grab that last 10% of value that utility CSS can potentially deliver, Tailwind has to do three things:

Create utilities to cover all CSS properties and their infinite permutations.
Create new, stripped down mechanisms to replace CSS behavior that’s too complex to be modeled as utilities.
Create escape hatches to vanilla CSS, because #1 is impossible and #2 means there are things CSS can do that Tailwind can’t.

The end result is a framework that makes the easy things easier, the hard things harder, and invents problems where none need exist.

Anything with multiple states (read; anything interactive) is a soup of unstructured, repetitious state prefixes. Support dark mode? Get used to typing dark:, because you’re going to write it in front every color declaration in every part of every component.

Paradigm-shifting custom properties? Nope. Calc()? Only in arbitrary values, which really is equivalent to writing inline styles. Grid? Nerfed. Complex relationship selectors? Sorry, you get the ~~pain stick~~ group system instead.

It was this last one that broke me. I was working on some goal UI updates to goals in our app, which uses <details> elements that can nest into moderately complex parent/child structures. After an hour of struggling to get custom open/closed markers to toggle in accordance with their containing parent – a basic direct child selector – I was struck by a revelation.

I could just write CSS.

There’s no award for writing “pure Tailwind”. There are no Tailwind Cops that will come to your house and arrest you for holding Tailwind the way its authors didn’t intend. It’s open source, babe. And luckily, door #3 – the escape hatch – is surprisingly pleasant.

How to make CSS and Tailwind work together

The gist; use Tailwind’s theme function to map values from Tailwind to component-level custom properties. Here’s a simple, contrived example:

.button {
  --padding theme(padding.3);
  --color: theme(colors.gray.900);
  --background-color: theme(colors.white);

  [data-theme="dark"] & {
    --color: theme(colors.white);
    --background-color: theme(colors.gray.800 / 30%);
  }

  padding: var(--padding);
  color: var(--color);
  background-color: var(--background-color);
}

In essence, you’re reducing Tailwind’s job down to “token manager”, and unlocking the full power of modern CSS by doing so. It means you can use Tailwind utilities for the simple stuff, component CSS for the more complex stuff, and have it all work off of the same set of values. It reduces Tailwind lock-in too. Your spiciest CSS starts 99% migrated; point at :root properties instead of Tailwind values and call it a day.

Values you type within the theme function tab complete, which coupled with the more intuitive naming structure, makes for a downright pleasant authoring experience. I wish my root custom props could auto-complete like that.

“What about @apply?” you might be asking. @apply manages to give you all the cons of component CSS and and all the cons of Tailwind in one package. Even the author doesn’t want you to use @apply.

Media queries

If you want to use Tailwind’s breakpoints in CSS, there’s a function for that too. It goes a little something like this:

.button {
  --font-size: theme(fontSize.sm);

   @media screen(lg) {
    --font-size: theme(fontSize.md);
  }

  font-size: var(--font-size);
}

Color

I’ve spent a decent amount of time thinking about and implementing approaches for making multi-theme websites as simple as single color websites (see: theme picker on this very website). Initial values defined as custom properties are key, lest you consign yourself to the aforementioned type-dark-before-everything dungeon.

Tailwind doesn’t work that way out of the box, but it’s straightforward to make it so. Start by adding a root css file, and defining custom properties for your colors. You want to make sure that you only provide the raw values here; opacity modifiers won’t work otherwise.

:root {
  --color-asphalt-50: 230deg 10% 98%;
  --color-asphalt-100: 230deg 10% 96%;
  /* more colors... */
}

Next, customize your Tailwind theme colors, and map your custom properties to new Tailwind colors.

module.exports = {
  theme: {
    colors: {
      neutral: {
        50: "hsl(var(--color-asphalt-50) / <alpha-value>)",
        100: "hsl(var(--color-asphalt-100) / <alpha-value>)",
      },
    },
  },
}

You can work with colors using the normal Tailwind color syntax, and you can do “cool color stuff” with custom props in your component CSS. Win-win.

Behavior wrappers

2023-11-28T00:00:00Z

Something that’s been on my mind lately is the value of not encapsulating html, css, and javascript into singular components. Sometimes – if you value keeping things simple – teasing apart behavior and presentation into composable pieces makes more sense.

Enter custom elements. As it happens, they’re the perfect vehicle for creating encapsulated behavior that you can use in all sorts of different contexts, and have it Just Work™, with progressive enhancement as the default behavior.

Here’s a relevant example from a project I’m working on. This is a custom element called <jitter-bug>. It’s job? Make a mess. Here’s how you use it:

<jitter-bug jitter="20" scale="10" rotation="15">
  <p>this is</p>
  <p>completely arbitrary</p>
  <p>markup</p>
</jitter-bug>

Stick some markup inside, and twiddle with a few knobs to tune the effect. It’s not concerned at all with what’s inside in terms of markup or styling. It’s only job is to mess things up. This’d be hard/weird as a kitchen-sink component, but sticking to behavior-only keeps things simple:

export default class JitterBug extends HTMLElement {
  static get observedAttributes() {
    return ['scale', 'jitter', 'rotation'];
  }

  get scale() {
    return this.hasAttribute('scale') ? this.getAttribute('scale') : '0';
  }

  get jitter() {
    return this.hasAttribute('jitter') ? this.getAttribute('jitter') : '0';
  }

  get rotation() {
    return this.hasAttribute('rotation') ? this.getAttribute('rotation') : '0';
  }

  static random(min, max) {
    const minimum = Math.ceil(min);
    const maximum = Math.floor(max);
    return Math.floor(Math.random() * (maximum - minimum + 1)) + minimum;
  }

  makeItMessy() {
    this.targetElements.forEach((element) => {
      const el = element;
      const rS = this.constructor.random(this.scale / 2, this.scale * 1.5);
      const rX = this.constructor.random(this.jitter * -1, this.jitter);
      const rY = this.constructor.random((this.jitter / 2) * -1, this.jitter / 2);
      const rR = this.constructor.random(this.rotation * -1, this.rotation);

      if (this.jitter > 0) {
        el.style.translate = `${rX}rem ${rY}rem`;
      }

      if (this.scale > 0) {
        el.style.scale = `${rS}%`;
      }

      if (this.rotation > 0) {
        el.style.rotate = `${rR}deg`;
      }
    });
  }

  connectedCallback() {
    this.targetElements = this.querySelectorAll(':scope > *');
    this.makeItMessy();
  }
}

window.customElements.define('jitter-bug', JitterBug);

I use this same basic approach for all sorts of things. <details> augmentations, content overflows, animation triggers, etc. Little behavior wrappers to use any place, any time.

“AI Inside”

2024-02-04T00:00:00Z

Tech companies are scrambling to stake their claims in the AI gold rush, and — on top of the legal and ethical woes they’re leaving in their wake — a lot of them are shipping surprisingly bad product. The tell? If the name focuses on “✨AI”, brace yourself.

Remember Intel’s iconic “Intel Inside” campaign? Effectiveness aside, it was a marketing campaign disconnected from solving user problems. Having “Intel inside” didn’t make it easier to use a computer or unlock new use cases. Instead, the campaign rested on the premise that “Intel Inside” was something consumers found inherently desirable. It’s a similar story with “✨ (product-name-here) AI” and “✨ AI co-pilot” products. They think consumers want “AI” because it helps them do…. stuff, and so they ship software that let them do… that stuff. Raw technology brimming with whatever use case you can think of! (1)(2)(3)(4)

The hope is — sticking with the gold rush metaphor — that if they send enough miners (users) down every mine shaft, they’ll eventually, inevitably, discover gold in them there hills. To some degree, that’s tech. There’s always a discovery phase with new technology, purpose-driven or otherwise. What makes this era of exploration unique?

This stuff is weapons-grade plutonium, and instead of running long careful betas and designing around potential harms, companies are yeeting AI features into production without a second thought.
I really mean “without a second thought”. Companies that ought to know better are shipping product that is gimmicky, half-functional, and/or outright destructive to the core product and then loudly, aggressively promoting it in-app and everywhere else.

Examples in the wild are myriad, but Notion and Adobe will do. I use products from both companies daily, and conveniently for me they offer examples of the bad way and some better ways to integrate large language models into commercial applications.

Bad

Notion’s value proposition for groups is “external hive brain”. Instead of knowledge being partitioned away in the heads of various mortal humans, Notion puts all that information into a single organized space where everyone has access to all that knowledge.

It follows then, that you’d want your external hive brain to be filled with high quality content. And here’s where we run into trouble. As of February 2024, Notion wants AI to be a major — perhaps default — way content gets created and edited.

When you create a new document, there are two options; “blank page”, and “start writing with AI…”.
If you pick “blank page”, you’re met with a “press ‘space’ for AI…” prompt. This same message appears whenever you place your cursor on a blank line.
When you select text, the first button in the floating toolbar is “✨ Ask AI”.
At one point last week, I had two different in-app pop-ups for two different AI features, one of which couldn’t be dismissed without viewing the underlying promo.

Notion really wants you to use AI.

But why would any company want an external hive brain filled with content they can’t trust? That gives you no audit trail to determine reliability? That has extra, value-free filler intentionally stuffed in? None of this is exaggeration; Notion prefaces generative AI with a “AI responses can be inaccurate or misleading” disclaimer, includes a “make it longer” tool, offers no sourcing for text it generates, and no UI for indicating whether or not a document includes generated content. These trust & quality undermining features combined with heavy emphasis in the interface work together to directly undermine Notion’s core value proposition. It’s bad product.

The lesson here; general purpose AI isn’t one-size-fits-all. Notion has strong uses cases in tone change, summarization, and translation. The problem stems from generative tools.

Adobe Illustrator is a more straightforward example of clumsy execution and marketing exuberance. When you select multiple elements, two out of three primary actions in the contextual toolbar are for AI features; one for “✨Generate”, and one for “Recolor”. Recolor is a useful feature (note again the correlation between a name that reflects a defined use case and quality / utility), and Generate… is not. To be fair, this isn’t a case of “add (beta) to the end to cover our asses”, it really is beta software. The prompting is shallow, the results aren’t predictable, and the output is akin to what you’d get from a raster-to-vector conversion (read; not great).

Normally that’d be fine, but turning a contextual action bar — something that should include the most common actions — into an advertising surface for tools that aren’t fully cooked and aren’t ready for professional use isn’t. It undermines Illustrator utility, and Adobe’s credibility as a reliable vendor of professional tools. It’s bad product.

Better

Notion Q&A is their second attempt at integrating AI, and it shows. One again, the name tells the story. Where before we had general purpose “do AI… stuff”, now we have a specific use case; ask questions and get answers from across all of your content. The critical difference here is that any generation is backed by links to the content it was generated from. No crossing fingers that the summary is accurate. Just dig in.

And unlike their general purpose AI, Q&A improves Notion’s value proposition for larger accounts by turning “the more you add, the harder it is to find things” into “the more you add, the richer your dataset is”. It’s good product.

A subset of Photoshop’s Generative Fill, Generative Expand strikes a similar note. In contrast to general purpose pure-prompt image generators, Generative expand solves a specific, painful problem; you don’t have enough image for what you’re trying to do. It’s baked directly into the crop tool; expand the crop larger than your current image, note what the extended scene should include, press enter. Simple. Style is determined by the source photo, which makes for more consistent output, and a tool that’s useful in a professional workflow. It’s good product.

Best

What makes for an “ideal” AI product? Where do things go from here? Notion Q&A and Generative Expand hint at the answer:

They focus on augmenting, improving, and/or manipulating original human input, not replacing it. First wave products like ChatGPT and Midjourney are androids; the best tools will make cyborgs.
They move past pure prompt interfaces and solve concrete problems.

In other words, the arc of AI tools will probably follow a similar arc as operating systems; from command line to GUI-centric. You can already see this happening with products like Perplexity, that solve a lot of the problems inherent in ChatGPT’s approach by wrapping a lot more UI around the inputs and outputs.

Consider the case of image generation, where first generation tools suffer from a fatal flaw; they pack style and content into the same interface (a single prompt). That leads to a large amount of unpredictability, which makes them unsuitable for most professional use cases (assuming you can get past the “is this legally safe to use?” issue in the first place).

What makes Generative Expand more useful is that it separates out content and presentation. Imagine defining a set of “brand styles” that include a high degree of control and specificity, that you can then apply at will to to a multi-modal input that describes the content (text, reference image, doodle, all of the above). Massively more predictable, massively more powerful.

This demo of generating architectural renderings in realtime from a GUI give a hint at how much unexplored opportunity there is. Intentional interfaces, solving real problems, with “✨AI” fading back to an implementation detail.

The inhuman computer

2024-02-25T00:00:00Z

The Vision Pro has arrived. With it, came a splashy Vanity Fair piece featuring Tim Cook reclining at his desk, stoically indulging in some spatial computing. The moment I saw the shot, I was reminded of the iconic photo of early Apple designer Susan Kare, also reclining at a desk, with a smile on her face and a Mac perched behind her. I posted about it, because I thought it was an interesting juxtaposition of two points in Apple’s history.

The more I read about the Vision Pro, the more my mind kept coming back to those two photos. Casey Niestat’s brilliant review illustrates why. Here he was, sitting in the middle of New York City in the middle of the day, surrounded by people but somehow also alone; wrapped in a personal bubble of technology.

Now, you might take Casey’s video as tongue in cheek. Apple clearly doesn’t intend this generation of the Vision Pro to be used as a walking around device. But if you look at any of their marketing videos, their vision for how it should be used isn’t fundamentally different. People playing with their kids, talking with friends, living their lives, all funneled through the Vision Pro. Apple’s vision for the future of computing, at a time when people feel more disconnected then ever, is to disconnect people even more by turing real life into a digital, Apple controlled experience. It’s a vision that is fundamentally inhuman.

It’s not just the vision; thw same philosophy seems to have saturated into every pore of the device. All the marketing videos share an intentionally bland art direction, with “homes” ripped out of Dwell and characters that resemble department store mannequins more so than living, breathing people. And then there are the avatars. My immediate reaction on seeing them was “Steve Jobs would NEVER”, quickly followed by a recall of Hayao Miyazaki’s infamous reaction to a demo of an AI-created character:

I am utterly disgusted… I strongly feel that this is an insult to life itself.

At every turn, the Vision Pro seeks to remind you that it wasn’t designed with actual humans in mind. Ed Zitron’s scathing review offers an exhaustive list of user hostilities, from a flawed interface model, to major bugs affecting fundamental UI tasks, to a design that requires an individually sized “light seal” to function properly. Even video viewing – one of the more successful use cases according to most reviews – suffers from chronic inhumanity. It’s not uncommon for movies to bring viewers to tears, but crying is simply something you can’t do while using the Vision Pro.

Which brings me back to those two photos. I don’t see the same scene captured decades apart, I see two fundamentally different philosophies, and two fundamentally different versions of Apple.

The Mac was infused with creative spirit from the start; both in expression and intent. It was a tool to empower creativity, empower people in their personal and professional lives. The photo of Susan Kare tells that story. Carefree, feet on desk, a wall of book and notes behind her, and yes, a Mac.

The Vision Pro however represents an inversion of the Mac’s vision of a computer as a tool that empowers and enhances human expression. Instead, like a cell turned cancerous, the technology is now the point, with humans serving to give it life (money) and purpose (more money). The photo of Tim Cook tells that story too. Drab, lifeless, art unhung, Vision Pro at center stage.

Apple isn’t alone here. This tail-wags-dog approach underpins the AI space at large, like it did with “web 3” and blockchain before it. If anything, it’s the defining characteristic of modern big tech. These are the richest companies on the planet, but they want more, and they’re desperate to find or force the next big thing in order to make it happen.

In the spirit of the Bechdel test, I’d like to propose the “Can you cry while using it?” test as a means for assessing whether or not flesh and blood humans were centered in the making of a given piece of technology.
On the hardware itself; I’m a longtime owner of an Occulus Rift, which uses a large, power hungry computer and multiple hardwired sensors placed around the room to track you. The fact that Apple has packed all of that into a headset – with major improvements to things like screen resolution – is a technical feat.
You can’t cry in any other current-gen “goggle” headsets either, but no other system is seriously marketed as anything other than game-playing devices.
The Frame glasses from Brilliant Labs seem much more Apple-like than the Vision Pro, and much more human-centric in approach. It’s a mystery to me why Apple – given their experience with Earpods, Watch, and Siri – decided not to pursue this direction.

Chasing color

2024-10-01T00:00:00Z

I’m a fan of side-quests; professional tangents that fuel your interest, sharpen your craft, and pay long-term dividends towards whatever your main quest is. I tend to have a few running at any point; some might last a few weeks, some off and on for years.

One of the latter is designing CSS color systems. It’s stuck around for a few reasons. Color is a powerful tool in the design toolkit, and designing a maintainable, flexible, malleable, adaptable color systems is hard (read; “fun to try and solve”). I also like like to keep things grounded in practical application, which means I’ve mostly pursued this side-quest in the context of websites I’m actively designing and building. In this case, that means my personal site, the website for Steady, and the latest iteration of my website starter, Grease. We’ll get to those in a moment. First, definitions.

Defining the ideal

What does an ideal CSS color system look like? My answer to this question has evolved along the way, but here’s what I think, today:

Composable, cascading themes - You should be able to set different themes at the page-level, section-level, and component-level, and have them cascade down until a different theme is applied.
Light & dark mode for all themes - Color themes shouldn’t be in addition to light and dark mode, every theme includes light and dark mode support.
Expressive - It should be easy to change opacity, use tints and shades, etc. within the context of your system. No having to go off system just because you need to add transparency.
Micromanagement-free - You should never even have to think about working with specific hues at the component level. In other words, adding a new theme shouldn’t mean touching every component.
Small set of properties - You should be able to worth with a small set of properties that you can further modify vs. maintaining an extensive list of semantic colors. Easier to work with, and easier to make new themes.
Good DX - It should feel good to work with. Flexible, straightforward, reads intuitively, forgiving, consistent, etc.

Adventure 1: “Can you theme grungy graphics?”

The design for the current iteration of this website was heavily influenced by a desire juxtapose modern minimalism against 90’s era grungy textures, and a desire to make color completely mutable.

For the graphics side of things, I used an approach of applying different SVG noise filters to text and CSS shapes. That meant I could grunge up anything and animate it without having to bake a bunch of different assets. And of course it meant everything could have color applied by CSS.

The color system was simple. Map your theme colors to a narrow set of semantic variables, and apply those variables to elements and components.

:root {
  /* colors */
  --color-white: 0deg 0% 85%;
  --color-black: 0deg 0% 10%;
  --color-yellow: 58deg 100% 50%;
  --color-gold: 51deg 100% 50%;

  /* semantic colors */
  --color-text: var(--color-black);
  --color-sheet: var(--color-white);
  --color-link: var(--color-text);
  --color-accent: var(--color-yellow);
}

a {
  color: hsl(var(--color-text));

  &:hover {
    text-decoration-color: hsl(var(--color-accent) / 75%);
  }
}

Light and dark mode are separate themes, along with a core set of designed themes and a “random” option, all keyed off a data attribute applied to the HTML element. Here’s the dark theme:

:root[theme="dark"] {
  --font-weight: 300;
  --color-text: var(--color-white);
  --color-sheet: var(--color-black);
  --color-link: var(--color-gold);
  --color-accent: var(--color-gold);
}

A little bit of javascript early in the page head works to apply themes, and prevent the dreaded FART (Flash of inAccurate coloR Theme):

<script>
  const theme = localStorage.getItem('theme') || 'system';
  document.documentElement.setAttribute('theme', theme);
  if (theme === "random") {
    document.documentElement.style.setProperty('--color-random-text', localStorage.getItem('color-text'));
    document.documentElement.style.setProperty('--color-random-sheet', localStorage.getItem('color-sheet'));      
  }
</script>

Pros of this approach

It’s dead simple. There’s only a few semantic colors, so it’s easy to work with at the component-level, and trivially easy to add new themes.

Cons of this approach

It’s dead simple. 3 colors, with no tints or shades works with the design direction of the site, but it’s too restrictive for general use.
Separate light and dark themes. Light and dark are independent themes, just like every color theme. In other words, you lose light/dark control once you switch to a color theme.
Incomplete color definitions. This system uses a pretty common approach of only assigning the values of a color to a variable, and using a complete color definition in components so that you can adjust opacity if need be. In practice I’ve found that decomposing like this introduces more cognitive friction than I’d like. “Can I use the variable here, or do I need to wrap it?” is a question I keep having to ask myself.

Adventure 2: “Can you make color composable?”

For steady.space, I wanted to see if I could address the “too restrictive” problem while keeping the good parts. I had a secondary goal here; I wanted to make standing up and designing new pages very fast and very easy.

So I took the core of the last approach, and broke down the “one theme per page” model. Now, every page would be composed of “micro-themes” that cascade down until a new theme is applied. To meet my secondary goal, I married it to a set of color utilities that let me quickly and easily compose expressive color on every page without touching CSS.

Themes are set up pretty much the same as before:

.theme-dark {
  --color-text: var(--color-asphalt-0);
  --color-accent: var(--color-ultramarine-400);
  --color-sheet: var(--color-asphalt-900);
  --color-pattern: var(--color-asphalt-800);
}

.theme-grape-aqua {
  --color-text: var(--color-grape-600);
  --color-accent: var(--color-grape-600);
  --color-pattern: var(--color-aqua-400);
  --color-sheet: var(--color-aqua-300);
}

But instead of a single theme applied to the HTML element, you use them like so:

<main>
  <section class="theme-dark">
    <h2 class="color --text --use-accent">alpha</h2>
    <p>bravo</p>
  </section>
  <section class="theme-light">
    <ul>
      <li class="card theme-ultra">charlie</li>
      <li class="card theme-rhubarb">delta</li>
    </ul>
  </section>
</main>

If you’re wondering what’s happening with that h2, it’s a little theme re-mapper:

.color {
  &.--text { --color-text: var(--property); }
  &.--sheet { --color-sheet: var(--property); }
  &.--accent { --color-accent: var(--property); }
  &.--pattern { --color-pattern: var(--property); }

  &.--use-sheet { --property: var(--color-sheet); }
  &.--use-text { --property: var(--color-text); }
  &.--use-accent { --property: var(--color-accent); }
  &.--use-pattern { --property: var(--color-pattern); }
}

It gives you one more level of flexibility without having to dip into CSS, and splitting it up into two properties means I didn’t have to make a utility class for every possible combination.

Pros of this approach

It’s still very simple.
It allows for very expressive per-page color and ultra-fast composition.
It’s easy to work with, and super low maintenance. You can have 1000 unique color compositions across pages without adding a single extra line of CSS.

Cons of this approach

There’s no light/dark mode support at all.
There’s still that slightly annoying “decomposed color” problem.
It’s still somewhat restrictive within individual themes. You can alter opacity, but that’s a poor proxy for actual tints and shades.

Adventure 3: “Can new CSS make it better?”

When I started working on a new version of Grease, I knew one of things I wanted to focus on was a solid, modern, broadly useful color system. And more specifically, I was keen to see if new tools like light-dark() and relative color syntax could make it better. Spolier: yes.

Once again, I wanted to keep the good parts, and whittle away at the cons. The changes start at the top with some new primitives; source colors, and tint & shade steps:

:root {
  color-scheme: light dark;

  /* source colors */
  --neutral: oklch(80% 0.01 210);
  --primary: oklch(30% 0.16 210);
  --secondary: oklch(70% 0.11 20);

  /* tints & shades */
  --0: 100% 0 h;
  --50: 99% calc(c/16) h;
  --100: 94% calc(c/4) h;
  --200: 88% calc(c/2) h;
  --300: 70% c h;
  --300: 70% c h;
  --400: 60% c h;
  --500: 50% c h;
  --600: 40% c h;
  --700: 30% c h;
  --800: 20% calc(c/1.5) h;
  --900: 15% calc(c/2) h;
}

This approach makes it very straightforward to develop a complete, consistent color palette without having to maintain an exhaustive list of properties. A perceptually uniform color space like OKLCH is crucial to making generated color systems like this work well.

Those values get baked into preset colors, using relative color syntax to combine source color with tints & shades, and light-dark() to bake in theme-level light/dark mode support.

  /* preset colors */
  --color-text: light-dark(
    var(--primary),
    white
  );
  --color-bg: light-dark(
    white,
    oklch(from var(--primary) var(--800))
  );
  --color-border: light-dark(
    var(--neutral),
    oklch(from var(--primary) var(--600))
  );
  --color-subtle: light-dark(
    oklch(from var(--neutral) var(--50)),
    oklch(from var(--primary) var(--900))
  );
  --color-accent: var(--secondary);
  --color-shadow: black;

Elements and components can and should use the preset colors as much as possible, but it’s easy to carve out on-theme exceptions. Just drop back down to the primitives:

a:hover {
  color: light-dark(
    oklch(from var(--secondary) var(--600)), 
    oklch(from var(--secondary) var(--200))
  );
}

You create additional themes by redefining your source colors and presets:

.high-contrast {
  --neutral: oklch(30% 0 210);
  --primary: oklch(30% 0.36 210);
  --secondary: oklch(85% 0.36 20);
  --color-text: light-dark(black, white);
  --color-bg: light-dark(white, black);
  --color-border: light-dark(black, white);
  --color-accent: var(--secondary);
  --color-subtle: light-dark(
    oklch(from var(--neutral) var(--100) / 50%),
    oklch(from var(--neutral) var(--800))
  );
}

Composition mostly works the same. Themes are automatically light/dark aware, but thanks to light-dark(), a one-line utility lets you force one mode or the other:

<main>
  <section class="theme-primary">
    <h2>alpha</h2>
    <p>bravo</p>
  </section>
  <section class="theme-secondary dark">
    <ul>
      <li class="card theme-primary light">charlie</li>
      <li class="card theme-primary light">delta</li>
    </ul>
  </section>
</main>

Pros of this approach

Super expressive, super flexible. In the example above I’m sticking to tint & shade presents, but nothing is stopping you from having fun with relative color while never going fully off-theme.
Straightforward, with a nice, tidy set of properties to work with. You get a full set of tints and shades for every color in every theme without having to manually define them.
You’re always working with fully formed colors.
No choosing between color themes and light/dark support. Every theme bakes it in.

Cons of this approach

These are very new properties. Relative color syntax in particular isn’t fully baked yet, with – at time of publish – no broad support for currentcolor or using a color defined with light-dark() as a source. Grease is always a bit forward looking (it’s purpose is to be the starting point for my next website, and I don’t start websites that often), but YMMV.
I’m sticking to the parts of RCS that are broadly available, so this approach is a little lacking on the relative part of relative color. There’s probably more simplicity to be had here when RCS is implemented in full and broadly available.

The quest continues

I’m happy with the progress I’ve made here, but as you can see by the fact that I’m still listing cons, I’m not 100% satisfied. I just can’t help but feel that I haven’t quite cracked it yet. So onto the back burner it goes where it’ll sit and marinate. And once I’ve had time to live with this approach, and relative color syntax has time to mature, I’ll try again to see if I can finally call this side-quest “done”.

House Fan

2024-11-03T00:00:00Z

Our house has one of those old, giant whole-house fans that looks like it was ripped out of an airplane and grafted into the ceiling. We love to run it on cool nights when we can leverage Sacramento’s fabled Delta breeze to maximum effect. The steady current of cool, citrus and jasmine-scented air it produces is deeply satisfying after a sun-scorched day.

It’s also the perfect noise machine, which as it happens, turned out to be a bit of a problem. Our son got so hooked on its soothing sounds that we’d wake up in the middle of 30F winter nights to the sound of our house fan on full blast. We tried subbing in various white noise machines, but he was dead set on the house fan.

I get it. I’m a can’t-sleep-without-noise person, and can attest to the fact that the sound our house fan makes is top-tier. The magic is two overlapping tones; brown noise created by the rush of air moving through the fan, and a deep, resonant thrum created by the fan vibrating the structure of our house like a tuning fork. Our house literally sings us to sleep.

So instead of playing a round of immovable object vs unstoppable force, I decided to figure out an accommodation. “Accommodation” is a word you hear frequently in special education and disability circles (our son is on the spectrum), and it’s a concept we work into day-to-day life. Briefly, an accommodation is a modification or adjustment to the status quo for a person with a given disability, with a goal of increasing access or equity. An accommodation might be more time to take a test, video off on a Zoom call, a ramp for someone using a wheelchair or walker, etc.

The accommodation in this case? A house fan emulator.

I sampled our house fan’s sound, built a simple offline PWA to play it, loaded it on an old iPhone, and hooked it up to a bass-friendly Ikea bluetooth speaker. To make things extra immersive, I added a “rumble pack” on his bed frame (an aquarium air pump).

The overall effect was surprisingly realistic. Like, can’t tell the difference in a blind test realistic. Sufficed to say, the accommodation was accepted. Happy kid, happy dad.

Our son uses it whenever weather doesn’t permit the real deal, and I use it (sans rumble pack) whenever I travel. You can use it too. It’ll work on your phone, offline, forever. No ads, no tracking, just house fan.

Check it out at housefan.aaadaaam.com.

Building House Fan

In theory I could have just sampled a long recording of our house fan, but it would have been harder to use, and let’s be honest, it was a reason to build something fun.

I’ve built just-for-me iOS apps before, but I didn’t feel like dealing with app store nonsense, so I went the PWA route. Plus, I wanted to see what kind of shape PWA background audio on iOS was in (spoiler: not great).

This is a tiny app that I don’t want to maintain, so it’s just vanilla markup, CSS, and JS that’ll work until the heat death of the internet. Here’s what the markup looks like:

<div class="layout">
  <sound-player>
    <figure class="fan" aria-label="a pixel art house fan">
      <div class="frame"></div>
      <div class="louvers">
        <div class="louver"></div>
        <div class="louver"></div>
        <div class="louver"></div>
        <div class="louver"></div>
        <div class="louver"></div>
        <div class="louver"></div>
      </div>
      <div class="blades"></div>
    </figure>
    <audio src="/sounds/house-fan-60.mp3" loop preload="auto"></audio>
    <button aria-label="play" class="button" type="button" aria-pressed="false" aria-label="play">
      <span aria-hidden="true"></span>
      <span aria-hidden="true"></span>
    </button>
  </sound-player>
</div>

A graphic of a house fan broken up into parts for animation purposes, an audio element that points to the recording, and a button. The audio element is important here. If you want background audio to work on iOS – critical for this specific use case – you must to use an audio element. I spent too long working with fancy looping audio libraries before I figured this out.

All the functionality is handled by the sound-player custom element:

export default class SoundPlayer extends HTMLElement {

  playable() {
    this.toggle.addEventListener('click', (e) => {
      this.update();
    });
    this.fan.addEventListener('click', (e) => {
      this.update();
    });
  }

  update() {
    const pressed = this.toggle.getAttribute('aria-pressed') === 'true';
    this.toggle.setAttribute('aria-pressed', String(!pressed));
    this.toggle.classList.toggle('--active');
    if (this.audio.paused) {
      this.audio.play();
      this.toggle.setAttribute('aria-label', 'pause');
    } else {
      this.audio.pause();
      this.toggle.setAttribute('aria-label', 'play');
    }
  }

  loop() {
    this.audio.addEventListener("timeupdate", () => {
      if (this.audio.currentTime > this.audio.duration - 1) {
        this.audio.currentTime = 1;
        this.audio.play();
      }
    });
  }

  connectedCallback() {
    this.fan = this.querySelector('figure')
    this.blades = this.querySelector('.blades')
    this.toggle = this.querySelector('button');
    this.audio = this.querySelector('audio');
    this.playable();
    this.loop();
  }
}

customElements.define('sound-player', SoundPlayer);

It does 3 things:

Adds a CSS hook for when the sound is playing for style/animation purposes.
Adds event listeners to the fan and button to play/pause the audio and update the UI.
Adds an event listener to the audio that sets the time back to the beginning when there is 1s of play time left.

CSS-wise, there’s a few things worth pointing out when it comes to working with small-scale pixel images like this. Here’s the styling for the fan blades, which covers them all:

.fan {
  ...

  .blades {
    position: absolute;
    inset: 0;
    z-index: 1;
    aspect-ratio: 1/1;
    background-image: url("/assets/blades.gif");
    background-size: 200% 100%;
    background-position: 0 0;
    background-repeat: no-repeat;
    image-rendering: pixelated;

    &.--active {
      animation: fan-spin 0.1s step-start infinite;

      @media (prefers-reduced-motion) {
        animation: none;
      }
    }
  }

It uses a common image sprite + background-position approach to animate through frames. Using a steps animation timing function is important here, since it gives you that hard cut you’d expect for frame-based animation. image-rendering: pixelated; is also critical here, otherwise the tiny sprites (some as small as 16x20 px) would be a blurry mess.

Making it work as an offline progressive web app took a few additions. Here’s the relevant portion of the head tag:

<head>
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-status-bar-style" content="default">
  <meta name="theme-color" content="#999" media="(prefers-color-scheme: dark)">
  <meta name="theme-color" content="#ddd" media="(prefers-color-scheme: light)">
  <link rel="manifest" href="/app.webmanifest">
  <link rel="apple-touch-icon" href="/assets/icons/favicon-196x196.png">
</head>

The meta tags are mostly about getting a chromeless, full screen canvas, which makes for a more “app-like” experience. A manifest is a requirement for a site to be detectable as a PWA in some browsers, and includes PWA-specific metadata like the name of the app, additional icons, display mode, etc.

The final piece is a service worker, which is where the “offline” part happens. Here’s what it looks like:

const secondsSinceEpoch = Math.round(Date.now() / 1000);
const PRECACHE = `precache-v${secondsSinceEpoch}`;
const RUNTIME = 'runtime';

// A list of local resources we always want to be cached.
const PRECACHE_URLS = [
  '/',
  '/index.html',
  '/assets/main.css',
  '/app.js',
  '/sounds/house-fan-60.mp3',
  '/assets/frame.gif',
  '/assets/louvers.gif',
  '/assets/blades.gif',
  '/assets/toggle.gif',
  '/assets/off.gif',
  '/assets/on.gif'
];

// The install handler takes care of precaching the resources we always need.
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(PRECACHE)
      .then(cache => cache.addAll(PRECACHE_URLS))
      .then(self.skipWaiting())
  );
});

// The activate handler takes care of cleaning up old caches.
self.addEventListener('activate', event => {
  const currentCaches = [PRECACHE, RUNTIME];
  event.waitUntil(
    caches.keys().then(cacheNames => {
      return cacheNames.filter(cacheName => !currentCaches.includes(cacheName));
    }).then(cachesToDelete => {
      return Promise.all(cachesToDelete.map(cacheToDelete => {
        return caches.delete(cacheToDelete);
      }));
    }).then(() => self.clients.claim())
  );
});

// The fetch handler serves responses for same-origin resources from a cache.
// If no response is found, it populates the runtime cache with the response
// from the network before returning it to the page.
self.addEventListener('fetch', event => {
  // Skip cross-origin requests, like those for Google Analytics.
  if (event.request.url.startsWith(self.location.origin)) {
    event.respondWith(
      caches.match(event.request).then(cachedResponse => {
        if (cachedResponse) {
          return cachedResponse;
        }

        return caches.open(RUNTIME).then(cache => {
          return fetch(event.request).then(response => {
            // Put a copy of the response in the runtime cache.
            return cache.put(event.request, response.clone()).then(() => {
              return response;
            });
          });
        });
      })
    );
  }
});

This is 99% boilerplate that I found… somewhere? The part worth mentioning is the PRECACHE_URLS array. Every resource that you want to be available offline needs to be represented there.

Put all the pieces together, and you get a nice little phone experience. App icon, app-ish feel, and it works 100% offline, forever. Makes me want to build a little library of single purpose, offline PWAs.

Oops, I built a headless frontend with 11ty

2024-11-10T00:00:00Z

My journey with 11ty’s global data went something like this:

“This is where my little text strings go”
“Neat, I can use javascript to set dynamic values”
“Literally any service with an API is my CMS now”

That last phase is key to understanding how our recent help site migration went off-script. We’d been using Intercom for support, but at the end of the day we just weren’t satisfied with the experience for customers, or ourselves. We ended up switching to a combination of HelpScout for a help desk, and Loops for marketing and onboarding sequences (now email-based).

I was all set to do some quick styling on the Helpscout’s hosted help pages, and started digging into their docs when I saw a line of text that instantly set the project off course:

The full Help Scout Docs API documentation can be found here: https://developer.helpscout.com/docs-api/.

“Literally any service with an API is my CMS now”

Memory is hazy about what happened next; all I know is that several days later I looked up my keyboard and I’d designed/built a headless front-end for our docs site on our 11ty-powered website. Here’s how it works.

Authentication

You need an API key to get data from your Docs site; I’m using a standard-issue dotenv setup. The steps in brief:

Install dotenv in your 11ty project.
Create a .env file and add it to your .gitignore file.
Add your API key to the .env file and give it a name, like HELPSCOUT_DOCS=your-key-here
import dotenv at the top of your eleventy config file, like so: import 'dotenv/config';
Also add your key to Cloudflare Pages / Netlify / whatever.

Talkin’ to APIs

The authenticate-and-fetch part is handled by a small helper called fetchHelpScoutData.js:

import EleventyFetch from '@11ty/eleventy-fetch';
import { environment } from '../_data/env.js';
const apiKey = process.env.HELPSCOUT_DOCS;

export default async function fetchHelpScoutData(endpoint, apiKey) {
  const url = `https://docsapi.helpscout.net/v1/${endpoint}?status=published`;
  const key = apiKey || process.env.HELPSCOUT_DOCS;

  const options = {
    duration: environment === 'development' ? '1d' : '5m',
    type: 'json',
    fetchOptions: {
      headers: {
        'Authorization': `Basic ${Buffer.from(key + ':X').toString('base64')}`,
        'Content-Type': 'application/json'
      }
    }
  };

  try {
    return await EleventyFetch(url, options);
  } catch (error) {
    console.error(`Error fetching ${endpoint}:`, error);
    return null;
  }
}

This helper does two important things:

It keeps from having to repeat a bunch of boilerplate for every endpoint we want to grab data from. We have to iterate over multiple endpoints to get the data we need, so a clean abstraction pays dividends here.
It caches the data for a period of time using 11ty fetch so we don’t hit the API every time someone runs a build in local dev.

Building global data

From there, we construct global data files that get used in templates. There are three; one that returns what amounts to a sitemap (nested titles and links for collections, categories, and articles), one that returns categories and the articles within, and one that returns the full content of help articles.

Starting with _data/help-map.js:

import fetchHelpScoutData from '../_utilities/fetchHelpScoutData.js';

export default async function nestedAlt() {
  const map = [];
  const data = await fetchHelpScoutData('collections');
  for (let collection of data.collections.items) {
    const collectionObject = { ...collection, categories: [] };
    const categoriesData = await fetchHelpScoutData(`collections/${collection.id}/categories`);
    for (let category of categoriesData.categories.items) {
      const categoryObject = { ...category, entries: [] };
      const articlesData = await fetchHelpScoutData(`categories/${category.id}/articles`);
      categoryObject.entries = articlesData.articles;      
      if (categoryObject.slug != 'uncategorized') {
        collectionObject.categories.push(categoryObject);
      }
    }
    map.push(collectionObject);
  }
  return map;
};

This demonstrates the general approach of iterating over multiple endpoints to build up a data structure that’s easy to work with. The end result here is an array of collection objects that include arrays of category objects, which contain arrays of article objects.

Here’s _data/help-categories.js:

import fetchHelpScoutData from '../_utilities/fetchHelpScoutData.js';

export default async function collections() {
  const categories = [];
  const data = await fetchHelpScoutData('collections');
  for (let collection of data.collections.items) {
    const categoriesData = await fetchHelpScoutData(`collections/${collection.id}/categories`);
    for (let category of categoriesData.categories.items) {
      const categoryObject = { ...category, entries: [] };
      const articlesData = await fetchHelpScoutData(`categories/${category.id}/articles`);
      categoryObject.entries = articlesData.articles;
      if (categoryObject.slug != 'uncategorized') {
        categories.push(categoryObject);
      }
    }
  }  
  return categories;
};

And finally our articles, via _data/help-articles.js:

import fetchHelpScoutData from '../_utilities/fetchHelpScoutData.js';

export default async function articles() {
  const articles = [];
  const data = await fetchHelpScoutData('collections');
  for (let collection of data.collections.items) {
    const categoriesData = await fetchHelpScoutData(`collections/${collection.id}/categories`);
    for (let category of categoriesData.categories.items) {
      const articlesData = await fetchHelpScoutData(`categories/${category.id}/articles`);
      for (let article of articlesData.articles.items) {
        const articleData = await fetchHelpScoutData(`articles/${article.id}`);
        if (articleData.article.related) {
          const relatedArticles = [];
          for (let relatedArticle of articleData.article.related) {
            const relatedArticleData = await fetchHelpScoutData(`articles/${relatedArticle}`);
            const { name, slug, number } = relatedArticleData.article;
            relatedArticles.push({ name, slug, number });
          }
          articleData.article.relatedArticles = relatedArticles;
        }
        articles.push(articleData.article);
      }
    }
  }
  return articles;
};

This one gets more complex in order to pull in the related entry data for each article, which we’re using for “next page” links within guides.

Building views

From here on out, the process is no different than if you were working with local global data file. All of the pages are handled by one layout ( _layouts/docs.liquid), a partial for the sidebar (_includes/docs/sidebar.liquid), and three templates; docs/index.liquid for the landing page, docs/category.liquid for the category pages, and docs/article.liquid for the individual article pages.

Let’s start with the sidebar:

<nav class="docs-sidebar">
  {% for collection in help-map %}
    <small-details>
      <details open>
        <summary>{{ collection.name }}</summary>
        {% for category in collection.categories %}
          {% if id %}
            {% assign matchingPages = category.entries.items | where: "id", id %}
          {% endif %}
          <details {% if matchingPages.size > 0 %}open{% endif %} name="categories">
            <summary>{{ category.name }}</summary>
            <ul>
              {% for entry in category.entries.items %}
                <li>
                  <a {% if entry.id == id %}aria-current="page"{% endif %} {% if entry.name.size > 30 %}title="{{ entry.name }}"{% endif %} href="/docs/article/{{ entry.number }}-{{ entry.slug }}/">{{ entry.name }}</a>
                </li>              
              {% endfor %}
            </ul>
          </details>
        {% endfor %}
        </details>
    </small-details>
  {% endfor %}
</nav>

The prep work on data structure pays off here, where I can easily iterate over the entries within help-map. A couple of points worth noting:

This uses an exclusive accordion approach, which is now trivially simple in CSS. Give > 1 details element the same name value and you get an exclusive accordion.
I wanted a given category details element to be open when you’re viewing an article and have the article selected. So I’m checking for a matching ID and using it to selectively set the open attribute on the matching category details and aria-current="page" on the article itself.

The landing page for the docs displays the two collections and their categories:


{% for collection in help-map %}
  <h2>{{ collection.name }}</h2>
  <div class="docs-grid">
    {% for category in collection.categories %}
        <div class="docs-card shadow-lg">
          <a class="docs-card__hero" href="/docs/category/{{ category.number }}-{{ category.slug }}/">
            <div class="docs-card__content">
              <h3 class="docs-card__title">{{ category.name }}</h3>
              {% if category.description %}
                <div  class="docs-card__description">
                  {{ category.description }}
                </div>
              {% endif %}
            </div>
          </a>
        </div>
    {% endfor %}
  </div>
{% endfor %}

The category and article templates are where things get a little more interesting because they are used to generate pages from our HelpScout data. That’s where 11ty’s pagination feature comes into play. Here’s the template for category pages:

---
layout: docs.html
pagination:
  data: help-categories
  size: 1
  alias: category
permalink: "docs/category/{{ category.number }}-{{ category.slug }}/"
eleventyComputed:
  title: "{{ category.name }} – {{ site.title }}"
  description: "{{ category.description | strip_html | truncate: 160 }}"
---

{% render 'docs/sidebar.html', site: site, help-map: help-map %}

<section class="docs-primary">
  <article class="docs-column">
    <nav class="docs-crumbs">
      <a href="/docs/">docs</a></a>
    </nav>
    <h1 class="mt-0 mb-md leading-flush size-xxxl">{{ category.name }}</h1>
    <ul class="docs-category">
      {% for article in category.entries.items %}
        {% if article.name %}
          <li>
            <a href="/docs/article/{{ article.number }}-{{ article.slug }}/">{{ article.name }} <span class="arrow"></span></a>
          </li>
        {% endif %}
      {% endfor %}
    </ul>
  </article>
</section>

What that frontmatter pagination block translates to is “generate one page for every entry in help-categories” and give help-categories an alias of ‘categories’ that I can use in my template.

The article template is more of the same:

---
layout: docs.html
pagination:
  data: help-articles
  size: 1
  alias: article
permalink: "docs/article/{{ article.number }}-{{ article.slug }}/"
eleventyComputed:
  title: "{{ article.name }} – {{ site.title }}"
  description: "{{ article.text | strip_html | truncate: 160 }}"
---
{% assign category = help-categories | where: "id", article.categories[0] | first %}

{% render 'docs/sidebar.html', site: site, help-map: help-map, id: article.id %}

<section class="docs-primary">
  <article class="docs-content" data-pagefind-body>
    
    <div class="docs-formatted">
      <nav class="docs-crumbs">
        <a href="/docs/">docs</a> / <a href="/docs/category/{{ category.number }}-{{ category.slug }}/">{{ category.name }} /</a>
      </nav>
      <h1 class="mt-0 mb-md leading-flush size-xxxl">{{ article.name }}</h1>
      {{ article.text }}
      {% if article.relatedArticles %}
        {% assign next = article.relatedArticles[0] %}
        <div class="docs-related">
          <p>
            <strong>Next:</strong> <a href="/docs/article/{{ next.number }}-{{ next.slug }}/">{{ next.name }}&nbsp;→</a>
          </p>
        </div>
      {% endif %}
    </div>

    <table-of-contents></table-of-contents>
  </article>
  
</section>

One of the nice things about HelpScout is that their docs data is stored as HTML, so we don’t need to do any processing or translation on the content.

That table-of-contents tag is a custom element that includes clickable links of all of the major headings within an article, that auto-updates the active heading as you scroll. The heading ID’s are auto-generated by the new ID attribute plugin in 11ty 3.0. Here’s what the custom element looks like:

class TableOfContents extends HTMLElement {
  connectedCallback() {
    this.render();
    this.observeHeadings();
  }

  render() {
    const headings = Array.from(document.querySelectorAll('h2'))
      .filter(heading => heading.id);

    if (headings.length < 2) {
      this.style.display = 'none';
      return;
    }

    const toc = this.generateTOC(headings);
    
    this.innerHTML = `
      <h3>On this page</h3>
      <div>${toc.outerHTML}</div>
    `;
  }

  generateTOC(headings) {
    const toc = document.createElement('ul');
    const stack = [{ level: 1, element: toc }];

    headings.forEach(heading => {
      const level = parseInt(heading.tagName.charAt(1));
      const listItem = document.createElement('li');
      const link = document.createElement('a');
      link.textContent = heading.textContent;
      link.href = `#${heading.id}`;
      listItem.appendChild(link);

      while (level <= stack[stack.length - 1].level) {
        stack.pop();
      }

      if (level > stack[stack.length - 1].level) {
        const newList = document.createElement('ul');
        stack[stack.length - 1].element.appendChild(newList);
        stack.push({ level, element: newList });
      }

      stack[stack.length - 1].element.appendChild(listItem);
    });

    return toc;
  }

  observeHeadings() {
    const headings = Array.from(document.querySelectorAll('h2'))
      .filter(heading => heading.id);

    let isScrolling = false;
    let clickedLink = null;

    const observer = new IntersectionObserver(
      (entries) => {
        if (!isScrolling && !clickedLink) {
          const visibleHeadings = entries.filter(entry => entry.isIntersecting);
          if (visibleHeadings.length > 0) {
            const firstVisibleHeading = visibleHeadings[0].target;
            this.highlightTOCItem(firstVisibleHeading);
          }
        }
      },
      { rootMargin: '0px 0px 0px 0px' }
    );

    headings.forEach(heading => observer.observe(heading));

    const tocLinks = this.querySelectorAll('a');
    tocLinks.forEach(link => {
      link.addEventListener('click', (event) => {
        event.preventDefault();
        const targetId = link.getAttribute('href').slice(1);
        const targetElement = document.getElementById(targetId);
        if (targetElement) {
          clickedLink = link;
          this.highlightTOCItem(targetElement);
          targetElement.scrollIntoView({ behavior: 'smooth' });
        }
      });
    });

    window.addEventListener('scroll', () => {
      if (clickedLink) {
        isScrolling = true;
        clearTimeout(window.scrollTimeout);
        window.scrollTimeout = setTimeout(() => {
          isScrolling = false;
          clickedLink = null;
        }, 100);
      }
    }, { passive: true });
  }

  highlightTOCItem(heading) {
    const links = this.querySelectorAll('a');
    links.forEach(link => link.classList.remove('active'));

    const headingId = heading.id;
    const correspondingLink = this.querySelector(`a[href="#${headingId}"]`);
    if (correspondingLink) {
      correspondingLink.classList.add('active');
    }
  }
}

customElements.define('table-of-contents', TableOfContents);

There’s a lot going on here, but generally we are:

Finding all the h2 elements on the page and using them to build our TOC.
Observing which heading is within the viewport and updating the active TOC element as you scroll.
Updating the active TOC element when you click on it directly.

At this point, we’ve got all of our pages in place, and some solid patterns for fast and fluid navigation. Just one thing missing; search.

Adding search with Pagefind

In my experience, adding search to a static site is painful, clunky, or both. Which is why I was delighted to discover Pagefind. You need to do four things; set up your search input, tell Pagefind what to index, include the Pagefind CSS and JS, and trigger indexing as part of your build.

The search input is set up jump menu style, courtesy of a js-free popover:

<dialog popover id="search" class="modal shadow-lg">
  <div id="searchResults"></div>
  <script>
    window.addEventListener('DOMContentLoaded', (event) => {
      new PagefindUI({
        element: "#searchResults",
        showSubResults: false,
        showImages: false,
        resetStyles: false
      });
    });
  </script>
</dialog>

Telling Pagefind what to index is as simple as adding a data attribute to the context you want to index. In this case, I added it to the element that wraps article content:

<article class="docs-content" data-pagefind-body>
  ...
</article>

I set up the PageFind CSS and JS behind a pagefind front matter key so that any page or layout can opt-in as need be.

{% if pagefind %}
  <link href="/pagefind/pagefind-ui.css" rel="stylesheet">
  <script src="/pagefind/pagefind-ui.js" type="module"></script>
{% endif %}

To build the index, I created a new index script in the project’s package.json file, and added it to the existing scripts for staging and production build (for local dev I run the script as needed only):

"scripts": {
  "start": "ELEVENTY_ENV=development eleventy --serve --incremental --quiet",
  "publish:stage": "ELEVENTY_ENV=stage eleventy && npm run index",
  "publish:prod": "ELEVENTY_ENV=prod eleventy && npm run index",
  "index": "npx pagefind --site _public"
}

That’s all there is to it. Well done Pagefind.

Wrapping up

For a couple days of work to design and build, the results were well worth it. We get all the benefits of keeping help content in HelpScout (CMS for easy management, being able to include help page content in responses to customers, etc), and all of the benefits from a completely bespoke frontend (better experience, tighter brand integration, better SEO from not having help content on a subdomain). The project didn’t go as planned, but I wouldn’t change a thing.

Dusting cobwebs

2024-12-17T00:00:00Z

I haven’t touched the design of this website in a few years, and I’ve mostly been content to let it collect a patina of dust and cobwebs. One of my explicit goals with this iteration of my website was to make it re-design resistant after all.

The key word there is mostly. I’d designed the overview of my work around the job of, well, getting a job. But I’ve been gainfully, happily employed for years now. The job changed, so the page needed to change too. And like with real dust and cobwebs, cleaning one spot tends to put everything left untouched in stark relief. Sufficed to say, one thing led to another. Not to a full re-design, but definitely a refresh. A deep ~~spring~~ winter cleaning.

re-designing /work

The original design for /work was focused around a collection of case studies. A reasonable approach when you’re job hunting, but it created two problems:

All of my case studies were password protected, which made for an unsatisfying experience for all but the small number of people who I gave the password to.
Focusing on depth inherently means you’re not focusing on breadth. Cherry-picking from a long career looks more or less the same as showing the entirety of a short career.

This time around, I oriented the design around breadth and range. I talk about how I’m a generalist designer on my front door; this page needs to pay it off. And while it’s doing that, make it clear that I’m operating from a depth of experience.

So instead of running with the typical “only show the work for the job you want” advice that’s perfectly fine when you’re on the hunt, I took the opposite approach. No edits, no omissions. A comprehensive timeline of my career in tech, but from a 30,000ft view.

All in all, it’s a much more enjoyable page for a visitor, and one that gives you a much better sense of my approach and body of work.

Incorporating anchor positioning

I’m a fan of side-quests, so I decided early on that I’d also use this /work redesign as an excuse to play with anchor positioning. And given it’s still early days and I didn’t want to polyfill, the usage couldn’t be core.

Since I was already running with a timeline, I used dialogs and anchor position to make that timeline more interactive and invite you to explore. About half the cards (in browsers that support anchor positioning) have an affordance you can click to get a little popover with more detail about the piece.

At first I thought it was too subtle / not “anchor position-y” enough. But then I realized something; that’s the point. I’d never reach for javascript library for something like this, but a little bit of markup and CSS? Sure.

HSL -> OKLCH

I took some of of what I learned from chasing color and switched the color system from HSL to OKLCH. This was particularly beneficial for the “random” theme option, which previously converted the colors to RGB in order to apply some arcane javascript that I flatly did not understand in order to derive a contrast ratio between two randomly generated colors.

The OKLCH version? 5 lines:

static lightnessDelta(color1, color2) {
  const lightness1 = parseFloat(color1.split('%')[0]);
  const lightness2 = parseFloat(color2.split('%')[0]);
  return Math.abs(lightness1 - lightness2);
}

OKLCH rules.

New themes, new patterns

A big part of how I’m making a re-design resistant design happen is by making change a constant. Patterns change on every page load. There’s a whole range of color themes, and a random option for even more variety. It’s tough to get sick of something that’s constantly changing.

But there are somewhat fixed parts of these systems, so I gave them some attention. I loaded up a new set of theme presets, and made a bunch of subtle tweaks to the pattern system that makes for a nice overall change in the vibe. Just enough changes to stave off re-design-itis for a few more years.

Hibernating

2025-01-06T00:00:00Z

The older I get, the more I find myself drawn towards seasonality and cyclicality. I find that it both gives structure and meaning to the present while satisfying that deep seated human need for change.

One of the ways I embrace cyclicality in my life is by taking off the two weeks between Christmas and New year’s. And I really, really mean “off”. No work, no side-projects, no blogging, no social media. The goal is to rest, recharge, and reset my perspective in a way that can only happen when you truly stop.

It’s something I’ve done for the past 5 or 6 years, and it’s become a self-care cornerstone. I look forward to it all year, and it lets me come back to work with a spring in my step and a smile on my face. Anecdotally, I’ve never hit a burnout wall since I started doing this. What can I say? Bears know what’s up.

That doesn’t mean I do nothing. Quite the opposite! Here’s my non-exhaustive list of leisure accomplishments for winter break 2024:

Played 40+ hours of Baldur’s Gate 3.
Watched literally every Studio Ghibli movie.
Read a few thousand pages of fiction, notably including the latest entry in Brandon Sanderson’s Stormlight Archive.
Made (and ate) a bunch of great food, including some amazing leftover potroast sandwiches using my homemade Rosemary & Preserved Meyer Lemon Focaccia.
Built this truly epic Dungeons & Dragons lego set with my kid.
Went to a fun interactive light experience at the fairgrounds.
Played many, many rounds of hide and seek.
Slept in.

It was a damn fine break. Here’s to doing it again next year.

Tools that build you

2025-04-27T00:00:00Z

While putting the finishing touches on the latest release of Grease, the words “5 years ago” caught my eye in GitHub. 5 years? Working on this? Of all the things I could do with my free time, of all the side-quests that fizzled out, why am I still working on this?

Upon reflection, my conclusion; it’s good to make and modify your own tools.

Backing way up; tools can be crudely grouped into one of two categories. There are off-the-shelf tools that you buy or borrow; a table saw, a hammer, React. And then there are bespoke tools that you make or modify. Elaborate handmade jigs, bent bits of wire taped to handles that carve clay just so.

Off-the-shelf tools are the foundation of any professional practice, and rightly so. If a cabinet maker built their own table saws and drill presses, there’d be precious little time for making cabinetry. But bespoke tools fill an important role, in that they do precisely what off-the-shelf tools cannot; they fit your exact needs and desires.

Professionally and creatively, that’s important. Case in point; prior to Grease, I’d inherited a large Jekyll website that was long in the tooth, and slow to build. Sufficed to say, waiting 2 minutes after pressing save to see a CSS change show up in browser is a serious problem for someone who’s process revolves around designing in-browser. It made for worse work that took longer, and was a real flow-killer to boot. Tools that fit the way you work matter.

But the value of building your own tools goes beyond functional min/maxing and workflow efficiencies. This took me a while to notice, but ultimately it’s the thing that keeps me coming back. Working on Grease has made me a better designer and developer.

I don’t remember when it happened, but at some point, Grease became my canvas for exploring new ideas & platform features, a receptacle for lessons learned from production projects, and a game of “OK but now how can I do this better?”. A functional, ever-evolving “note to self” of how I think websites should be made.

Building a reusable foundation in Grease pushed me to think more deeply about approaching CSS as a declarative system instead of an ever-growing collection of disconnected rules. It’s made me spend time considering just how much tooling is “worth it”. It’s made me take more care in designing with the grain of the web. It’s made me more conscientious about naming things. It’s made me think about the craft and the process in a way that wouldn’t have otherwise happened if I were just doing typical professional work. It’s made me better.

The thing is, you can’t make good tools without thinking long and hard about the craft and process the tools will be used in. And that act – stepping outside of doing the work and examining the whole – creates a virtuous cycle. You build the tool, the tool builds you.

There’s no such thing as a CSS reset

2025-07-13T00:00:00Z

CSS resets are a technique nearly as long lived as the modern CSS era itself, stretching all the way from the CSS Zen Garden days to inclusion in mass-market current-day tools like Tailwind. Resets are a staple in the CSS toolkit.

But here’s the thing; there’s no such thing as a CSS reset. Now, to be clear, I’m not suggesting some kind of long-running mass hallucination. I’m suggesting CSS resets don’t do what the name says. The word “reset” implies an objective default state that you’re restoring to, but the only objective default state is what browsers ship. You cannot “reset” browser styles by addition. Resets are inherently subjective, which means in practice, you are not so much resetting as you are defining default element styles for a website.

You might think I’m nit-picking semantics – it’s true, I am – but it’s a useful semantic distinction. Because when it comes to defining default styles you only have two choices:

Define defaults that are useful without additional styling.
Define defaults that are not useful without additional styling.

Using those same two bookends of CSS Zen Garden and Tailwind, we started with approach #1, and over time went hard for approach #2. Like, “men would rather invent a CSS framework rather than style a single <button> tag” hard.

To be fair, there were reasons.

Mo’ CSS, mo’ problems

At the risk of flattening nuance, you can more or less summarize the the shift from “embrace the cascade” to “burn the cascade with fire” in two words; specificity woes.

Using tag selectors exclusively inherently lead to deeply nested selectors, which to say another way, increasingly specific selectors. Inevitably you’d run into a situation where you want a style to override one of those highly specific selectors, and you only had a few options:

Add more selector depth to further increase specificity.
Play with source order.
Use the nuclear option, AKA !important.

These tools were fine-ish at small scales and in small doses, but big projects would quickly spiral out of control. The more CSS you added, the more painful it got.

Which is why when strategies like BEM emerged, they felt like a breath of fresh air. You could just… not think about specificity and the cascade at all. Everything was flat, tightly encapsulated, and highly predictable, with nary an !important in sight.

That idea of highly encapsulated component styles became the more or less defacto approach across a variety of permutations; Tailwind, styled components, Atomic CSS, shadow DOM, etc. But through all of those permutations, the humble CSS reset lived on as an element style vestigial tail. It would after all be pretty obnoxious to have to zero out the margin, remove list bullets, etc. in every component in a project where that’s not what you want 90% of the time.

Why use element styles?

The status quo became the status quo for valid reasons, but that’s not to say there weren’t any tradeoffs made along the way. There are some wonderful benefits to directly usable styled elements, and new tools like cascasde layers, and :where() mitigate so many of the cons that the pros are worth a second look. The top 3, in my humble opinion:

Free names: Word on the street is that naming things is hard. What if I told you that there are 100+ names that you can use right now, today, for the low, low price of “free”? Think of elements like components, but ones that come packed in the browser. Custom elements, without the “custom” part. You can just like, use them.
Enforce semantics: People (rightly) bemoan the fact that so many websites composed of undifferentiated div soup, but that’s large in part due to the fact that most modern approaches to CSS intentionally decouple style from structure. By making elements functional components, you can strongly encourage use of semantic HTML. Out with <div class="button">, in with <button>.
Simple page composition: With styled elements, you can just write simple markup or Markdown to scaffold a page. Maybe toss a class in here or there when there’s an exception. I’ve built a bunch of marketing sites over the years and it’s extremely pleasant to design/build a page by starting with semantic markup and having 50%-60% of the work done.

Putting the baby back in the bathwater

Cascade layers are incredible. I stan cascade layers. Every word of this post to this point has been a tee up for me to sing the praises of cascade layers. I am convinced that if cascade layers had existed from the jump, we would have an order of magnitude fewer “CSS hard” memes. They’re easy to use, but give you precise control over CSS specificity (which is to say, they’re very powerful). Here’s how I like to use them:

@layer base, components, utilities;
@import "_base/_base.css" layer(base);
@import "_components/_components.css" layer(components);
@import "_utilities/_utilities.css" layer(utilities);

Each of those imports are an entrypoint that in turn imports more granular CSS files. You can use @layer rules too, but I prefer this approach since it means you can ignore cascade layers outside of this basic config. With 4 lines of CSS, you can more or less run wild with useful, directly usable element styles without them ever overriding your component and utility styles. This is a pretty simple example (I like to keep things simple), but you can use more layers, add sub-layers, whatever makes sense for the project at hand.

Note that I said “more or less run wild” above. Unless you’re already using a defensive approach to writing component CSS, it’s still true that it’d often be impractical or annoying to have to zero out margins, unset pseudo elements, etc. from base styles in all of your component definitions.

A great way to solve that problem is by making spicy element styles opt-in, like so:

:where(article) {
  & > * + * {
    margin-block-start: var(--flow-space);
  }

  & li::before {
    content: " ";
    display: block;
    height: 0.1rem;
    width: 100%;
  }
}

Your core element styles take care of the 80% case, opt-in element styles take care of the 20% case, and you can keep writing component CSS as if you’re using a reset + pure encapsulation approach.

With cascade layers and opt-in spicy styles, you might still have a few instances where you need to manage specificity within layers. A sub-layer might be a good choice, but I rely on :where() selectors primarily, which let you use nested selectors without increasing specificity. Combining cascade layers with :where() lets you create some truly wimpy styles:

@layer base {
  :where(ul > li) {
    color: red;
  }
}

Everything beats this style. You look at this style wrong and it crumbles. This is the fainting goat of CSS.

There are more techniques and more tools in the tool belt when it comes to managing the cascade (looking at you @scope), but the point is, CSS is in a fundamentally different place than it was even 5 years ago, and it’s worth taking the time to reconsider decisions made around outdated tradeoffs.

Kobo-pilled

2025-08-11T00:00:00Z

About 6 months ago – right around the time that Amazon made it crystal clear that you do not own ebooks you purchase in any meaningful sense – I bought a Kobo Libra Color.

I don’t really do product reviews, and this isn’t really a product review. I’m writing about my switch because it’s the most refreshing technology experience I’ve had in years, and one that meaningfully changed my behavior for the better. Whew.

Prior to the aforementioned enshittification event, my Kindle experience was “fine”. I bought and read books for years; mostly on my phone (I know) instead of my ancient PaperWhite. I didn’t really think about it at all, in the way I don’t think about my internet provider. It was just the conduit for my reading habit. I probably would have kept muddling along that way for years if Amazon hadn’t decided to be… Amazon. But they did, and in retrospect I’m better off, so (grits teeth) thanks Amazon.

The device itself is nice, but that’s not really what this story is about, so here’s the hardware TL;DR. It feels like tech that’s intended to be used and abused. It’s solid, light, and decidedly un-precious. Case? Screen protector? LOL, no. Throw it around, get it wet, it’s fine. People have big feelings about color e-ink screens. I like it. The UI is snappy by e-ink standards. End hardware review.

The real star of the show is the Kobo software and ecosystem. I say this as a pure, unabashed compliment; the Kobo experience feels like a product of a past era. A few highlights:

You can plug you Kobo into a computer and sync it up with the open source e-book swiss army knife, Calibre. To say it another way; you can completely ignore the Kobo store if you want. How many modern portable devices can you say that about?
You have a ton of control over the reading experience, in a Win95 control panel kind of way. It’s a lot, but also empowering.
The Kobo store is not filled with an endless sea of self-published platform exclusive drek. It’s filled with… exactly the same books you’d see at a good local bookstore. In other words, it seems like it’s run by people who actually read and like books.

There’s more, but all these things add up to a device that feels like tech from 20 years ago. And in the era of enshittification, I find that incredibly refreshing.

But the real killer feature is Kobo’s Overdrive integration. Prior to owning a Kobo, I couldn’t tell you the last time I checked a book out from the library. It just wasn’t part of my reading habit. But now I had this rectangle in my hand that could do all sorts of library things, so I was like hey, why not give this a shot.

The good times start with discovery. Overdrive is baked directly into the on-device storefront, so you can browse around and seamlessly place a hold. You get notified when holds become available, and can check out, read on device, return, the whole 9 yards. A whole library of books, stuffed into a 6" rectangle. It’s awesome. So awesome that I went from being a “I only buy books” guy to a certified Library Guy. I read daily, and I’ve done nothing but read e-books from the library for the past 6 months.

I struggle to think of another piece of technology that has had such an immediate and drastic impact on one of my core habits. In a way, it feels like I’ve discovered reading all over again. Every time a hold becomes available – particularly when it lands early – it feels like Christmas. I love it. Kobo (and library) pilled.

This website has no class

2025-09-14T00:00:00Z

In my recent post, “There’s no such thing as a CSS reset”, I wrote this:

Think of elements like components, but ones that come packed in the browser. Custom elements, without the “custom” part. You can just like, use them.

The line continued to rattle around in my head, and a few weeks later when I was digging into some cleanup work I came to an uncomfortable realization; I wasn’t really taking my own advice. Sure, I was setting some default element styles, but I was leaving a lot on the table. I felt attacked. Called out even. Present me, positively roasted by past me. There was only one possible solution; refactor my website.

I like to apply severe constraints in designing and building this site – I think constraints lead to interesting, creative solutions – and it was no different this time around. Instead of relying on built in elements a bit more, I decided to banish classes from my website completely. I haven’t used a class-free approach since the CSS Zen Garden days, and wanted to se how it felt with modern HTML and CSS.

Doubling down on styled defaults

CSS for the site was structured around 3 cascade layers; base, components, and utilities. Everything in base was already tag selectors, so the task at hand was to change my approach for components, and eliminate utilities completely.

Step 1? Mitigation. There was plenty of code that could have been styled defaults but wasn’t, so I gave all my markup a thorough review, increasing use of semantic elements, extracting common patterns in the form of new element defaults, and making more use of contextual element styling. By contextual styling, I mean going from something like this:

.header-primary {
  margin-block: clamp(var(--size-sm), 4vw, var(--size-lg)) var(--size-flex);
}

To something like this:

body {
  background-color: var(--color-sheet);

  & > header {
    margin-block: clamp(var(--size-sm), 4vw, var(--size-lg)) var(--size-flex);
  }
}

It was a good start, and modern features like nesting, :where(), and :has() made this feel better that it did 20 years ago, but I took things way too far with contextual styles. Taken to the extreme, you end up with overloaded selector definitions and progressively more esoteric selector patterns. I knew I was down the rabbit hole when I did something like this:

li {
  &:has( > a + p) {
    padding-block: var(--size-lg);
    border-block-end: var(--border-default);
    text-wrap: balance;

    & > a {
      font-size: var(--font-xxl);
    }

    & > p {
      margin-block: var(--size-sm);
    }
  }
}

I still needed a “real” solution for components, and a way to manage variants.

Custom tags & custom attributes

I had an inkling of a solution, which is to leverage patterns from custom elements and web components, sans js. By virtue of their progressively enhanced nature, custom tag names and custom attributes are 100% valid HTML, javascript or no. That inkling turned into fervent belief after reading Keith Cirkel’s excellent post “CSS classes considered harmful”.

Revisiting the example above, now we’ve got a pattern like this:

note-pad {
  padding-block: var(--size-lg);
  border-block-end: var(--border-default);
  text-wrap: balance;

  & a {
    font-size: var(--font-xxl);
  }

  & p {
    margin-block: var(--size-sm);
  }
}

Custom attributes become a go-to for handling former BEM modifiers, but instead of relying on stylistic writing convention to fake a key-value pair, you get an actual key-value pair.

random-pattern {
  & [shape-type="1"] {
    border: 0.1rem solid var(--color-sheet);
    background-color: var(--color-sheet);
    filter: url("#noise1");
  }

  & [shape-type="2"] {
    background: var(--pattern-lines-horizontal);
    background-size: var(--pattern-scale);
  }
}

Now, you can use data-whatever for attributes, but really, any two dash-separated words are safe. Personally, I think dropping the data prefix feels better and allows for richer semantics.

You can argue that both of these techniques are re-inventing classes in various ways. Kind of! You can use custom element names in lieu of semantic tags, just like you can slap a class on a div. But these techniques, particularly with how you can seamlessly enhance to true custom elements or web components, feels like a coherent end-to-end system in a way that class-based approaches don’t. It’s tags and attributes, all the way down.

Would I do this again?

On the plus side, the user outcomes are decidedly positive; I removed a non-trivial amount of CSS (now about ~5KB of CSS over the wire for the entire site), and accessibility is without question better due to having to paid much closer attention to markup. Also, just look at that markup. So clean. So shiny.

On the flipside, this feels like an approach that simply asks more of authors. It requires more careful planning compared to pure component approaches; you can’t think of things in purely isolated terms. All to say, I’m very happy to ship this on my personal website, I’d be less likely to advocate for this approach on a large project with varied levels of frontend knowledge.

There’s a variation here that’s more encapsulated (use custom tag names with abandon), but that pulls on what feels like an unresolved thread; replacing a semantic element with a custom tag name that has no semantic value feels bad, and adding extra wrappers around everything also feels bad.

All to say, I’m not quite ready to say that this is The One True Way I’ll build all sites from now on, but I also can’t help but feel like I’ve crossed some kind of threshold. I used to think classes were fine. Now I’m not so sure. I don’t know exactly where it’ll lead yet, but this feels like one of those exercises that’ll have a lasting influence on my work.

A mea culpa; I only got 99% of the way there. I use 11ty’s syntax highlighting plugin, which uses classes for styling. I gave syntax-highlight a hard look, but I don’t love the idea of introducing client-side js where none need exist, and the authoring experience would be a step back, so I begrudgingly left it alone for now.

Taming Tailwind, part 2

2025-10-01T00:00:00Z

In the first Taming Tailwind post, I documented how I’d inherited a Tailwind project that I eventually switched from a utility-first approach to a hybrid modern CSS + Tailwind architecture. I didn’t intend to write any more on the subject, but then they went an released a major rewrite with Tailwind 4. This is the story of that upgrade; the good, the bad, the WTFs, with even more taming.

Tailwind 4; now featuring CSS

The major change from v3 is a significantly more CSS-forward stance; CSS-based configuration, design tokens as custom properties, real cascade layers instead of the faux-layer system that made it impossible to use real cascade layers (I’m not bitter). No beating around the bush; this is an extremely positive change, and coupled with streamlined tooling, v4 is flatly better, and significantly so.

Here’s the entirety of the v4 configuration for the project:

@import 'tailwindcss' source("../../../app");
@source "../../../app/**/*.svg";
@source "../../../app/frontend/**/*.css";
@source "../../../app/{components,views}/**/*.html*";
@source "../../../config/initializers/*.rb";
@variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

@theme {
  --color-*: initial;
}

Sufficed to say, this is much more pleasant – and much less config – than the json v3 equivalent. Note the --color-*: initial; line, we’ll get to that later.

Upgrading; ouch

Some libraries take great pains to avoid breaking changes, and/or maintain backwards compatibility. And then there’s Tailwind. Breaking changes were everywhere. Some were obviously due to under the hood changes, but the majority of it seems to have come from a “let’s revisit all of our decisions” place.

To their credit, there is a migration script, but as you can see from the releases, it’s been an ongoing work in progress. At the time that I made the switch, I’ll hazard a guess that the migration script took care of about half of the work, and I had to exhaustively QA every single route. Woof.

Not unique to Tailwind, but this is a prime example of why I don’t like using CSS libraries. They come with a tax, and the bill comes due at upgrade time.

Out with the theme() function, in with custom properties

Tailwind 3 included a theme() function that used a dot notation to access various token values. You’d use it like this:

.button {
  font-weight: theme(fontWeight.normal);
}

That’s toast in v4. Instead, most tokens are just regular old custom properties:

.button {
  font-weight: var(--font-weight-normal);
}

So much better, particularly for the kind of approach I’m using here, where Tailwind is being used alongside regular CSS. It feels like one system now, which makes things easier to reason about.

Note that I said “most tokens”. V4 includes a few single purpose functions; one for spacing values, and another for manipulating opacity. Here’s how they work:

.button {
  color: --alpha(var(--color-text) / 10%);
  padding: --spacing(2);
}

These compile down to color-mix() and calc() respectively. You can also use the underlying var(--spacing) custom property if you want the default value. Obviously you can use any number in these functions, so they don’t set you up for success consistency-wise. On the plus side, they’re syntactically identical to forthcoming CSS functions, which’ll make for an easy transition when they’re ready for prime time.

Color management; still bad

Aside from switching to custom properties, the Tailwind color story is unchanged from v3. Which is to say, it’s still one of the worst aspects of Tailwind. It starts with the assumption that you’re going to litter every component with dark: variants. So right out of the gate, you’re signing up for utility bloat, and touching every component if you want to change colors. Now let’s say you want to take thinks a step further and introduce additional color themes. Here’s the Tailwind way, pulled straight from the docs:

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

Which would get used like:

<div class="bg-white dark:bg-black theme-midnight:bg-blue-800"></div>

That’s right, the answer is even more component-level utility bloat. Utter madness. I honestly struggle to think of a worse way to managing color with CSS. So I relieved Tailwind of the job, and implemented a system that I outlined in Chasing Color. First step is dropping all the Tailwind provided colors in the Tailwind config:

@theme {
  --color-*: initial;
}

Then defining some new :root colors:

:root {
  /* color: core */
  --color-white: oklch(100% 0 0);
  --color-neutral: oklch(60% 0.04 276);
  --color-accent: oklch(55% 0.23 276);
  --color-success: oklch(69% 0.12 195);
  --color-danger: oklch(60% 0.18 10);
  --color-warning: oklch(69% 0.15 33);
  --color-link: oklch(60% 0.18 256);
  --color-highlight: oklch(79% 0.3 90);

  /* color: steps */
  --50: 98% calc(c/16) h;
  --100: 95% calc(c/8) h;
  --200: 93% calc(c/4) h;
  --300: 85% calc(c/1.5) h;
  --400: 75% c h;
  --500: 55% c h;
  --600: 50% c h;
  --700: 35% calc(c/1.5) h;
  --800: 25% calc(c/2) h;
  --900: 21% calc(c/2) h;
  --950: 19% calc(c/2) h;

  /* color: presets */
  --color-text: light-dark(
    oklch(from var(--color-neutral) var(--900)),
    oklch(from var(--color-neutral) var(--50))
  );
  --color-text-muted: light-dark(
    oklch(from var(--color-neutral) var(--600)),
    oklch(from var(--color-neutral) var(--400))
  );
  --color-text-subtle: light-dark(
    oklch(from var(--color-neutral) var(--400)),
    oklch(from var(--color-neutral) var(--600))
  );
  /* more presets... */
}

Those presets are used directly in CSS, and a set of non-Tailwind utilities applies select presets in the random instances where UI is composed of utilities (mostly non-customer facing admin views).

Want to change the accent color globally? Change one custom property. Want to add additional themes? Redefine a few custom properties. What’s more, this approach adds a significant amount of consistency, makes it so you don’t have to think about themes and color modes at the component level at all, and in practice shed a surprising amount of weight from the production CSS bundle.

Closing thoughts

V4 is the best version of Tailwind, and a vast improvement from v3. But the simple truth remains; utility-only CSS is a deeply flawed architectural approach, and using more modern CSS features doesn’t change that fact. Which makes mitigation – like with asbestos – the best approach.

For this project in particular, the worst offenders have been fully excised. The project is mostly component CSS now, with Tailwind relegated to build, token management, and exception management duty. Because of that, there’s not a strong reason to spend the time it’d take to full remove it. It just doesn’t make sense given all the other priorities we have. But as more CSS features become widely available, like functions and custom media queries, I’ll keep chipping away at it. If I write a third post in this series, it’ll be brief. “I got rid of Tailwind. The end.”

Lowriders & websites

2025-10-06T00:00:00Z

My recent post on removing classes from my personal site was unusual in a few ways; I got a surprising number of kind emails about it, and on the flip side, it broke containment and ended up on Hacker News. I know you shouldn’t look at the comments. No good can possibly come from looking at the comments. I looked at the comments.

My immediate takeaway; the advice on not reading Hacker News comments is good advice. My less immediate takeaway had to do with one comment in particular. The commenter in question – let’s call them ElonStan420 – was taking me to task for the following line:

Also, just look at that markup. So clean. So shiny.

According to ElonStan420, I’d committed the ultimate Very Serious Programmer sin of putting time and energy towards something that “doesn’t really matter”.

It instantly reminded of our annual trip to the California State Fair. Along with corn dogs cattle, and carnival rides, the state fair features yearly exhibitions of various facets of California culture. On rotation this year was an exhibit on lowriders, with a dozen or so examples arranged in a circle, hoods, trunks, and doors ajar so you could see every detail.

I don’t profess to know much about lowrider culture, but I can tell you this; those cars were beautiful. Obviously, the paint and pinstripes were immaculate. But what struck me was the fact that there was’t a single part of these vehicles that received anything other than the utmost care and attention. The springs, the struts, the frame, the engine compartment, everything. They felt more like functional sculptures than “car”, and absolutely oozed pride-of-craft. That’s not me editorializing; in many instances, the owner was standing by, beaming with pride at the oooohs and ahhhs from the crowd.

I think of ElonStan420 standing in that exhibit hall, eyeing those cars with disdain because all that time, energy, care, and expression “doesn’t really matter”. Those hand-painted pinstripes don’t make the car faster or cheaper. Chrome-plated everything doesn’t make it more efficient. No one is going to look under the hood anyway.

The thing is, this particular brand of “functional absolutism” that’s widely held in tech circles is a bankrupt philosophy. It leaves no room for beauty, no room for expression, no room for investing time and care in something for no other reason than you find it satisfying to do so.

Should every website be the subject of maximal craft? No, of course not. But in a industry rife with KPI-obsessed, cookie-cutter, vibe-coded, careless slop, we could use more lowriders.

Pumped up

2025-10-28T00:00:00Z

If you asked people to name the most impactful technology of the last 100 years, some might say the lightbulb, others the transistor, and others still the microprocessor.

Each of those has played a major role in shaping modern life, but there’s another technology that’s equally as impactful, but day in, day out, goes largely unnoticed aside from the low hum coming from your kitchen. Or more specifically, from your refrigerator.

The thing inside that makes your food cold – the humble heat pump – is a true modern marvel that doesn’t get nearly the credit it deserves. You don’t need to look any further than refrigeration to make the case. We take it for granted, but do you know what food was like before modern refrigeration? Not great.

Food-related illnesses were rife, good luck getting fresh fruit and vegetables out of season, everything had to be canned or preserved to prevent spoilage, most food ended up spoiled anyway, if you were lucky you had the privilege of constantly dragging giant blocks of ice into your icebox, and so on. In other words, food regularly killed people, was less nutritious, comparatively tasted like shit, and required exponentially more effort. Thank you heat pumps.

But refrigeration is just the tip of the iceberg. Let’s move on to the next most familiar use of heat pumps; air conditioning. Now, if you live in a cool climate you might write off this particular use case off as unnecessary or even wasteful, but air conditioning saves lives in hot climates. According to this report from the IEA, AC saved an estimated 190,000 lives from 2019-2021 alone. The fact that you can live in a climate like mine here in Sacramento without feeling like you’re living on the surface of the sun is just a nice bonus.

But wait, there’s more. Heat pumps also have the power to improve our health and play a major role in saving our sorry selves from the existential threat that is global warming by eliminating fossil fuel use and significantly increasing efficiency.

I’ll use my house as an example. It relied quite a bit on natural gas, with some low-efficiency electric appliances in the mix; gas furnace, gas stove, gas water heater, resistance heat dryer. That made it remarkably similar to the 75% of homes in the western USA that rely on natural gas, and part of the 4.5 trillion cubic feet of natural gas used by residential homes in the USA each year.

Now, this is a bit of an aside, but bear with me. “Natural gas” is the greatest marketing con job ever perpetrated on society.

“Oh, it’s natural, it must be harmless”. No. You know what natural gas is? Methane. Just like what comes out of a cow’s ass. You know that prank where 13 year old boys cup their hands around a fart and then release it in someone’s face? That’s basically what people are doing with natural gas, except the fart was dealt 200 million years ago, the 13 year old boy is an energy utility company, and you’re paying them to un-cup that ancient, decrepit fart in your face.

You might be thinking, “it doesn’t go into my face, it gets burned up in my stove and my water heater”. Not quite. Like with the cupped fart, leakage is a fact of life with natural gas. Leaks happen during extraction, transport, and finally, at the point of use, directly into your face. The former contributes to global warming and local air pollution, the latter literally poisons you.

Now don’t get me wrong, burning methane is better than burning coal. But we have the technology. Yes, you guessed right, heat pumps. Up to this point, I’ve only talked about ways heat pumps cool things. But heat pumps are called “heat pumps” and not “cold makers” for a reason; they move heat from place to place. They can move heat out of a space cool it, but they can also do the reverse and move heat into a space to warm it up.

Moving heat is also the key to why heat pumps can be so efficient in heating applications. A gas furnace or resistive electrical elements can never be more than 100% efficient. The best you can do is turn 100% of that fuel source into heat. But heat pumps don’t directly turn farts or watts into heat. They use watts to run a compressor that moves heat that’s in the air or ground into your home, which lets you readily break that efficiency barrier. Why settle for 100% efficiency when you can have 300% or more?

Historically, heats pumps haven’t been used nearly as much for heating purposes, but all sorts of companies have improving that particular use case, and as of today are cranking out uber-clean, ultra-efficient alternatives to common home appliances. Going back to the example of my house:

Gas furnace and separate air conditioner → whole house heat pump. Basically a more efficient AC that runs in reverse in the winter, capable of pulling heat out of sub-zero temperatures. Much cheaper to run in my market, zero venting risk, and it eliminated an entire HVAC system.
Gas water heater → hybrid heat pump water heater. It has standard electric heat strips for backup; we keep it in heat-pump only mode. Again, cheaper, safer.
Electric vented dryer → ventless heat pump washer/dryer combo. Way more efficient, and extra so because you’re not taking conditioned air from inside your home and shoving it out you dryer vent. Also, not having to switch loads rules.
Gas range → induction range. Not a heat pump, but totally awesome. You’re cooking with magnets.

The net result of these changes are a decarbonized home that’s significantly safer, more comfortable, and cheaper to operate, which keeps my local air cleaner, and the world less toasty. Heat pumps are awesome.