lowmess

My Interop 2027 Picks

Sat, 12 Sep 2026 00:00:00 GMT

Each year, The Interop Project chooses web features and APIs to focus on delivering complete implementations of over the coming year. The goal is to create a stable, targetable platform that developers can be confident in regardless of user browser choice. For the last few years, the team has asked the broader community to weigh in on which features would make the most impact for them. Inspired by Stuart Robson’s blog post doing the same, I’m sharing the features I picked for next year in the developer survey.

`Temporal`

Date sucks. We all know it. It’s a giant pain to work with, and causes untold headaches when you can’t be certain where it will be created, manipulated, or formatted for display. Thankfully, Temporal fixes all that while adding functionality typically provided by expensive third-party libraries. Unfortunately, it is not currently supported in Safari – though it is already in the Technical Preview build. This might have been a “wasted” vote given that, but I need this to land as soon as possible for mental health reasons.

Recommended reading: “Date is out, Temporal is in” by Mat Marquis

Customizable `<select>`

There is probably no individual HTML element I have argued about more than <select>. I’m of the opinion that the thousands and thousands of hours that have been poured into creating JavaScript-based <select>-like elements just to have a slightly more visually cohesive dropdown (often at the expense of usability) were a waste, to say the least. So fully stylable <select>s were already going to be a win, even before they tacked on even more incredible functionality. Bring that same love to <datalist> and we could eliminate entire UI libraries.

`attr()`

attr() has long been a handy way to pass content from HTML to CSS psuedo-elements. But there’s a whole new slate of functionality coming soon: it can be used in all properties (not just content), typed for its use, and have fallback values. This opens up all sorts of possibilities, but for me this is primarily an avenue towards removing tons of inline styles used only to set custom properties to achieve this same purpose.

`interpolate-size` & `calc-size()`

My favorite part of delivering any feature is the last 5% of polish to make it really feel satisfying to use. A lot of times, that comes down to subtle animations for state changes. @starting-style and sibling-index have already gone a long way to removing some of the plumbing, but I am very excited to never again write JavaScript to calculate an element’s expanded size before animating it in.

`@function`

Mentally I am including a bevy of new built-in support functions here: if(), style(), and color-scheme() to name a few. Combining these with custom functions, I think the way we write CSS is going to dramatically change in the next few years. I am looking forward to never writing calc(<value> * -1); more than once per project ever again.

Interest Invokers

I’m always excited to ship less JavaScript, especially without a degredation of functionality or customizability. Interest invokers allow us to create popovers (tooltips, those sweet preview cards on Wikipedia you get when you hover over a link, those sorts of things) and display them to the user with no JavaScript involved whatsoever. Even more they allow us to delay the entry and exit of those popovers for graceful recovery.

Container `scroll-state()` Queries

I have had the unfortunate experience of creating several monstrous CSS classes that hack together a “hey this container has scrollable content” affordance. They work, but are never very adaptable and are always extremely hard to reason about. @container scroll-state(scrollable: block-end) is much clearer. The number of times I’ve wished for scroll-state(stuck) is also immeasurable.

`gap` Decorations

While there are lots of applications for gap decorations, I’m most excited for them to share one specific bugbear: ghost separators for wrapped flex children. Right now, there is no way to tell if an item is the first or last child of a row when it has wrapped, so if you are rendering an HTML element (psuedo- or no) to separate items, it will always show. Once we’re able to style the space between rows rather than the space between elements, this problem disappears entirely.

Anchor Positioning

Gotta be honest: this one is purely selfish. The little underline in the header navigation on this site is a single anchor-positioned element where the anchor scope changes based on :hover/active state. And it technically works in all major browser engines…but Chromium is the only one that will animate it. Other than that I have not found a single issue with anchor positioning between browsers. But my animation!

Generating Open Graph Images With Astro & Satori

Wed, 28 Jan 2026 00:00:00 GMT

Several eons ago, when I cared about these things, I wanted to update all of the headers across my various social media accounts to use the same design. Because each platform wanted slightly different sizes this was quite annoying to do manually in design software. Luckily I already knew a tool that could adapt to the various sizes each platform demanded: HTML & CSS. So I hacked together a tool to abuse the then-new Puppeteer library to take screenshots of a given HTML page at the required sizes. And it worked great!

I’m far from the only person to think the flexibility of these technologies makes them perfect for dynamic imaging. When Vercel ran into similar issues generating Open Graph images at scale they created a whole library about it. When I was looking to do the same for this site, combining Astro’s endpoints feature with that library seemed like an ergonomic option. It turned out to be even better than I thought. (And, before we get too far, some folks do still go the Puppeteer route!)

First Off, What’s an Open Graph Image?

You know when you paste a link into some app and seems to magically pull in a description and image for that page? That’s all powered by something called the Open Graph protocol. Originally developed by Meta to enhance links shared to (and from) Facebook, it has since become the defacto standard for displaying information in link previews.

And We’re Generating These Images How?

First things first, I am going to assume you already have an Astro site set up. Second things second, we need to install some dependencies to get this to work:

npm i satori react sharp

Satori renders JSX to SVG. React is needed for Satori’s layout engine. Sharp is used to take the resulting SVG and transform it into a PNG. You could also use resvg-js for this last part, but I already had Sharp installed, so that’s what my examples will use. If you use Astro’s image components you very likely already have Sharp installed as well. Because this is Astro, unless you explicitly set out to make a React component that uses Satori and Sharp on the client for some reason, none of these dependencies will be shipped to the client.

Making a Helper

On this site I have two templates for images I want to show. For blog posts, I want to include the title and date for the post. For every other page I want to include a generic image that has the same general vibe, but with the site’s tagline. That being the case it makes sense to separate template rendering from template definitions.

import { type ReactNode } from "react";
import satori from "satori";
import sharp from "sharp";

export async function generateOgImage(template: ReactNode) {
	const svg = await satori(template, {
		width: 1200,
		height: 630,
		fonts: [],
	});

	return await sharp(Buffer.from(svg)).png().toBuffer();
}

A few questions might pop out here.

Why 1200x630?

Very good question. I do not know. But it is the most common recommendation.

Why Return a `Buffer`?

Since we will be returning these from an endpoint, we need to encode the information in a way that will fit into a Response.

Why is `fonts` Empty?

We actually need to add some stuff there, but it depends on whether you are using third-party or local fonts (or, I suppose, some combination of the two). If you are loading your fonts from Google or another third-party source, you should fetch the file and turn it into an ArrayBuffer.

const myFetchedFont = await fetch("https://example.com/font-file.woff");
const myFetchedFontData = await myFetchedFont.arrayBuffer();

export async function generateOgImage(template: ReactNode) {
	const svg = await satori(template, {
		width: 1200,
		height: 630,
		fonts: [ 
			{
				name: "MyFetchedFont",
				data: myFetchedFontData,
			},
		],
	});

	return await sharp(Buffer.from(svg)).png().toBuffer();
}

For local fonts, fs.readFileSync is your friend. Note that the path for the font file should be from the project root, not relative to the helper.

import fs from "fs";

const myLocalFont = fs.readFileSync("./src/fonts/my-local-font.woff");

export async function generateOgImage(template: ReactNode) {
	const svg = await satori(template, {
		width: 1200,
		height: 630,
		fonts: [ 
			{
				name: "MyLocalFont",
				data: myLocalFont,
			},
		],
	});

	return await sharp(Buffer.from(svg)).png().toBuffer();
}

With the helper in place, we need some templates to render. As I mentioned, I have two, but they share a layout so I actually have three components. This will vary site by site but the general idea is we’re creating functions that return JSX for Satori to render.

export function BlogPostOgImage({ post }: { post: BlogPost }) {
	return (
		<div
			style={{
				display: "flex",
				width: "100%",
				height: "100%",
			}}
		>
			My post is called {post.title}
		</div>
	);
}

Satori only supports a subset of CSS and even then only through inline style objects. It’s not the best experience in the world, but it’s also important to remember that these images can be rendered quite small. If it gets cumbersome to edit the template or you’re having issues with your design, it’s usually a sign to simplify.

Okay But How Do I Put These On My Website?

Astro is most commonly used to generate HTML pages and their associated CSS and JavaScript. But you can use endpoints to return any type of data we want. In this case, we want to create an image for each blog post. Let’s create a new route at pages/blog/[slug]/og-image.png.ts to serve up these images.

import { type APIContext } from "astro";
import { generateOgImage, OgBlogPostImage } from "#utils/og-image.tsx";

const allPosts = await getAllPosts();

// Generate a path & return a `GET` endpoint for each post
export async function getStaticPaths() {
	return allPosts.map((post) => ({
		params: { slug: post.slug },
	}));
}

export async function GET({ params }: APIContext) {
	const { slug } = params;
	const post = allPosts.find((post) => post.slug === slug);

	// If we don't have a post, we don't have an image
	if (!post) {
		return new Response(null, {
			status: 404,
			statusText: "Not found",
		});
	}

	// React isn't in context, so call the template as a normal function
	const png = await generateOgImage(OgBlogPostImage({ post }));

	// Cast from `Buffer<ArrayBufferLike>` to `Uint8Array<ArrayBuffer>`
	return new Response(png as Uint8Array<ArrayBuffer>, {
		headers: { "Content-Type": "image/png" },
	});
}

Of course, this will change depending on how you get your posts into your site – I use a content collection – but the core idea is the same. Fetch your posts and create a static GET endpoint for each one. And if you’re in SSR mode, you can just remove the getStaticPaths and generate the image on the fly! You’d probably want to add some caching in that case, though.

It’s All In Your `<head>`

Once the the images are being generated, you have tell other sites where to find them. If you clicked on the Open Graph protocol link above you probably spotted the secret sauce. Even if you didn’t I’ll still tell you: we need to add a tag to the <head> of our pages. This probably means adding a prop to your layout component (with a default value if you have a generic image).

---
type Props = {
	ogImageUrl?: string;
};

const { ogImageUrl = `${Astro.url.origin}/og-image.png` } = Astro.props;
---

<!doctype html>
<html>
	<head>
		<meta property="og:image" content={ogImageUrl} />

		<!-- the rest of your site metadata, probably including other Open Graph tags -->
	</head>
	<body><!-- your site content --></body>
</html>

Then we update our blog post page:

---
import Layout from "#layouts/global.astro";
---

<Layout ogImageUrl={`${Astro.url}og-image.png`}>
	<!-- blog stuff -->
</Layout>

Note that the links to the images are absolute links derived from Astro.url. Some sites will be able to pick up on relative links, but in general it’s always safer to have absolute links.

And Then What?

Then you post the link to the blog post you wrote about putting Open Graph images on your website! That’s my plan, at least.

Creating a Dark Mode Toggle in 2026

Mon, 19 Jan 2026 00:00:00 GMT

I recently added a system-aware color theme selector to this website. Like, an hour ago. It was preposterously easy; the hardest part was deciding how and where I wanted to display the toggle. If you don’t believe me (or don’t want to read this article), here’s an entire implementation in about 50 lines of code. Let’s break it down.

An Introduction to `color-scheme` and `light-dark()`

The two features that (now) make this so easy are color-scheme and light-dark(). Put simply – or at least succinctly – color-scheme allows us to tell the browser which color schemes an element supports and light-dark() allows us to assign <color>s by the combination of that value and the user’s prefers-color-scheme setting. You could imagine a light-dark() implementation in JavaScript looking something like this:

function lightDark(lightValue: Color, darkValue: Color) {
	const colorScheme = getNearestColorSchemeRule();
	const userPrefersDark = window.matchMedia("(prefers-color-scheme: dark)");

	if (colorScheme === "light") {
		return lightValue;
	}

	if (colorScheme === "dark") {
		return darkValue;
	}

	return colorScheme.includes("dark") && userPrefersDark.matches
		? darkValue
		: lightValue;
}

This gets at the core of what makes creating system-aware toggles so easy now. We can just tell the browser we don’t support a certain color scheme in some conditions! That’s exactly how the color palette for this site works:

:root {
	color-scheme: light dark;

	--some-color: light-dark(#f00, #b44);
}

:root[data-color-theme="light"] {
	color-scheme: light;
}

:root[data-color-theme="dark"] {
	color-scheme: dark;
}

This alone is about 90% of a working implementation. If you take nothing else from this article it should be this: light-dark() is real, and strong, and it’s my friend.

Creating a Selector

While you could make a group of <button> or <radio>s to actually allow the user to update their preference, I went with the element that is named after the verb the user will be taking: <select>.

<label for="color-theme-select">Select color theme</label>

<select id="color-theme-select">
	<option value="system">System</option>
	<option value="light">Light</option>
	<option value="dark">Dark</option>
</select>

Once the markup is in place, updating the color scheme when the user changes the value of the <select> is simple:

const $colorThemeSelect = document.querySelector("#color-theme-select");

$colorThemeSelect?.addEventListener("change", (event) => {
	const nextValue = event.currentTarget.value;

	document.documentElement.dataset.colorTheme = nextValue;
});

Note that even though I have a "system" value in my <select>, I don’t have to worry about it messing up any styles by setting the data attribute, since :root and :root[data-color-theme="system"] would function identically. If you wanted to clear the attribute instead, that’s also a valid approach, though some of the rest of the code would need to be tweaked.

That’s enough for a basic toggle, but now loading in new pages or refreshing will always revert to the default system color theme. To fix that, we’ll want to store the result of each change somewhere. Since this is a static site, I’m doing so in localStorage, but a cookie or database entry may work better for dynamically rendered sites.

const $colorThemeSelect = document.querySelector("#color-theme-select");

$colorThemeSelect?.addEventListener("change", (event) => {
	const nextValue = event.currentTarget.value;

	document.documentElement.dataset.colorTheme = nextValue;
	localStorage.setItem("color-theme", nextValue);
});

Now that we have the value stored, we need to update the document on page load:

const defaultTheme = "system";
const storedTheme = localStorage.getItem("color-theme");

document.documentElement.dataset.colorTheme = storedTheme ?? defaultTheme;

Be sure to put that script in your <head> to avoid any flashes of unwanted color. If you’re dynamically rendering the page, this is where storing the value as a cookie/in your database comes in. You can read the value and apply the appropriate data-color-theme attribute to the root <html> element before the browser even gets the document.

We might as well also set the default value on our <select> so the correct option is checked. Unlike setting the color theme on the document, this can happen after the initial parse/paint since it’s unlikely a user will be able to interact with the selector faster than the script parsing/execution. You can place it right next to your change handler.

const $colorThemeSelect = document.querySelector("#color-theme-select");

if ($colorThemeSelect) {
	$colorThemeSelect.value = storedTheme ?? defaultTheme;
}

$colorThemeSelect?.addEventListener("change", (event) => {
	const nextValue = event.currentTarget.value;

	document.documentElement.dataset.colorTheme = nextValue;
	localStorage.setItem("color-theme", nextValue);
});

The last detail is to only display the select if the user can actually interact with it. Did you know they added a scripting media query to CSS? Me neither until earlier today.

@media (scripting: none), (scripting: initial-only), print {
	#color-theme-select,
	label[for="color-theme-select"] {
		display: none;
	}
}

Wrapping Up

The first couple of times I built color toggles were painful. They relied on heavy and slow CSS-in-JS solutions and often resulted in a blinding version of FOUC where the light theme would flash before correcting into the dark theme. By leaning into modern (and well suppoorted) CSS features, we no longer have to make any trade-offs between user experience and developer experience. It’s a reminder that the web is a constantly improving platform, and just how exciting that can be.

The Tokens Are the System

Tue, 15 Dec 2020 00:00:00 GMT

Let’s pose a hypothetical.

At work, you are tasked with creating a new view within the company’s application. Luckily your company has an established design system library (DSL), so you should be able to speed through the UI part of the task. But this new view introduces a component not covered by the library. You’ve talked with design, and they agree it’s an oversight, but necessary for the view. Or they acknowledge the inconvenience but point out it’s a one-off. In either case, this view cannot wait for the creation of a new component in the library. How do you solve this dilemma?

That Wasn’t a Hypothetical

That’s right. I tricked you. That exact scenario has happened to me (and a lot of other developers, I’m certain) many times using both third-party and in-house DSLs. The answer is dependent on the team and on the library’s engineering. Sometimes design provides redlines for these one-offs. Sometimes you’re left on your own, and you need to scrounge around in source code to find color, spacing, and other values. Sometimes these values are defined in a design token map. Sometimes they’re exposed as Sass variables or CSS custom properties; sometimes the library has a Box component.

In truth, how we solve this particular hypothetical isn’t very important. What is important is remembering that it isn’t a hypothetical at all. This situation will arise.

Also worth keeping in mind is that the problem isn’t only applicable to one-off components. Spacing is often (rightfully) left to the developers consuming the library, but incongruent spacing can have a dramatically negative impact on how the UI feels. How ever the developers approach the one-off component, they will approach these smaller problems the same way.

Designing a System

Taking this quote-unquote “hypothetical” into account when creating our own DSLs is very important. Recall how I said the solution is dependent on the library’s engineering. Think through how your users would approach this problem with the tools you’ve given them. Have you exposed enough tokens to them for them to create their own view- or application-specific components that are harmonious with the rest of the system? How easy, how obvious is it for them to use the tokens? (Also important: have you documented your design tokens?)

There are many ways to solve for this, some of which I’ve mentioned above. While I have my preference as both a library author and consumer – Box components are very good – I ultimately only care that the DSL makes my job quicker & easier while also improving the consistency of the UI. Whether that means the library ships with a customized Tailwind config, a design token JSON file, or some other solution I’ve yet to come across is immaterial.

I just want to create that damn component.

Styling Links for Print

Fri, 03 Jul 2020 00:00:00 GMT

A few weeks ago, amid the ongoing COVID-19 pandemic, my apartment building left a note in my mailbox. Among the helpful information and polite requests to wear masks in shared areas, I noticed a piece of text that had a very familiar style. It was blue, and underlined, and seemed to hint at a missing piece of content. In short, it was a link. Of course, this being a printed piece of mail, the link wasn’t much help to me. And, while this note was certainly a Google Docs or Word document, it made me think about the way links are styled on the web.

While people aren’t printing out websites at the same volume they used to, print styles are still very important. Modern browsers use these styles when saving a page as a PDF, for example. The problem is that links in this context are not always clickable. But with a little CSS we can ensure the user is always shown the URL the link points to:

@media print {
	a:link[href^="http"]::after {
		content: " (" attr(href) ")";
	}

	a:link[href^="/"]::after {
		content: " (https://mywebsite.com" attr(href) ")";
	}

	a:link[href^="#"] {
		text-decoration: none;
	}
}

This CSS takes advantage of the print media query to set special styles on links in that context. Specifically, we are creating a psuedo-element on links that begin with http (absolute links) and / (root-relative links). The content of those elements is set to the link element’s href attribute using the attr function. As a bonus, we also remove the link-styling for anchor links, since those have no practical purpose in print contexts.

Of course this isn’t an advised solution to every link, but it is particularly useful for blog posts, technical documentation, and any content that a user might want to save to refer to later. Printing websites not be a common occurrence anymore, but setting print styles absolutely should be.

No Red Squigglies For Semicolons

Wed, 04 Dec 2019 00:00:00 GMT

Us developers are an opinionated bunch. We share our opinions wide and loud through blog posts, tweets, talks at meetups, in meetings. The tenacity with which we hold these opinions seems to have an inverse correlation with their impact, and nowhere is this strange dichotomy more present than in stylistic choices. Should we use tabs or spaces for whitespace? Should we use semicolons or not? Single quotes or double quotes?

Collectively, these stylistic choices are known as bikeshedding. Thousands of words have been written about how we should be painting our bikesheds. We have many tools to help us paint the bikeshed. But, truth be told, I don’t care much about what color the bikeshed is. What I do care about is my code editor’s linting extension putting a red squiggly line under a function declaration because there’s a space between the name of the function and its parameter list.

Linters Are For Code Quality, Formatters Are For Style

Linters are incredible code quality tools. They enforce best patterns and can help catch bugs well before our code makes it to a browser. But they are ill-equipped to handle issues of style. Attempting to use an undefined variable is a bug, and your linter should point this out to you. Using single quotes instead of double quotes, on the other hand, will not impact your code’s logic or ability to run. As such, your linter should not care about this issue. At the very least it should not interrupt your work to tell you about it.

Formatters are a different kind of tool altogether. They care only about enforcing a consistent style and rarely (if ever) give real-time feedback. Instead, they wait until your work is at a safe stopping point to run: when you save a file, when you commit, or when you explicitly tell the formatter to run. Because of this, they are much less likely to introduce friction into your workflow.

In the JavaScript world the most used linter is ESLint, and the most used formatter is Prettier. They’re what I use across my projects. Unfortunately, many popular ESLint configs include strict enforcement of stylistic rules. Recognizing that conflicts between the two tools would arise, the Prettier team created eslint-config-prettier. The aptly-named ESLint config turns off any rules that conflict with Prettier, giving it full dominion over all issues of style. Using it allows us to keep the code quality benefits of our linter, only without those pesky bikeshedding errors.

If You Have to Remember To Do It, You’ll Forget To Do It

The workflow friction does not stop with squiggly lines, of course. If your setup relies on you to remember to run a linter or formatter (or test suite) against your code, you will forget to do so. Probably not every time, maybe even not most of the time, but definitely some of the time. This is especially true when working in a shared codebase: we can’t be sure all members of our team have the same linting & formatting extensions installed, that those extenstions are configured the same way, or be sure our teammates will remember to run those tools manually. Instead, I find it better to set these tools up to run with Git hooks.

Git hooks allow us to run arbitrary commands when performing a Git function; they allow us to run scripts before or after committing or pushing or pulling. While possible to set these hooks up manually, tools like husky make setting them up much easier. I also often use a tool called lint-staged to lint & format only those files staged for commit. This makes the process much faster, and ensures that no extraneous files are included in a commit.

Combined with removing bikeshedding rules from your linter, introducing a formatter and setting up Git hooks will remove a fair amount of friction from your code writing process. Setting these tools up — ESLint, Prettier, husky, & lint-staged — are among the first things I do in any new JavaScript project. I highly recommend giving it a shot.

On Declarative Styling

Fri, 19 Jul 2019 00:00:00 GMT

The enemy of art is the absence of limitations.

Orson Welles

There is a problem at the heart of CSS. It’s not the cascade, or specificity, or inconsistencies between rendering engines – though these things can be annoying. No, it’s much simpler than that: the problem is that we can write too much of it.

I am not talking about append-only stylesheets (though these too cause their issues). Even if we’re extremely disciplined about refactoring our CSS, and we only add new rules when absolutely needed, something is still wrong. The problem is the flexibility of the language itself. There are nearly unlimited valid values that a padding declaration can take, and while extremely freeing this also introduces surface area for inconsistencies in our designs. And consistency is key to good design! It reduces the end user’s cognitive load, it (generally) looks better, and it minimizes the workload for designers & developers to boot.

Artificially limiting the number of values that we can use in declarations is key to avoiding these inconsistencies. We want a declaration like padding to act a little more like float; we should only be able to set a value that we’ve defined in our governing system. There are many techniques and technologies that can help us accomplish this (or at least get us close). I call the overarching concept that these tools encompass “declarative styling”.

Defining “Declarative”

This term – declarative styling – is derived from the computer science concept declarative programming. It means we want to tell the computer the rules for drawing our interface, and let it follow those rules for us. We no longer want to write padding: 1rem, we want to write something like padding: 3 and have the computer replace the 3 with the 3rd value in our spacing scale.

This accomplishes several things for us. It ensures consistency across our design by allowing us to use a reference rather than a specific value. It also reduces the cognitive load for stakeholders by providing a common language to communicate in. These factors (among others) can make designing and iterating faster, and all but eliminate the inherent friction in designer-developer handoff.

Design Tokens

Those familiar with the concept of design tokens may find a lot of conceptual overlap here. Design tokens are an essential part of declarative styling: they are how we define our custom subset of styling options. If a rule in our stylesheet declares a background-color, that swatch should be found in our tokens.

There are many techniques for storing and parsing design tokens. I’m partial to the JSON-based System UI theme specification, which organizes our tokens into a variety of scales. Several of the tools discussed below rely on this or a similar technique, but the concept remains the same: there should be a source of truth for these values, and it should not be the CSS rule itself.

Techniques

Much like there are a multitude of ways to store our tokens, there are many, many ways to apply them to our styles.

CSS Variables

The most commonly-used solution, and one you’re likely familiar with, is to use variables whenever possible. Although Sass and LESS have had variables since their inception, CSS now has native variable support with the custom properties specification.

.box {
	padding: var(--spacing-3);
}

Unlike the variables of preprocessors like Sass and LESS, custom properties can take full advantage of the cascade. This means we can create fully themeable component styles natively.

.btn {
	/* First we define our variables in the base component style */
	--button-padding-y: var(--spacing-2);
	--button-padding-x: var(--spacing-3);
	/* Then we apply our variables to our declarations */
	padding: var(--button-padding-y) var(--button-padding-x);
}

/* By updating our variables, the styles will change automatically */
.btn--large {
	--button-padding-y: var(--spacing-3);
	--button-padding-x: var(--spacing-4);
}

To take full advantage of this system, we need to convert our tokens to custom properties in the :root selector. The easiest way to do this is to copy and paste the values by hand, though there are tools to automate the process.

Of course, no method is without a downside. In this case, the biggest flaw is the same as its biggest draw: the low barrier to entry. There are no guardrails to stop you from writing padding: 24px instead of using your variable. It takes a lot of discipline to not deviate from the system, and any time you’re writing new CSS is an opportunity to create a discrepancy. But combined with a strict code review process, this can be a powerful way of enforcing consistency while creating a themeable system.

Atomic CSS

Atomic CSS (aka Functional CSS, aka Utility-first CSS) libraries like BassCSS, Tachyons, and Tailwind CSS are declarative by definition. Classes like p3 automatically follow our padding rule from above: we’re telling the engine to apply equal padding to all sides (the p) using the third step from our spacing scale (the 3).

<div class="p3">Hi</div>

Customizing BassCSS and Tachyons can be tough, but it is possible. Tailwind, on the other hand, is fully customizable by default. The Tailwind configuration system is a plain JS object exported from a Node script. A major benefit to this approach is that we can read our tokens from a JSON or YAML file, and apply them to our custom config with a few lines of code.

I’m on the record as being a big, big fan of atomic CSS. But I’m not blind to the disadvantages. The learning curve can be quite steep; not only do we need to internalize the naming scheme, but we also need to rethink how we apply our CSS. Because we also need to apply a fair amount of classnames to our components, I also tend to recommend this approach only for very simple projects or for projects that have a powerful templating system. Applying atomic CSS classes to a React component or Pug mixin makes applying the classnames to our elements much more palatable.

Styled System

The advent of CSS-in-JS has presented us with a unique opportunity: by taking advantage of an expressive, fully-featured programming language, we can create abstractions on top of CSS that would otherwise be impossible. For example, by taking the lessons learned from atomic CSS and applying them to a JSX-based CSS-in-JS system, Brent Jackson has created several purpose-built declarative styling libraries.

The first of these libraries, the foundation upon which the others are built, is called Styled System. The library provides a consistent interface to refer to your design tokens when defining or consuming a component. The true genius of Styled System is how it handles responsive styles. By default, Styled System props accept a string, which the library parses and converts to a value represented by a design token. If the token is not found, the literal value is passed to the underlying CSS-in-JS library. However, by passing a prop an array, it will apply the 0-index value to the component by default, the 1-index value to the component at the first breakpoint, and so on and so forth.

import styled from "styled-components";
import { space, color } from "styled-system";

const Box = styled.div`
	${space}
	${color}
`;

const MyStyledSystemComponent = (props) => (
	<Box p={[2, 3]} color="primary" {...props}>
		Hi
	</Box>
);

This approach allows us to not only create components that are not only consistent with our system, but are extremely portable as well. A rule of thumb I try to follow when styling a component is to only define surrounding vertical margin when the component is actually consumed in a view. By spreading our props to a root component defined with Styled System, it becomes trivial to follow this rule.

const MyView = () => (
	<main>
		<header>...</header>

		<MyStyledSystemComponent my={4} />

		<footer>...</footer>
	</main>
);

Because Styled System (when used in React) reads from the theme put into context from your CSS-in-JS library of choice’s ThemeProvider, creating themeable components is a breeze. However, attaching space, color, and other token references to all your components can be quite annoying. Luckily, Mr. Jackson has also created a library of primitive components built on top of Styled System called Rebass. These components operate like the Box component we utilized inside of MyStyledSystemComponent.

Most recently, Brent has released Theme UI, a further iteration of this idea. Theme UI exposes an sx prop on JSX components that allows us to reference our tokens, provides primitive components to use as a foundation, handles styling of markdown content with MDX, and much, much more. It’s an exciting evolution of the approach, and one I intend to explore more fully in the future.

The Styled System approach, much like the others, comes with its fair share of downsides. For starters, it shares the same learning curve problem as atomic CSS. It can be somewhat cumbersome to set up, particularly when not using Rebass or Theme UI’s primitive components. And while it can technically work with any framework that supports JSX, React is the only true first-class Styled System citizen. But, when given a choice, it is still my preferred method for defining and consuming styles.

A Vision of the Future

The web has always been an extremely flexible and expressive platform. This has lead to some amazing creative applications of technology, new media experiences, and beautiful interactions. It has also created plenty of footgun opportunities. By placing self-imposed constraints on the very fabric of the web, we get to remove the more self-sabotaging aspects of designing for the platform. Rather than limiting our creativity, these constraints provide guardrails for us to explore the limits of our designs while providing a consistent and visually harmonious interface to our users.

The declarative styling methodology will continue to evolve over time. As design tokens become more prevalent, design software will add first-class support for them. More libraries and methods will evolve for applying them to our products, both on the web and beyond. As we solve the problem at the heart of CSS, the language we use to communicate between ideation and implementation will meld into one. Perhaps our tools will as well.

Request Timeouts With the Fetch API

Sat, 30 Mar 2019 00:00:00 GMT

I’m a big fan of the Fetch API. I use it regularly in all sorts of projects, including this site and the API that powers the stats on the about page. However it isn’t always as clear how to do things like error handling and request timeouts as it is in libraries like Axios.

If you’re not familiar with fetch, it’s a native API that massively simplifies making AJAX requests compared to the older XHR method, and it’s supported in all modern browsers. When it initially landed, however, there was no easy way to handle request timeouts. You could fake it with Promise.race or by wrapping your fetch in another Promise, but these solutions don’t actually cancel the request. This is where AbortController comes in.

AbortController is an API that, much like its name and my previous sentence suggests, allows us to abort (cancel) requests. Though browser support isn’t wonderful at time of writing, it can be used in most modern browsers and polyfills are available. The API itself has a very small surface area: a signal property to attach to request objects, and an abort method to actually cancel the request. Because the API is so simple, it’s very flexible – Jake Archibald has a fairly in-depth article on the Google Developers blog going over various cancellation scenarios, as well as the history behind the API, and I highly recommend giving it a read.

With AbortController, it becomes trivial to cancel a request if it doesn’t resolve before a given period of time: if the abort method is called before the request resolves (or before the response Body is consumed), the request is cancelled; if it’s called after, the browser just ignores the call. To put it all together, we need to:

Create an instance of AbortController
Create a setTimeout function that calls the controller’s abort method
Pass the controller’s signal to fetch’s options object

Putting It All Together

First, because we’re basically writing a shim around fetch, I’m going to add an extra little perk. If the response doesn’t return in the 200 range (that is, if response.ok evaluates to false), we’re going to throw an error. We absolutely do not need to do this – we could just catch our timeout and the function would work the same (we actually don’t even need to do that). However, I always perform this check anyways, so this removes a lot of boilerplate code for me.

Anyways, here is my generic fetchWithTimeout function. It should work in any environment that supports fetch and AbortController.

const fetchWithTimeout = (uri, options = {}, time = 5000) => {
	// Lets set up our `AbortController`, and create a request options object
	// that includes the controller's `signal` to pass to `fetch`.
	const controller = new AbortController();
	const config = { ...options, signal: controller.signal };

	// Set a timeout limit for the request using `setTimeout`. If the body
	// of this timeout is reached before the request is completed, it will
	// be cancelled.
	const timeout = setTimeout(() => {
		controller.abort();
	}, time);

	return fetch(uri, config)
		.then((response) => {
			// Because _any_ response is considered a success to `fetch`, we
			// need to manually check that the response is in the 200 range.
			// This is typically how I handle that.
			if (!response.ok) {
				throw new Error(`${response.status}: ${response.statusText}`);
			}

			return response;
		})
		.catch((error) => {
			// When we abort our `fetch`, the controller conveniently throws
			// a named error, allowing us to handle them separately from
			// other errors.
			if (error.name === "AbortError") {
				throw new Error("Response timed out");
			}

			throw new Error(error.message);
		});
};

Using the function is fairly straightforward. Because we return fetch directly, we can use it in much the same way; the only change should be the addition of a third parameter (our time argument) and the extra error handling we discussed above.

// This example _always_ logs the error, because I'm telling httpstat.us
// to wait at least 1s before responding, but setting the timeout
// threshold to 500ms.
// Also, this could definitely be written in async/await if you preferred.
fetchWithTimeout(
	"https://httpstat.us/200?sleep=1000",
	{ headers: { Accept: "application/json" } },
	500,
)
	.then((response) => response.json())
	.then((json) => {
		console.log(`This will never log out: ${json}`);
	})
	.catch((error) => {
		console.error(error.message);
	});

That’s it. That’s the whole post. Though the snippet is ultimately pretty simple (it’s 20 lines without whitespace and comments) writing this provided me with three major benefits: it forced me to abstract the function to the most reusable version I could, it gave me an opportunity to research AbortController to make sure I knew exactly how it behaved, and it provided a place where I can come find this snippet in the future instead of rooting through old projects.

A Better Album Ranking Algorithm

Mon, 12 Mar 2018 00:00:00 GMT

Years ago, I deleted my Last.fm account, because it felt like a dying social media network. Months ago, I created a new one, because Last.fm is a treasure trove of behaviorally generated personal data. It’s a lovely service for a developer to have around for side projects, as it provides instant and easy access to a large dataset with a particularly personal connection if you’re a music lover. In the process of using it for one of those side projects, I found a dark & disturbing secret: Last.fm actually kind of sucks for tracking album plays.

Fair warning: things are about to take a turn for the opinionated, pedantic, and downright trivial.

The Scrobble Killed the Record Star

Last.fm is built upon an atomic unit: the scrobble. From it, all other units are derived. A scrobble represents one play of one song, and Last.fm sets your top album by how many scrobbles it has. The problem with this is that it’s the complete wrong way to count album plays.

Album play counts are slightly different than song play counts. They should start from basically the same place – one playthrough is one playthrough – but from there they branch in subtle but important ways. For example, it is much more common to only partially listen to an album than it is to partially listen to a song. Albums are also, generally, between 10 and 12 times longer than songs, and broken into as many parts.

If the length of an album is what makes a complete playthrough of an album rarer than a playthrough of a song, a playthrough of a longer album should count for more than that of a shorter album. (There’s an argument to be made that the same is true of songs, but we’ll leave that for another day.) Thus, the ideal album ranking algorithm would account for total playthroughs, with a weight given to longer albums. Maybe even something as simple as this:

albumPlaythroughs * (1 + albumDuration / 2700);

Here, we weight the duration in 45 minute increments, the length of a single LP (albumDuration being in seconds). Adding 1 to the duration calculation helps to ensure we’re not simply normalizing for record length – while that is also a valid way to rank album plays, it is not the one I prefer.

Ok, You Got Me. Something Exactly As Simple As That

Let’s take three albums of varying lengths and see how they handle this algorithm. Our albums:

[
	{
		"name": "Cardinal",
		"artist": "Pinegrove",
		"duration": 1845
	},
	{
		"name": "Marquee Moon",
		"artist": "Television",
		"duration": 2754
	},
	{
		"name": "Summertime '06",
		"artist": "Vince Staples",
		"duration": 3545
	}
]

Given one playthrough each, the three records will be ranked in exactly the same order they are now. Let’s listen to a few more tracks.

const cardinalRank = 3.5 * (1 + 1845 / 2700); // 5.89
const marqueeRank = 3 * (1 + 2745 / 2700); // 6.05
const summertimeRank = 2.5 * (1 + 3545 / 2700); // 5.78

Now we’re getting somewhere. Even though Cardinal has the most playthroughs, Marquee Moon has the highest rank thanks to its lengthier runtime. Summertime ’06 is just barely in third place despite having a full playthrough less than Cardinal. The system works, folks.

This Is the Part With the “But”

Given all the information we need, the algorithm works. But we still have to get the information, and unfortunately, Last.fm doesn’t make it too easy on us:

We can easily get a user’s top albums, but the response doesn’t include information on the amount of tracks on, or duration of, each album.
Last.fm doesn’t use unique IDs to track albums, so we have to use an endpoint that searches by album name and artist to get detailed album information. This often fails or retrieves the wrong album, even when the album name and artist are provided by Last.fm (like from the previously discussed endpoint).
Once we find an album, track listings are missing or incomplete about 20% of the time. This happens more often with newer albums.
Neither the top albums nor album info endpoints give us the album’s release year. This doesn’t impact the algorithm, I just thought it was odd.

All told, to implement this algorithm on our own means we would have to make an insane amount of requests just to get incomplete or missing data. If you think that doesn’t sound like it’s worth it, you’re right. And while I didn’t use it, you can see an implementation here.

Last.fm still ranks albums wrong, though.

Customizing Tachyons

Mon, 27 Nov 2017 00:00:00 GMT

Tachyons, if you haven’t heard, is incredible. It’s often called an atomic (or functional) CSS library, but if you spend enough time with it, you come to realize it’s something else entirely: a powerful and expressive framework for defining and consuming design system primitives.

The problem, then, is that not every design system will use the same primitives. While Tachyons has some great default settings to help you achieve just about any design you please, you often need to tweak some of those properties: a different color palette, or type scale, or you have sizing needs outside of the scope of the defaults. How should you go about customizing this CSS file that has nearly every property:value pair in CSS?

K.I.S.S., Stupid

The simplest solution is the most oft-overlooked: just frickin’ copy the files into your project and start hacking away. The good folks over at Tachyons HQ even cooked up a CLI so you don’t have to goof around with a build process.

Get Sassy

Sass has come to be the defacto CSS preprocessor. It brings a bunch of goodies to CSS: nesting, functions, and of course, variables. This makes it a great way to consume and customize libraries. And wouldn’t you know it, there’s an official Sass fork of Tachyons ready to be brought into the fold of your Sass projects.

Deliver Some Packages

Did you know that nearly every Tachyons module is available independently on npm? If you only need to customize a few of them (like, say, the typography scale), you can simply replace the default modules for your custom ones. The downside to this is that you have to import every single module you want to use into your project, but the folks over at Egghead don’t seem to mind.

It’s Your Property, Do What You Want With It

Much like Sass before it, CSS itself is getting variable functionality (and browser support is pretty good too). Wouldn’t it be great if Tachyons used this new syntax to define all of the properties we’d like to update? Meet tachyons-custom, who I’m sure you saw standing just off stage-right over there. Simply include it in your project, and because CSS custom properties follow the cascade, any of your variables will overwrite the Tachyons defaults.

Generate the Future, Today

Tachyons HQ is hard at work developing a Tachyons Generator. This tool allows you to describe your Tachyons variables in JSON and have a full-on version of Tachyons spit back out at you. This is the tool I am most excited about, because it has the potential to completely automate all of the other customization options we just went over while also being more expressive and powerful. And that’s a beautiful thing.