blog.damato.design

62.5%

Mon, 30 Jan 2023 00:00:00 GMT

Pixels are an absolute unit, they are expected to represent a fixed size and aren’t affected by outside factors (sort of). While this sounds like a good thing for design because you can be be sure of the dimensions, the reality is that using pixel values in the web hinders user experience. Layouts become unresponsive, translated content becomes unreadable, and accessibility preferences just aren’t considered. In most cases, we want to avoid absolute units and instead use something more flexible that adapts to the needs of the layout.

Relative units are related to something else. An example of a relative unit is percentage and relates to different properties based on where it is used. The rem is a relative unit which roughly represents the size of the letter “M” in the document. If the document font-size changes, all areas where this unit is used will also change. The root font-size can change based on user preference; usually increasing to help folks with vision impairment. There is a not insignificant amount of the population who leverage the ability to change the font-size in user settings so we want to ensure this feature of the web is maintained in our experiences. It’s possible to check this out for yourself.

Hocus pocus

There was a trick by Richard Rutter discovered many years ago which was meant to help folks better understand relative font-size units when coming from pixels. The trick is to set the font-size of the document to 62.5%.

html {
    font-size: 62.5%;
}

The 62.5% looks like what we like to call a magic number; it seems oddly specific. The number is the ratio 10:16 as a percent. The default rem is 16 pixels, so 1/16th of a rem equals one pixel. Multiplying by 10 helps keep the font size somewhat readable (6.25% is too small, 625% too large). Then the final use of this declaration allows for the following:

button {
    padding: .8rem 1.6rem; /* 8px 16px */
}

Here, it is possible to write rem in terms of pixels. This provides the benefits of rem while maintaining a pixel mental model. This post by Aleksandr Hovhannisyan goes into the approach in more detail also mentioning accessibility considerations. Some design systems (eg., Workbench by Gusto) use the approach to make it “easier” to work with rem units. So what is so difficult that warrants this approach?

The fact is that the rem doesn’t exist in design tools, so a translation from pixels to rem must occur for an inclusive web experience. Before this approach, designers and engineers would need to figure out what the final rem number should be based on a formula. Then they would potentially need to repeat that formula every time a new size was needed. In other words, math is hard and to repeat that math is a waste of time. It is “easier” for the translation to occur once globally.

So why would Jeremy Keith say the following about the author and the approach nearly 20 years later?

Not that he—or anyone else—would recommend it these days!

— Jeremy Keith

Absolutely arbitrary font-size

Toheeb Ogunbiyi does a deep dive into the 62.5% approach and has some opinions about thinking in pixels:

Thinking in pixels makes it easy to do the following:

Translate UI Design to code.

Read the code in the editor.

Troubleshoot the code in the browser.

This ensures a better development experience. In addition, the mental model is maintained across the team.

— Toheeb Ogunbiyi

What if I said that mental model being maintained is baseless artifact of legacy computer graphic design? 😱

When you select a pixel font-size, what does it mean? More specifically, what is the difference between Courier and Verdana at 16px? In practice it’s meant to represent the em square. In the harsh reality, it doesn’t really mean anything. That means we could use 16 pigs, or 1 barn, maybe 8 tulips to talk about font-size if design tools were prepared to use these units. It actually doesn’t matter as long as the visual result is expected. That’s what we are really doing when curating font-size. We are tweaking some input and assessing the visual output. When we get something that Looks Good™, we record what the tool says in the input to repeat the visual style in digital media elsewhere.

So why do we need to use the pixel value so much? It’s because that’s what design tools have decided to use to define the font-size among other computer graphic properties. If the design tool was to include the rem as an option, we would have a 1:1 relationship between the design expectation and the engineering execution and no need to require this translation at all! You could speak in terms of rem right in the tool; no math required. The design tools are the problem and this “solution” is a community hack for a missing feature.

Subverting expectations

When the font-size value is redefined at the html element, the representation of the rem is changed for the entire document. This means that third-party elements could look incorrect; designed with the rem to expect the browser 16px default. This even includes usage of rem in the Shadow DOM. Josh W. Comeau calls this out:

There’s a baseline assumption on the web that 1rem will produce readable text. I don’t wanna mess with that assumption.

— Josh W. Comeau

He also mentions that adoption is difficult because it would need to be done all at once. There’s no possibility of incremental enhancement. This also means that deprecating the approach is also troublesome. So you need to be very sure in this decision, more than most others.

Back to base

So instead of thinking in terms of pixels for font size, think in terms of a base (or root) size. What is the font size that is most used in the document? This is most likely your body copy. That should be what the rem represents and exist as the base. Next, any font-size that you want to set past this should be some proportion from the base. How much larger do you want the headline to be from the base? 1.5x larger? 2x larger? 2.5x larger? Guess what, that’s rem! If you’ve set your headline to be 2.5x times larger than the base, that’s 2.5rem.

h1 {
    font-size: 2.5rem; /* 2.5x times larger than your base (root) font-size */
}

If the user zooms the content, that relationship is maintained. This is what Andrés Galante says in his article “Accessible Font Sizing, Explained” at CSS-Tricks:

Think about proportions, not size

— Andrés Galante

While it’s recommended to not update the font-size at html and maintain the default expectations, setting the size here isn’t all bad as long as it’s made accessible. Just recognize that it does affect all use of rem throughout the page where this rule is applied. So reverting this approach later is an exercise of auditing all pages where rem is used and updating the values where appropriate. For large applications and systems, this could be a monumental task. However, if you’ve kept in mind that the rem is relating to the font-size in the usage, it might not be a difficult change. It might even be a feature of the approach. Though, if you use rem as just another unit because someone said it’s better without understanding why, you might end up fighting rem.

Don’t dislike rem because you don’t understand it, dislike pixels because you do.

Accent Color

Tue, 10 Jun 2025 00:00:00 GMT

The concept of an accent color occurs in modern web design often, especially in minimalistic compositions of black and white. The accent color is typically used to start drawing attention to important elements and tie in with the beginnings of a brand expression. We often see this manifest in rudimentary token systems that might include something like $accent-color such that this color can be changed to affect an overall mood where appropriate.

In fact, this very blog uses this approach on each of the articles to indicate how spicy a particular topic is. This is an easy way to keep the overall look of a site consistent across pages, while giving individual pages their own personality.

`accent-color`

Recently, we received a CSS property called accent-color, which is made to affect the color provided by the user-agent and operating system with one provided by the brand through a stylesheet:

input[type="checkbox"],
input[type="radio"],
input[type="range"],
progress {
    accent-color: hotpink;
}

This will update the color of some user-interface controls to hotpink in browsers that support it. This helps convey a consistent brand easily without needing to provide customized controls which might require a lot of reimplementation. Unfortunately, due to the spotty support, teams continue to resort to custom controls to properly convey their brand with custom colors.

`AccentColor`

Where accent-color is a method for a web designer to set a color for user-interface controls, the AccentColor keyword is a method for a web designer to get the current color given to user interface controls… sort of.

At the MDN page for system color, you’ll find other keywords on the page that are meant to provide default color choices for a web page. As an example, the VisitedText is the purple we’d see as the default color for visited links.

If you scroll to the bottom of MDN for the Browser compatibility table, you might find something strange:

AccentColor (and AccentColorText) are called out as not supported in many browsers in comparison to the rest of the list. What’s up with that? The answer: Privacy.

Fingerprinting

The introduction of AccentColor into browsers begins here in 2022 and everything is going fairly smoothly until August 2023, where Joey Arhar, a engineer working on the Chrome browser for Google, leaves a comment suggesting that implementing this feature could present a new “fingerprinting” vector. This spawns a totally new and separate discussion about Mitigating fingerprinting for AccentColor/AccentColorText bringing the original discussion to a halt over these concerns.

So what’s all of this about fingerprinting? Here’s what web.dev says:

Fingerprinting means trying to identify a user when they return to your website, or identifying the same user across different websites.

The idea is that identifying the color assigned to AccentColor for your device could be a data point in a larger collection that would specifically identify you (or more specifically your device) such that scripts could follow you from site to site. You might see how this could be used from an analytics point-of-view, where you could follow the path of a user from an advertisement all the way to a purchase flow. However, this could also be used in a digital surveillence capacity. Scripts could collect data about a target’s device and then identify how that device travels between collaborative or infected sites.

This is the reason some of the properties that were once introduced at window.navigator are now marked as deprecated. It is because they offered too much information that could be used for fingerprinting. If your code is depending on the type of browser or device, it’s possible this is no longer reliable. Instead, you should modify your code to use feature detection instead.

Importantly, the real problem isn’t the color but the value that the color represents. There’s no problem with displaying the color to the user. The problem arises when some code attempts to read the value of the given color which could be used as a data point. That’s why the newer discussion considers returning static values for when the color is meant to be retrieved, such as using getComputedStyle() in JavaScript or if the color was to be rasterized to an HTML <canvas/>.

What isn’t clear yet is how the keyword might work with CSS color-mix() and this is why I’m heavily interested in the outcome.

Personalization

In my most recent work, I speak about the concept of influence. This means instead of an organization curating tokens precisely, I recommend looking into the idea of influencing existing values with some brand expression. In this way, we don’t specifically say that $body-bg is exactly #ffffff but instead we influence the given color with ours by some amount. What is the given color? In my opinion, it’s the color chosen by the user. How it is chosen can be a separate topic altogether but consider this; imagine if we could support light and dark mode simply by saying “#66ff22 is our brand color” and let the system figure out the rest.

Here’s a practical example: let’s say I’m trying to convey the brand of Home Depot with their signature orange #ee7125. Instead of going through all of the tokens, for both light and dark mode, what if instead I only provide this one color and let modern color functions and system colors fill in the rest?

body {
    /* Set our brand color */
    --brand-color: #ee7125;

    /* This is needed for system colors to work */
    color-scheme: light dark;

    /* Use color-mix to influence the system color */
    background: color-mix(in oklch, Canvas, var(--brand-color) 5%);
    color: color-mix(in oklch, CanvasText, var(--brand-color) 5%);
}

This would tint the background and foreground colors with the --brand-color by 5%. Importantly, the color supplied by Canvas and CanvasText is supplied by the device and browser depending on the user’s settings. As an example, in light mode, we’d expect Canvas to be a light color. Importantly, you cannot be sure what this color keyword is exactly. As a reiteration, this means we aren’t choosing the color for the background and foreground directly, but we are influencing what is given by the user’s choices with our own orange brand.

Ultimately, I’d like to see system colors that were closer to the concept of intents. Though I’ve found some sensible replacements in most cases. You can see some of this in action at my system playground.

There’s lots of opporunity for this to fail unfortunately but I believe there’s also opportunity for this to succeed. A user can be responsible for the appropriate general presentation either actively (heyo hot dog stand 🌭) or passively (maybe learning user activity). While we influence that presentation slightly with our own branding. This needs more experts, especially ones who work with color, to figure out best practices over time.

Folks that are used to providing highly curated values for their experiences are going to feel uneasy with this. But for those who truly put the user first, we can lessen the emphasis on choosing color and redirect our efforts to providing a better overall experience.

Against atomic design

Wed, 25 May 2022 00:00:00 GMT

Atomic design as an idea I agree with; parts of your system are built from smaller parts. What I don’t agree with is the image that has been floating around the internet which introduces people to the concept:

If you think about this, how could an organism (a living thing) become a template (a non-living thing)? If you think I’m taking the image too literally; that’s the point. People around the design community have taken the naming convention provided by design as the standard and using it to communicate where something lives within the system.

So here’s a simple question, where would I find the dropdown component in this system? If you know about atomic design this is probably a molecule. If you don’t know about atomic design (perhaps like many engineers looking for a component), then it could be a molecule or an organism by process of elimination.

However, even if you know about atomic design the examples can also conflict. The canonical example of an organism in the original post is a masthead. However, the masthead could be a reusable template because the megamenu within the masthead could be a organism. The lines become blurry about what exists at each level even for folks who follow atomic design. There’s a lots of room for debate about what a particular part of the interface should be categorized as. That debate will only cause confusion and distract from the purpose of the idea.

So here’s the easy fix:

#naming-is-hard. The naming is what hurts the approach.

Definitions

I’m going to also include some definitions that I’ve developed while working with design system people and resources that might help bridge communications across disciplines.

Product teams: The group of individual contributors who are responsible for bringing product concepts to life; commonly comprised of designers and developers.
Patterns: Recommended, content-agnostic compositions that have not yet been formally named or packaged which are meant to host content, interactivity or feedback for product team use.
Components: Patterns that have been promoted to reusable packaged resources which simplify the options that the original pattern suggested using internal logic.
Fragments: Components only meant to be used to compose more complex components. These are not commonly used by members outside of the team responsible for them. An example might be a modal backdrop.
Local Components: Components meant to support a specific product or feature.
Universal Components: Components meant to support all products and features.
Layouts: Reusable compositions for visual arrangement; analogous to the use within artboards.
Templates: Reusable compositions for data arrangement; analogous to the use within database schemas.
Modules: Components populated and configured by people outside of product teams.

The reason we give names to anything is to share ideas. If the name doesn’t properly identify the idea in a repeatable way; it’s a signal that the name doesn’t support the idea well. My recommendation is to not take the atomic design system naming convention literally but instead to execute on the concept that an interface is a collection of increasing complex compositions. The naming used within the system should be developed so that it meets expectations for most introduced to the system and limits ambiguity.

Antidatalossconfigurationism

Tue, 08 Jul 2025 00:00:00 GMT

I’m in the middle of deep thought about what a text component looks like. There’s the easy stuff like having the ability to choose the appropriate semantic element. There’s the less obvious stuff, like adding a flag for screenreader only content. But then there’s something that we tend to overlook, how to manage overflow content.

Data loss

It’s not uncommon for someone to choose the solution of clipping the content, maybe in the form of an ellipsis. We even have more options coming about when those ellipsis appear. The problem with approaches that include overflow: hidden; is that the content is no longer clearly accessible. This goes against a core principle of mine: if you place it on the page, that means it is important. There should be no condition that obstructs that element in any way. Otherwise that can introduce data loss. Adding ellipsis is not an inclusive solution to large blocks of text. Instead, we’ll need to ensure the text remains readable while balancing the expectations of the layout.

Properties

There’s several CSS properties that are directly related to the way text flows on a webpage. We’ll go over each of the properties below but first a few definitions:

Whitespace refers to characters that provide space between other characters.
Segment breaks are characters that cause text to break onto new lines (eg., line feed).
Hard breaks (aka: forced line break) will always cause the text to break onto a new line, even if it is not necessary to do so.
Soft breaks will cause text to break to a new line only if necessary. Where these can occur are called soft wrap opportunities.
Line box describes the inline formatted box, typically used to contain text. The size of this box depends on the content and the available size of its ancestors.
CJK is short for Chinese/Japanese/Korean used to describe text that has a different ruleset for when strings are allowed to break.

`white-space`

This property has been around for a while, but recently it has been altered to host separate properties. Overall, this property and its related new properties are meant to handle how whitespace characters effect the surrounding text.

First, the white-space-collapse property has the following possible values:

collapse says that all whitespace should be collapsed. How whitespace is collapsed follows several algorithmic steps.
preserve says whitespace and segment break characters are perserved. This is commonly seen as the default in the <pre/> HTML element style.
preserve-breaks says only preserve segment breaks, whitespace characters are collapsed.
preserve-spaces does the opposite of preserve-breaks by allowing segment breaks to be collapsed and perserve whitespace as written in source.
break-spaces is the most unique of the values with a more specific set of rules for how whitespace is perserved.

Remember that white-space-collapse is only one part of the white-space property. The other part is text-wrap-mode which only has two values, wrap and nowrap. As you might expect, you’ll primarly want to have text-wrap-mode: wrap and this is the default.

When considering the keyword options provided by the original white-space property, it’s not immediately clear how they align to these values:

normal is white-space-collapse: collapse; text-wrap-mode: wrap.
pre is white-space-collapse: preserve; text-wrap-mode: nowrap.
pre-line is white-space-collapse: preserve-breaks; text-wrap-mode: wrap.
pre-wrap is white-space-collapse: preserve; text-wrap-mode: wrap.

`text-wrap`

To make things more confusing, text-wrap is also a shorthand. We already saw one of the properties text-wrap-mode which determines if the text is allowed to wrap or not. The newer part to this is text-wrap-style which has added many of the fancy algorithmic ways that text can wrap based on the number of characters. Here are the values for this property:

auto wraps the text in the most performant way and ignores the number of characters. This is the default.
balance attempts to wrap in away that keeps the number of characters roughly equal amongst the lines of text. This is best used for headlines.
pretty is similar to balance but favors layout over speed. This is best used for paragraphs of text.
stable is meant to be applied in areas where the user is editing content and wrapping should be kept to a minimum during this time.

Harry Roberts posted some benchmarks on using the newer text-wrap values. The setup was a page with 10,000 <p/> elements which, by default, have orphans. Here’s what he found:

Baseline – 1,186ms
text-wrap: balance: 1,224ms (38ms/3.2% longer)
text-wrap: pretty: 1,310ms (124ms/10.5% longer)

He said that impact on balance was almost zero, while pretty is more noticeable. The reality is that you most likely won’t have 10,000 paragraphs on your page.

The properties so far are only configuring how the whitespace characters behave in a block of text. None of these properties will affect the strings of characters that typically behave as words. The following properties are meant to target when these strings are meant to break and avoid poor layout artifacts.

`overflow-wrap`

The overflow-wrap property helps tell the browser when it should insert line breaks in otherwise unbreakable strings of text to prevent overflowing. This is an alias of the word-wrap property. Originally, this only allowed two values normal the default which keeps strings in tact and break-word which will break words sometimes. When a word is meant to break depends on the width of the container and where soft breaks can exist. This is usually very helpful for places where a long URL is written that needs to be broken to maintain a reasonable text layout.

The newer value option is anywhere which is typically less desirable as soft wrap characters are also used to determine how big the line box should be. This will allow the box to be much smaller instead of trying to fill the box as is normally expected.

`word-break`

Continuing with the theme of confusingly similar CSS properties, word-break is a property that determines what happens when a string would overflow outside of its container. To make things worse, one of the values here is an override to overflow-wrap. We’ll start with that one:

break-word is identical to overflow-wrap: anywhere and takes priority over any other value provided to overflow-wrap.
normal says to use normal line break rules which may also break between CJK characters.
break-all will cause a break to occur at the place where overflow would occur.
keep-all same as normal except CJK characters will also not break.
auto-phrase same as normal but analysizes the language to avoid breaking natural phrases.

A question you might have, what’s the difference between all of these properties? They all look like they handle the same sort of consideration for breaking strings of text. The CSSWG has an excellent breakdown of the differences:

The line-break property allows choosing various levels of “strictness” for line breaking restrictions.

The word-break property controls what types of letters are glommed together to form unbreakable “words”, causing CJK characters to behave like non-CJK text or vice versa.

The hyphens property controls whether automatic hyphenation is allowed to break words in scripts that hyphenate.

The overflow-wrap property allows the user-agent to take a break anywhere in otherwise-unbreakable strings that would otherwise overflow.

On top of the other properties that we didn’t cover, there’s a lot more detail within that page about how line breaks are expected to work. I’ve made a little playground to see how the properties would affect text samples combined from MDN examples:

See the Pen Antidatalossconfigurationism by Donnie D’Amato (@fauxserious) on CodePen.

Recommendations

Based on all of this, here’s how I’d try making an API for a text component when it comes to avoiding data loss. Here’s my considerations:

Create a wrap flag with the following values:
- (default) if the tag name used expects a certain text-wrap-style value, use that style. For example, balance for shorter text and pretty for longer text.
- true is the same as text-wrap-mode: wrap.
- false is the same as text-wrap-mode: nowrap.
Create a break flag with the following values:
- (default) sets overflow-wrap: break-word on text by default. This will allow the presence of long URL to break nicely when within the text. Josh Comeau includes this in his CSS reset.
- true is the same as word-break: break-all.
- false is the same as word-break: keep-all.

Here’s what the CSS might look like:

.text {
    overflow: visible !important;
    overflow-wrap: break-word;

    &:where(h1, h2, h3, h4, h5, h6, dt, legend, label, button, th) {
        text-wrap: balance;
    }

    &:where(p, li, figcaption, dd, summary, caption) {
        text-wrap: pretty;
    }

    &:where(textarea, [contenteditable]) {
        text-wrap: stable;
    }

    &:where([data-wrap="true"]):where(pre, kbd) {
        text-wrap: pre-wrap;
    }

    &:where([data-wrap="false"]) {
        text-wrap: nowrap;
    }

    &:where([data-break="true"]) {
        word-break: break-all;
    }

    &:where([data-break="false"]) {
        word-break: keep-all;
    }
}

I’m using the keyword value for text-wrap over the shorthand because it’s easier to update this value instead of unsetting it to reapply in some cases. This allows us to leverage the default of text-wrap-mode: wrap for most elements.

The elements I’ve chosen to receive text-wrap-style are based on their expected content. Elements that expect shorter amounts of content receive balance while elements that expect longer amounts use pretty. Note that these are targeting elements that would normally have content as their direct children. While you could put pretty on sectioning content for it to cascade, it’s more performant to be more specific.

If you were paying attention, you’ll notice that there’s a lot of property values that we went over which are missing from the API. The reason is that they’re probably not going to be useful in day-to-day web development. This isn’t meant to be a CSS reset, this is an opinionated setup for what I believe would be a text component that allows for some customizability while keeping the options limited.

This includes my own rule-breaking for use of !important in this case to call out that hiding overflow on text is a bad practice. Makes me want to set z-index: auto !important on all my elements too.

Astro RSS MDX

Sun, 18 Aug 2024 00:00:00 GMT

I’ve been using Astro for a long time. The developer experience includes all the best parts from the way I learned web development nearly 30 years ago. The stuff that was missing back then is intuitively included, like HTML templating without the need for a heavy framework. I’ve since moved all the personal projects I’m currently developing onto an Astro stack.

However, there’s been one thing that was always missing from the Astro ecosystem. Rendering full content MDX in your RSS feed.

Astro’s recommendation

From the docs, the general idea is to use Astro’s RSS package to create the feed. This isn’t doing anything too special itself. It leverages the src/pages directory to statically generate XML content based on your collections. Here’s the “whole” example from their docs:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const blog = await getCollection('blog');
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      customData: post.data.customData,
      link: `/blog/${post.slug}/`,
    })),
  });
}

I put the word “whole” in quotes because you might notice that the post content is missing from the feed. Some folks prefer this choice to drive traffic to their website. Personally, I’m old school and would rather folks read my content in whatever medium they feel most comfortable. That’s why it was very important to include the full content in my feed.

While Astro does have a section about rendering full page content, it is limited to vanilla Markdown. It does not include an approach to handle the full MDX documented. In fact, it suggests using an entirely different rendering engine. This has been a big thorn in the side for folks who have dynamic MDX content looking to migrate to Astro from other ecosystems. This is because the only way to render that content is by using the following:

---
import { getEntry } from "astro:content";

const { slug } = Astro.params;
const entry = await getEntry('posts', slug);
const { Content } = await entry.render();
---
<Content />

That <Content/> component can only be rendered within the context of a .astro file. Now, you might think you could just render that content to HTML and then fetch the result. With some finesse, you can get this to work in local development, but a statically generated site will have problems. This is most likely due to a race condition, or the order in which data is rendered. Either way, there hasn’t been a clear approach to render MDX in Astro RSS feeds for a while.

Luckily, one of the more recent releases of Astro introduces an approach that can get us what we’re looking for.

Astro Containers

In v4.9 of Astro, a new experimental Container API was introduced. The benefit of this API is the ability to render Astro components outside of the normal Astro context, specifically outside of .astro files. This is exactly what we need to get the content into a normal Javascript file.

At first, this was not a straightforward process. We still needed a .astro file to help render the special <Content/> element. Soon afterward, the setup to do this became a lot cleaner which is what I’ll show in this post.

We’ll start with a /pages/feed.xml.js file. This is similar to what was provided in the first example, and you can certainly use Astro’s RSS package to help construct the feed. However, to get the MDX rendering, you’re going to need some additional helpers. Let’s go through the file by each section, first the imports:

import { experimental_AstroContainer as AstroContainer } from "astro/container";
import { getContainerRenderer as getMDXRenderer } from "@astrojs/mdx";
import { loadRenderers } from "astro:container";
import { getCollection } from "astro:content";
import rss from "@astrojs/rss";

The first line imports the new Container API, we’ll use this to create a new Astro context. The second line comes from the @astrojs/mdx package, and this will tell the container API how to render the data. The next import is used to load the renderers. For whatever reason, this isn’t included in the container API.

The last two imports should be familiar, importing the getCollection method from astro:content and the rss builder from @astrojs/rss. Now we’re going to put those imports to work:

export async function GET(context) {
    const renderers = await loadRenderers([getMDXRenderer()]);
    const container = await AstroContainer.create({ renderers });
    const posts = await getCollection('posts');
    const items = [];
    for (const post of posts) { /* Next part will be here */ }
    return rss({
        title: 'My blog',
        description: 'All my thoughts',
        site: context.site,
        items,
    });
}

First, we load the MDX renderer. Then we pass the result of that into the .create() method for making an Astro Container. Then we do a standard getCollection() for the posts. If you need to filter posts for some reason, make sure to also do that here before processing in the upcoming for loop. We’re using a for loop instead of a functional process because we’ll need to do some async work in the loop. After all the items are processed, we’ll write the feed using the @astrojs/rss rendering function. Let’s look at what’s inside the loop:

const { Content } = await post.render();
const content = await container.renderToString(Content);
const link = new URL(`/posts/${post.slug}`, context.url.origin).toString();    
items.push({ ...post.data, link, content });

Assuming that your frontmatter matches the expected schema for @astrojs/rss, the only other keys you’ll need to provide are link and content. You can see how I construct the link by using the context.url.origin. This helps with local development.

Our real focus is the content output. In here, we do something similar to how we might render the <Content/> element in a .astro file. However, then we send the output of that to the container.renderToString() method. The result of that is regular HTML that we can pipe directly into the rss() method at the end of the function. Here’s the whole file:

import { experimental_AstroContainer as AstroContainer } from "astro/container";
import { getContainerRenderer as getMDXRenderer } from "@astrojs/mdx";
import { loadRenderers } from "astro:container";
import { getCollection } from "astro:content";
import rss from "@astrojs/rss";

export async function GET(context) {
    const renderers = await loadRenderers([getMDXRenderer()]);
    const container = await AstroContainer.create({ renderers });
    const posts = await getCollection('posts');

    const items = [];
    for (const post of posts) {
        const { Content } = await post.render();
        const content = await container.renderToString(Content);
        const link = new URL(`/posts/${post.slug}`, context.url.origin).toString();    
        items.push({ ...post.data, link, content });
    }

    return rss({
        title: 'My blog',
        description: 'All my thoughts',
        site: context.site,
        items,
    });
}

Again, you’ll probably want to add some additional metadata to your feed, maybe filter and sort the posts too. You could probably construct that data in a similar way to the approach taken for link above. This is basically how I create the feed at this very site.

Hopefully, this helps folks with the final steps in migrating their blog to Astro. From here, the sky’s the limit!

EDIT (2025-01-30): I’ve had a few people reach out about this post helping them get full content which is great! However, Astro did change part of the API in v5, specifically the way you render content.

Previously, a .render() would exist on the Collection Entry. Calling that method would return a <Content/> element; the thing that was so hard to resolve outside of .astro files.

---
import { getEntry } from 'astro:content';

const post = await getEntry('blog', params.slug);

const { Content, headings } = await post.render();
---
<Content />

Now in v5, there’s a render function available as an import from astro:content. You’ll want to use that to get the <Content/>.

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', params.slug);

const { Content, headings } = await render(post);
---
<Content />

So the new snippet should look something like this for v5.

import { experimental_AstroContainer as AstroContainer } from "astro/container";
import { getContainerRenderer as getMDXRenderer } from "@astrojs/mdx";
import { loadRenderers } from "astro:container";
import { getCollection, render } from "astro:content";
import rss from "@astrojs/rss";

export async function GET(context) {
    const renderers = await loadRenderers([getMDXRenderer()]);
    const container = await AstroContainer.create({ renderers });
    const posts = await getCollection('posts');

    const items = [];
    for (const post of posts) {
        const { Content } = await render(post);
        const content = await container.renderToString(Content);
        const link = new URL(`/posts/${post.slug}`, context.url.origin).toString();    
        items.push({ ...post.data, link, content });
    }

    return rss({
        title: 'My blog',
        description: 'All my thoughts',
        site: context.site,
        items,
    });
}

I haven’t tested this since my blog is still on v4.11, so your mileage may vary. Good luck!

Avoiding tokens

Mon, 24 Feb 2025 00:00:00 GMT

The design systems community was buzzing a few days ago with the announcement of version 2 of the Salesforce Lightning Design System (SLDS). I shared the link to the new documentation on LinkedIn and the engagement has been significant.

As someone who has visited dozens of design system documentation sites, there’s certain things I tend to look for when perusing the content. One of those things is how the team handles design tokens. Design tokens are a fundamental feature of what we do, because this unlocks the ability to update the presentation of an experience with less friction. In fact, the term design tokens originated from SLDS many years ago.

That’s why it was so surprising to not find a page dedicated to design tokens in the new version. The term design tokens is mostly absent from the site, except for this quote found on the front page.

SLDS 2 prioritizes CSS custom properties as the visual language and decreases the usage of design tokens.

— SLDS 2

I aimed to find out.

The problem they’re solving

Conversations sparked at the LinkedIn post as well as within the Design Systems Slack where I first saw the link. Alan Weibel, UX Architect at Salesforce, was responding in both places. In all of the discussion, his response to Brad Frost made things more clear.

…I think it depends on how you define design tokens.
If the definition is design tokens are variables (tokens) for design system values, then yes, styling hooks are the same and come with a name-value pair.
If that definition comes with expectations of the specifications in W3C drafts or common implementations of design tokens, then it is not the same. They’re a completely different format that is web first, non-web second.

— Alan Weibel, Salesforce UX Architect

This highlighted the issue. The team at Salesforce has considered the use of the word “design tokens” to strictly mean the artifacts coming from the DTCG work. Meanwhile, the community has more commonly considered design tokens to simply be the name-value pairing for design purposes. In other words, at Salesforce “design tokens” equals DTCG specification while outside of Salesforce “design tokens” equals name-value pairings.

So they’ve decided to explicitly distance themselves from the evolving specification but that still doesn’t answer the question of “why?” Here’s another quote from Alan, this time from the Design Systems Slack:

Design tokens are very helpful for a lot of teams. They just aren’t super helpful for Salesforce. It was an extra step to create tokens to be used across multiple frameworks when 99% of Salesforce is on a single platform—the web. Even our native mobile apps use webviews inside of the native wrapper.
We ended up using a web standard, CSS custom properties, as the name/value pair instead of design tokens. These style hooks are a lot easier to manage in both code and tooling. If folks need this CSS for a non-web application, then they can use the THEO tool.
In the end, people still get name/value pairs for all the frameworks but it’s less complex and easier to manage for our platform

— Alan Weibel, Salesforce UX Architect

There’s a few notes that I take away from this:

It was easier for the team to write CSS Custom Properties instead of requiring a process to turn non-CSS into CSS.
They opted for a solid web standard over the more tumultuous DTCG specification.
The team now focused primarily on the web, so supporting other platforms was considered overkill.
If some team needs to transform the CSS into non-CSS, they had an answer for that need using THEO.

How to fix this

The community had a very similar response to Figma’s variables. When the new feature was announced at Config in 2023, the slide showed the word “design tokens” crossed out. Certainly meant to cause a stir amongst the crowd before announcing variables which work very similar in concept. The team made a conscious decision to not name them design tokens but why? Jacob Miller answers that question in the Design Systems Slack:

…If we tailor-made a solution for design tokens, we’d end up with disparate systems for a bunch of other features that have similar requirements, such as translation strings or conditional prototyping logic.
Rather than do that, we wanted two things: A more unified experience, and more alignment with code. In the same way that you can use css variables to implement design tokens, we wanted that with Figma as well.

— Jacob Miller, Figma Product Manager

I wrote about why they were different when variables were first released, along with other design token metadata options at the time.

The difference between Salesforce and Figma is that Figma has documentation which speaks about design tokens and how to implement them within their ecosystem. This makes it easier for folks expecting design tokens to be supported and how to transition those folks into the specific changes within Figma to do similar things.

This is where the decision for the public documentation of the SLDS breaks down. The lack of design tokens or a path for transitioning makes it hard for folks expecting to see the concept. SLDS does have name-value pairs in a similar way to how most of us think of design tokens, they’ve just renamed the concept to Styling Hooks. This is the same as naming your carousel component “Fred”. It might work for your internal team, but cause friction for anyone coming at it for the first time, externally or internally.

I’d recommend that the SLDS team explain in their public documentation how folks looking for design tokens can transition to styling hooks. At best, define “design tokens” more generally as the community currently does or make mention in their blog post that the DTCG was too complex for their needs at this time.

A form of protest

Ultimately, I agree with Salesforce’s decision to avoid the DTCG specification at this time. I’m a highly critical of the current direction. It is my opinion that it is scope-creeping into territories that will make it difficult for it to ever be finished.

For example, the DTCG specification originally defined a color in this way:

{
    "colors": {
        "color-red-500": {
            "$type": "color",
            "$value": "rgba(180, 216, 167, .75)",
        }
    }
}

In the example, the $value is a string. The newer specification is in the process of defining color in this way:

{
    "Acid green": {
        "$type": "color",
        "$value": {
            "$hex": "#00ff66",
            "$colorSpace": {
                "name": "srgb",
                "$components": [180, 216, 167],
                "$alpha": 0.75
            }
        }
    }
}

Among other critisms I have, seeing color defined in this way highlights why Salesforce finds “design tokens” too complicated for their customers. Defining all of the individual parts of a color in a structured object is tedious. It is clear that the community group is less focused on making the file human-manageable at this point and expecting tools to help with the translation. I’m afraid this begins vendor lock-in where you might only be able to edit design tokens from tools. Salesforce Styling Hooks largely avoids the tooling needed to take the DTCG specification into their primary format for the web.

I’ve spoken to Kaelig Deloumeau-Prigent, one of the co-chairs for the DTCG about the direction to this more complex object. The main reason seems to be the difficulty in parsing strings. His example explains that the CSS rgb() color function is an example of the complexity because it takes several different kinds of syntax which any consuming application would need to support. Standarizing the format for systems to injest makes it easier. I contest that this makes it easier for the machines, not for the humans authoring tokens.

I am biased in this area as the creator of Token Operations. While folks could argue that the operations themselves are less accessible for human maintainers, the benefit is that those operations are for the machines but repeatable and sharable. The intention is for a single complex operation to be tucked away from human authors using those operations.

I think a compromise in this area would be best. Where string concatenation could be added into the specification. Such that you could separate parts of the value meant to be concatenated for different platforms, but make it easier to author for humans. Based on my examples in the DTCG issue, string concatenation would solve much of the problems that Token Operations would handle otherwise. This would allow for the original simplified construction while allowing for more complicated multi-platform values to exist. This would also finish the specification much faster by avoiding all of the complexities that might come from every individual $type. Admittedly, this doesn’t solve for a zero-tooling ecosystem that Salesforce might have targetted, but I believe it would make it more accessible to those with minimal tooling.

Being intentional

Over the years, I’ve avoided the word “semantic token” to describe the middle tier due to my strict definition in favor of the word “intent”. I continue to refer to this as a type of design token to keep the concept connected. Where I work today, the word “design token” is rarely used in favor of “intents” which also delivers that strict definition. Where variables could be named and assigned anything, the criteria for similar as “intent” is more systematic and helps maintain a consistent construction and presentation as a result. No one asks “where are design tokens?” because they are design tokens.

It’s ok for design systems to be different, right? 😉

Avoiding z-index

Fri, 13 Mar 2026 00:00:00 GMT

From the days of working with design tools like Photoshop, layering compositions in 3D space on a computer has been part of the job. Managing what appears on top can be dozens of elements, maybe even groups of elements, and carefully curating the order of the layers is often a necessary unit of work.

As you can expect, this sort of exercise has translated to the web, and traditionally we think the z-index property is meant to manage this ordering in a similar way to how layers would work in a design tool. When you are working alone on your own project, this is reasonable because you are in control of the elements, the order, and the composition as a whole. You can decide if the z-index you added yesterday isn’t good enough today and make modifications. You can tweak this part here, and make a small change there to get everything just right. In fact, I use z-index right here on the blog in a few specific places to get things looking just right artistically.

But for larger teams where elements are coming together from all across the organization to be composed into a single experience, trying to manage z-index is a political battlefield. It’s not possible to just make a --dropdown-elevation variable, because that dropdown might be on another surface that itself has an elevation higher than the dropdown.

Popular public design systems like Shopify Polaris include z-index tokens which don’t mention where the token is meant to be used, we just know they exist.

There are certainly attempts at making sense of this. A recent article on CSS-Tricks suggest naming the elements where they are expected to appear. Semantically, this makes sense on the surface. But as mentioned earlier, it’s very possible that a flyout that is normally underneath a modal is meant to later be on top of it. And it would be inappropriate to make an entirely separate component meant for “modal dropdowns”. Maybe it’s OK to set your own z-index? Well, how do you know it isn’t conflicting with another element that will appear later in the lifecycle. You’re essentially playing whack-a-mole, goldilocking the perfect z-index value, tokens or no tokens.

But what if you didn’t need z-index at all? There’s two approaches I want to highlight and both related to a very simple concept. Elements are visible in the order they appear in the DOM.

Top layer

For what purpose do we set elements in 3D space on the web at all? Certainly, we can stylistically show something is a little bit raised for some personality but when we are creating flyouts and popovers, why are we using them. Overall, these are meant for focused attention. The user was currently navigating the general interface but needs to either focus on something further to continue. Sometimes that’s to choose an option, or maybe be notified of something. This means that there’s a hierarchy to what is being presented. This thing is currently important, then this thing is important, and so on. So this means as we introduce elements to the user, this is conveying a sense of importance. The most recent thing that is added, is the thing the user needs to see more than any other.

This is how the top layer works in HTML. It is a separate layer from the rest of the DOM where anything placed within it will be on top anything that would be placed in the normal DOM. No amount of z-index can place elements higher than the top layer. Additionally, z-index doesn’t work in the top layer. So your question might be, how do I provide the correct order of elements? The order of the elements is how they are added to the top layer. That way, if you want some messaging to be the newly most important thing, you simply append it to the top layer.

Elements that can apepar in the top layer are restricted to the following according to MDN:

Fullscreen elements, i.e., elements that have been caused to display in fullscreen mode by a successful Element.requestFullscreen() call.
<dialog> elements displayed as a modal via a successful HTMLDialogElement.showModal() call.
Popover elements shown via a successful HTMLElement.showPopover() call.

Now, it’s more clear what is supposed to be on top. You can see all the elements and their visual order in devtools. Here’s an gif from the Chrome for Developers article on the top layer showing how to inspect these elements.

Devon Govett, one of the engineers behind Adobe Spectrum, recently described some of the drawbacks about using the top layer. I’ve made a response to the comments about <dialog/> in a recent Wireframe episode. But it’s important to reiterate that you do have control of the order, and I’d argue better control than spraying a new z-index number and praying it doesn’t conflict with something else.

Grid positioning

The other common reason why z-index is used is to compositionally place elements on top of each other. This was very common when we used to use the aspect ratio hack years ago for video. In this hack we’d need to use a padding value as a percentage which is based on the width of the element to maintain the aspect ratio of the box. Then we’d break the inner container out of the flow, and make it fill the parent’s dimensions.

.aspect-ratio-box {
  height: 0;
  overflow: hidden;
  padding-top: calc(100% / (16/9));
  position: relative;
}

.aspect-ratio-box-inside {
  position: absolute;
  inset: 0;
}

These days, if we needed a similar effect, we can just use aspect-ratio: 16/9 on the parent, but having a child fill a container is still important today. And it is commonly done using this combination of position values.

Using position creates a new stacking context which you probably don’t want and may have not even known was happening. While it might be harmless to use in one place, when you start positioning many shared elements, you might find putting a z-index on one of them causes something else that was positioned to conflict. Understanding stacking contexts is very important when working with positioned elements, and there’s a great article by Josh Comeau about them.

But you can avoid creating a stacking context altogether using CSS grid! Assuming a similar HTML setup for the aspect ratio hack, here’s what that looks like with grid. I’ve removed the padding hack since we don’t need that any longer with modern CSS.

.aspect-ratio-box {
  aspect-ratio: 16/9;
  display: grid;
}

.aspect-ratio-box-inside {
  grid-area: 1 / 1 / -1 / -1;
}

See the Pen Untitled by Donnie D’Amato (@fauxserious) on CodePen.

Any time you want to have an element match the dimensions of its parent, this is the technique that you should think of first. This approach avoids using position and works with the order in which elements are provided.

You can also place elements relative to the container. For example, maybe you’d like to place a close button at the top corner.

See the Pen Grid positioning banner by Donnie D’Amato (@fauxserious) on CodePen.

I wouldn’t recommend this specific approach for handling a close button because the composition’s elements might conflict with each other. You should see the problem with this if you resize the example, heading will appear over the button. But it should give you some ideas of what else you might use CSS grid positioning for. Want the button on top, reorder the elements in the HTML.

When we use and promote techniques that avoid pitfalls, we produce more robust applications and consistent systems of composition. Sure, CSS gives us a lot of tools, but it’s up to us to use them in thoughtful ways. Reaching for z-index should be a last resort when everything else doesn’t work. There’s better ways in a modern web, we just need to take a moment while our chatbots are working to explore novel solutions on our own.

Beer goggles

Mon, 19 May 2025 00:00:00 GMT

Material Design 3 (Material You) was officially unveiled at Google I/O in May of 2021. At the time the new M3 site was still in the works with only a few analogs to the earlier Material Design site. I didn’t think much of this at the time, especially since 2021 was a busy year for me personally. But now, Material has a “new” launch called Expressive with an article explaining how we got here. The article triggers me for a few reasons:

Boredom

One of the first paragraphs in the article has the following quote:

Back in 2022, our research intern was studying user sentiment toward Material Design in Google apps. After mentioning her initial findings to colleagues in a Munich beer hall, she sparked a team-wide design debate: Why did all these apps look so similar? So boring? Wasn’t there room to dial up the feeling?

One interpretation of this story is that you too can make a difference in a large organization with a small idea. Sounds very inspiring. However, when I read this, it looks like a group of designers were bored. There’s no user need spearheading the work. And this is something we see all the time. Some new designer comes in, looks at the current body of work for something they can own, and turns it into some project for a promotion. This occurs even if everything is working fine.

Don’t get me wrong, there’s always things that can be improved, but it’s rarely the way that things look. It’s more often the way things work that need improvement. Unfortunately, it’s easier to put a new paint job on some walls than it is to teardown and rebuild parts of the house. A new coat of paint can really help make the room look new, but someone should really consider moving the toilet out of the kitchen.

LooksGood™

Later in the article we get some “data”:

These factors can be quantified in users’ responses to new M3 Expressive designs. We found a 32% increase in subculture perception, which indicates that expressive design makes a brand feel more relevant and “in-the-know.” We also saw a 34% boost in modernity, making a brand feel fresh and forward-thinking. On top of that, there was a 30% jump in rebelliousness, suggesting that expressive design positions a brand as bold, innovative, and willing to break from convention.

These numbers are points describing the Aesthetic-Usability Effect. Imagine conducting a survey and asking people about their feelings toward cotton candy versus a shovel. You’re going to get an overwhelming amount of positive responses for things that look fun and inviting over things that are designed to solve a user problem. If you then ask about the feelings between a pastel shovel and a brown shovel, you’ll probably get more people liking the pastel one because it looks unique and fun.

The bottom line here is that we need things to be usable first. We shouldn’t be triggering a redesign unless we need a hole and all we have is cotton candy.

False positives

The next is an image from the article:

The article claims that the participants were able to find the send button 4 times faster with the Expressive redesign specifically because of the following:

By making the Send button larger and more prominent…

However, I’d argue that the size and cosmetic treatment didn’t have the largest impact here. It certainly contributes, but the placement change is more of a signficant factor. To demonstrate, consider if we were to imagine eye-tracking on writing an email. Your eyes should be following the words as you type, left-to-right moving downward. This means when you are finished, your eyes will be lower on the screen.

This also means that the send button in the original application is in a suboptimal spot at the top-right corner. This isn’t just due to how we read, but items on the top edge are often overlooked in user interfaces as they are normally reserved for more generic items like user accounts or settings. The main action should be more prominently featured within the context of the user task.

This is the difficulty with testing too many changes at once. You may wind up with a more usable solution but not know what of the changes was the definitive improvement. Changing the size, color, and placement of the button all at once can make it seem like the cosmetic changes were the qualities that provided the impact and falsy drive more resources into something that didn’t truly need it. Imagine painting your bedroom and realizing you have a lot of left over paint. So you decide to repaint all of the walls. They didn’t need to be repainted, you just did it because you were already motivated for that task. Meanwhile, the toilet is still in the kitchen.

Unfamiliarity

One final quote at the bottom of the article:

It is also worth noting that while expressive design improved preference and usability, it was impacted by users’ lack of familiarity. This is a challenge that designers will have to navigate, but we expect to see familiarity increase as more and more apps adopt this new style in the coming months.

This paragraph is justifying what happened during the hamburger menu explosion of 2016 and beyond. There’s plenty of articles showing both sides of the story across the internet ending up in a firm It Depends™ from the community. When there’s so much debate, it’s easy to get lost in the opinions. The reality is that you want familiarity. This is Jakob’s Law. The more you make things unique and unfamiliar, the harder it will be for people to use.

Take the new expressive email interface from before. I can’t tell you what all the other icon buttons next to the send button do. Why is it “image” and then “camera”? Can’t I see my images from the camera? Maybe the next one is a document scanner? Does the scanner write the document into my email or does it just attach like the paperclip used to do? I have no clue what the fourth icon is supposed to be. That last icon looks like a pen so maybe I can draw something in the email? All mostly unclear and unfamiliar.

Take caution

The main point I’m making here is we’re seeing more designers going for low-hanging fruit of cosmetic changes instead of truly improving our experiences. I’m afraid that design teams are going to look at this “research” to justify their own exploration into expressiveness while neglecting better experiences for users. A technique like Mise en Mode can provide infinite amounts of expression. But at the end of the day, you still haven’t moved that toilet from the kitchen.

Big four oh

Tue, 13 Dec 2022 00:00:00 GMT

It’s my birthday today, 40 times around the sun. I reflect back to the first time I started journaling; it was on my IBM computer in a text file I called “hyperjournal”. I really tried to be regular about it but just fell out of habit. Fast forward to now and it’s been 4 months since my last post but not for lack of effort.

Complementary Space

A topic that I’ve written about on my blog and spoke about at a conference earlier this year is a new way to think of spacing tokens called Complementary Space. It’s the follow-up to Gridless Design which got a great deal of interest last year. Complementary Space has gotten a bit less attention but I think that’s understandable because it is experimental and not strictly design token based. It needs a different kind of mindset to fully embrace. Releasing it so close to the holidays was also probably bad timing. However, I appreciate all of the feedback I’ve received on it.

Connecting with community

So. many. design systems events. In the past few months I attended Schema and Clarity along with a dozen video conference events. The latest was a fully stacked panel speaking about the future of design tokens yesterday, and there’s another event today (that I unfortunately must miss). I love how active this community is, where there is always a discussion to be had. I’m especially glad for the wrap up of yesterday’s panel where the leadership agreed that there’s a future where we aren’t pushing pixels or making buttons because it’s already done. This gives us time to focus on what really matters; the experience.

There is absolutely a world where design systems is not about the assets but about the infrastructure. I got an opportunity to catch up with Shaun Bent of Spotify who had a talk a few years ago describing their onion model where a core system supports outer systems. This is where the future of design systems is for me; people who focus on the infrastructure of how resources are delivered across teams. We spoke a bit about the TV team for Spotify since it is especially niche and how the fit into the support strucuture. A question I had was “would it be more beneficial to have a representative of the TV team on the design system team?” Both of us don’t know what the answer to that is. There are pros and cons either way. For right now as I understand it, the TV team there is specialized and meets regularly with the design system team for alignment. Though I think these are questions we should be asking, not what is another way of displaying a token library.

I absolutely love chatting with members of the design system community about these kinds of questions and topics.

Redesign

When I first launched this blog I didn’t put a lot of effort into the design because I expected folks to subscribe to the RSS feed. However, every time I’d look at this blog, I’d be so bored with the design of it. It wasn’t reflecting my personality and I wasn’t sure what direction to go. After playing around a bit and speaking with Jen on this; she recommended that I lean harder into the hot takes and use Hot Ones as inspiration. I’m glad there’s another designer living with me to help get out of designers-block. 😅

So now I rate each post with a heat which will inform the accent color used on the post; from mild to volcanic. This isn’t visible at all in the feeds, but for those visiting the site it’ll be a nice bit of personality. Most of the colors being generated are accessible but I’m looking forward to the new color space functions in CSS to get further accessibility support. Jen also had the idea to have folks reading posts to influence the heat but I’m not about to hook this up to a custom database and authentication just for a single value.

I’ve also updated the OG image generation to use Satori by way of eleventy-plugin-og-image, making it much easier to create images for each post. I hope there’s better support for CSS in the future with this tool but it does a good enough job for easy integration.

I also want to put a bit of animation into the new neon synthwave effect for the titles but that’ll take a bit of time and exploration.

Plans for next year

I have another large project that I started last year based on a short conversation with Dan Mall. It’ll probably take a long time to officially announce since there’s a lot of work to be done for it. In the meantime I still expect to create posts here on a better cadence. I have over a dozen post ideas ready to be written.

Additionally, I’m planning to put more focus on Mastodon and less in other social media platforms. I’m still not comfortable with the new platform because at the moment the circles are small. I hope more folks join for more connections to be made and that finding like interests is easier. However, it’s better than having notifications of suggested posts that are completely irrelevant to my interests like most other social platforms. So if you’re following me at the birdsite, I recommend you consider coming over to Mastodon and following me there.

Looking forward to what the next 40 years may bring!

Book Authoring Backstage

Wed, 25 Mar 2026 00:00:00 GMT

By the time you are reading this, my several-year-long journey in book writing has neared its end. My first book, Mise en Mode, is now available for purchase. Now that it’s complete, I wanted to document some of the process so that you might consider venturing out into the great unknown of self-publishing a little better than I did.

How it started

After speaking on the subject at Clarity in 2023, the topic generated a great deal of interest. I received lots of questions and people who wanted to know more. As per usual, I sat down and started writing another blog article here. But after looking at the reading time showing 15 minutes, not being anywhere near done, I felt it was time to go to the next level.

I’ve always been interested in writing a book. I have a few books on writing books. Though I never had a topic that I felt passionate and knowledgeable enough to write about. I know they say that just because someone has written something before, there’s no reason not to write about it again, but I wanted to be unique with whatever my book was about. Mise en Mode was most certainly that opportunity.

Where to write

The next hurdle was where I was supposed to put these words. I did some research here, and even spoke with Ethan Marcotte early on about his process. My big worry was, “if I start writing in X, will that make it easy to turn into a physical book?” The answer was one of the hardest parts of the process.

I first started writing in reedsy. Its main selling point is that you will absolutely get a printed book using their platform. Additionally, it’s a web-based editor so I can write anywhere. I actually tried to use reedsy twice, thinking that the shortcomings could be overlooked. The reality is that reedsy is not suited for technical books. It can’t support inline code and to speak about design tokens, there’s a lot of inline code. I figured if you’re writing something non-technical, this would be a good place to try.

So from there, I searched for something that was more suited for technical writing. I saw some reddit posts that claimed the publishing houses might expect AsciiDoc as a format because they already have templates to render that format into a book. From the look of the syntax it was markdown-like which was good. I preferred to write in markdown because I’ve been using it for years and it streamlines the content management process. I could also write and version control using GitHub so I could even edit in GitHub directly. The syntax isn’t really markdown, it’s a bit different but not too far from what I was used to writing.

It’s been a while and I don’t remember the specifics but I ended up having problems rendering the final book using AsciiDoc. I know you need to install a few things in order to get it working, which I don’t really like. I think the biggest problem was customizing the final output to something that looked like a real book.

That caused me to go out and look for other solutions. I’ll also say there’s a lot of red herrings out there. For example, the first line of mdbook says:

mdBook is a command line tool to create books with Markdown.

But when you read the next line, it’s clear this isn’t what I want:

It is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean, easily navigable and customizable presentation.

It should be called mdDoc or mdWebpage.

I eventually found Quarto which has a syntax even closer to markdown. I even tried rendering what I had as a book and at first glance it seemed like everything worked well. I ended up writing the entire rest of the book in Quarto.

Then, came the rendering.

Even though I had sent a first pass through, it was where you look at the details. What I found was snag after snag. Quarto uses LaTeX and pandoc to render documents. LaTeX for the formatting, and pandoc to convert to a specified output. If you touch nothing, this works well enough. But if you need anything special, you are in for a challenge.

One of the things that really caused me to throw out this toolchain was line wrapping. The token names in the book are long. For example $action_primary_backgroundColor and because of this I expected the inline code to wrap when necessary. Otherwise, you’d get huge distracting gaps in the text. You might even be seeing this awful lack of wrapping in this very post! I’ll fix it here, eventually…

However, for a printed book where I could curate how it looked precisely, this was unacceptable. However, no matter what I tried, I couldn’t get LaTeX to make these wrap. There were plenty of other problems like when to make pages break. I’d have code blocks and callouts broken between pages. I couldn’t believe how hard this was, or how this wasn’t just something built into the system. Why would it be acceptable for a code block that isn’t larger than a page to split between pages? I said to myself, I know exactly how to do this in CSS.

One last attempt was to try and make this work using Adobe InDesign. My wife worked in publishing before and was familiar with the features of the program. However, what made this a non-starter was the restrictions on the callouts. Because the callouts are in their own colored boxes, they can’t be given styles like the normal paragraphs. My wife was trying to hack together something to make them look good enough, but at this point I didn’t want good enough. I wanted it to look like I expected it to look and I wanted it to be easy so if I needed to make an edit, it wouldn’t break the entire layout.

CSS to the rescue

Toward the end of my frustrations with book layout, I couldn’t stop but think to myself “Why is this so hard? I could do this in CSS in minutes!” That’s when I went out to see if anyone actually did do this. That’s when I found this post by Ian McDowell where he outlines how he used CSS to layout his print book. He even shows the result at the end which was very inspiring.

So, that’s exactly what I did. While I’m normally an Astro fanboy, I decided to use 11ty for this because all I needed to do was convert markdown to HTML and 11ty is made for that. Then I could just write CSS as I normally would, hit Ctrl+P on my keyboard and save it as a PDF. There’s actually not much more to it than that, but I’ll go over the items that are unusual.

In my book I set up the following values:

:root {
    --page-size: 6in 9in;
    --page-margin: .75in;
    --inner-margin: calc(var(--page-margin) * 1.5);
    --runner-margin: calc(var(--page-margin) / 2);
}

The --page-size is used in the @page declaration directly, along with the --page-margin to go around each page:

@page {
    size: var(--page-size);
    margin: var(--page-margin);
    counter-increment: page;
}

That counter increment property is described in an earlier post that helps create page numbers. Next, we need to increase the inner margin on the correct pages.

@page :left {
    margin-right: var(--inner-margin);

    @bottom-left-corner {
        font: var(--font-caption);
        content: counter(page, false-start);
        margin-block-end: var(--runner-margin);
    }
}

@page :right {
    margin-left: var(--inner-margin);

    @bottom-right-corner {
        font: var(--font-caption);
        content: counter(page, false-start);
        margin-block-end: var(--runner-margin);
    }
}

The runner is the bottom of the page and this is a bit larger to make room for the page numbers. Finally a few other items to help with printing:

body {
    -webkit-print-color-adjust: exact !important;
    print-color-adjust: exact !important;
}

The print-color-adjust: exact is used to tell the browser that these styles are made for print and to not make any opinionated changes to the page. Without it, the print rendering could look unexpected by removing background colors for example.

From there, we have a few additional properties that help. For example, here’s all of the items that I want to avoid a page break:

:where(ol, ul, table, figure, pre, blockquote){
    break-inside: avoid;
}

For headings, I have slightly different rule.

:where(h1, h2) {
    break-before: right;
}

:where(h3, h4) + * {
    break-before: avoid;
}

For h1 (part titles) and h2 (chapter titles), I want to make sure that they always start on a right-hand page. That’s what break-before: right is supposed to do in theory. In practice, it doesn’t work because no browser has implemented it. Instead, I created a blank page element that I manually insert to get those pages in the correct place.

For the h3 and h4 elements, I want to make sure that the following paragraph is connected to those headings. Otherwise, it would be weird if the heading was at the end of a page with its first paragraph on another page.

There’s a lot more to the CSS print specification that browsers haven’t implemented. PrinceXML claims that its main feature is to implement these features and more. I looked into it after finishing the book, but it looks like it might be more involved than I was hoping. It wasn’t clear how to get it working after downloading the zip for me.

But after that, I had a process to get a real ready-to-print PDF of my book. Next, is to make it real.

Publishing

I did a lot of research into self-publishing and ultimately went with Ingram Spark. Most of the complaints were around customer service being slow, but the benefits of worldwide distribution and not being locked into a single Amazonian ecosystem was very enticing.

Before this I bought ISBN numbers from Bowker because then you are able to have more flexibility than if a publisher gives you a free one.

I’ll say that the process was mostly painless. There’s some tools at Ingram Spark that help you prepare your book. The cover template is a little tricky. For my hardcover it wasn’t clear how the template would be used. After getting the first book printed it was more clear that some of the lines were meant to indicate how the cover folds around the book.

We originally made the cover in Adobe Illustrator but then cancelled our subscription because the cost was getting out of hand. Luckily Affinity is free and works just as well. There was a bit of a learning curve but we got the results we needed for the second round of printing. It was close enough such that when I submitted the cover design a third time with a small tweak, I was confident enough to enable the book to be sold without buying myself another copy.

When you’re adding your book to your account, Ingram Spark asks you some questions about the purchase price. In this there’s areas where you need to set the wholesale discount. This is where I got tripped up. Basically, if someone buys your book direct from Ingram Spark, your cut is much higher than if they were to buy it from a middleman like Amazon. This means that it’s better for people to buy it direct from “you” (Ingram Spark). What they don’t tell you is that when Ingram Spark says they have the best distribution network, they mean to resellers, not themselves. I didn’t know this, so when I released my book, I found out it was only available to the US and UK directly through Ingram Spark.

Future

I’ve already started the process of getting the e-book available. It’s in review inside Ingram Spark and I’m planning to do a joint release making the e-book available at the same time that I enable worldwide distribution of the hardcover. I don’t know how long it’ll take for that to reach resellers but keep an eye out on my socials because I’ll be checking periodically and eventually updating the website with links that I get to the book.

Button size styles

Wed, 10 Apr 2024 00:00:00 GMT

This topic was sparked from a few discussions on Twitter. On one side there’s a school of thought that believes the size of a button should be achieved with padding. On the other side, there is also a belief that the size of the button should be handled with minimum dimensions. I have a strong opinion which is based on the principle that the size of an element is dictated by its contents and therefore I believe padding (along with other properties) should be the general basis for size.

Minimum size

If you are purely using min-height to determine the size of the button, you aren’t accounting for the possibility of translations to your text. I’ve explained in the past that some words are translated to be much larger than initially provided. In that example, the words “Buy Now!” translated to Mongolian result in “Одоо худалдаж авах!”, something much longer than expected. In layouts with limited space, we will want to wrap the text for it to remain visible.

In the following example, both buttons look similar in height, one using min-height and the other using padding-block (vertical padding).

In this next example, we reduce the available space. If we purely use min-height for the button to determine its dimension, we will lack space between the upper and lower edges of the button. Meanwhile, including padding in the button will ensure that there is always space from these edges; giving room for the text to breathe and not feel cramped.

Note that in these examples, I’m not including space in the horizontal direction. I’d argue that we’d also want to use padding here as well.

Line height won’t save you

Perhaps you have a personal vendetta against padding and want to do everything in your power not to use it. You say the line-height will provide the additional vertical space I need! And yes, it might but at a cost. Here’s what that looks like using the first example, replacing min-height with line-height to get a similar size with padding.

Now, here’s what happens when the text breaks onto two lines.

You’ll see that the line-height causes too much space to appear between the lines in the first button. This is expected because that’s the purpose of line-height; it’s meant to control the height of each line. While we don’t expect a button to wrap to multiple lines and cause this wide gap to appear, we should still be prepared for it.

Also, know that the resolved line-height value will be presented differently between different fonts and their metrics. I love recommending this post by Vincent De Oliveira to deep-dive into the differences. So if you don’t want the size to be related to the font, then line-height isn’t your tool.

Set the line-height value based on what you’d like to see when the content wraps to multiple lines. This goes for any prose, not just the button. You should not be setting a line-height value when looking at only a single line of text.

Why not use both?

Because it’s redundant.

The padding contributes to the height of the component (along with the line-height). So as long as there is content inside the button, the button will be the same height related to the content within it. min-height is only useful if we expect the button to not have any content within it and that should never happen. If it does happen, you have larger problems than the height of the button.

Mixed content

Now, I’m sure you are already thinking of an exception where there is mixed content in the button; specifically an icon with text and those elements do not share the same height.

There’s a great deal of nuance in this area, but the bottom line is that you want the space that the icon occupies to match the line-height of the font it is paired with. This may mean that you’ll include a negative margin-block using a unit related to the current font metrics to get the appropriate optical placement without adding to the overall size.

In the above example showing buttons from Adobe Spectrum, placing the icon on the font’s baseline would not vertically center the glyph. We must offset this at the icon. Here’s an example of a few approaches, all with the padding-block property set.

Button with no icon.
Button with icon using negative margin related to the font metrics.
Button with icon using vertical-align related to the font metrics.
Button with icon without alignment adjustments.

In the second and third examples, the icon is optically centered with the text. The difference is how much the icon contributes to the button height. In the third example using vertical-align, the height still contributes to the overall size, causing the button to be much larger when an icon is provided, even while centered with the text.

Using the negative margin with the correct value can also be used when text does not appear within the button. Here’s the same example as above, now with an icon-only button which also uses the negative margin value.

I’d suggest that your icon component should be built in with a negative margin based on the current font metrics. Getting the font metrics to behave isn’t easy but some CSS properties are coming that might be useful. This is especially critical in a themed ecosystem as the resulting value for the negative margin will change depending on the font properties for any given theme.

Thoughtful units

Here’s one final hot take, and it happens to be an argument against what I’ve previously thought in the past. Consider not using (r)em for size/space. 😱

Josh Comeau has an excellent demo of this in his post. The reason why we apply space to anything is often meant to show relationships between elements. In the case of the button, we are applying space for an additional reason; to increase the size of the target for better clickability.

If the font size were to increase due to the user’s zoom, the target area would become larger as a result when the content dictates the size of the element. We do not need to also increase the space surrounding the button; the resulting content size is enough to click. In this way, the padding is effectively contributing to the minimum height of the button.

In the other direction, if the user wants to decrease the text size, using a padding size that ensures a proper target area is available is recommended. Decreasing the text size is less common than increasing but could occur in areas where data is meant to be dense, like in a table to view more information.

If you want the size/space to be affected by the relative font size, use em.
If you want the size/space to be affected by the user’s font size preference, use rem.
If you want the size/space to remain the same regardless of these settings, use px.

I’d now argue that the final one is more appropriate than we might realize when it comes to relationships and user settings. The user is generally increasing their font size for legibility and has very little to do with increasing visible space between elements. Meanwhile, the user still has the option to zoom, which causes everything to be larger for nearly any unit being used.

It is still important to use relative units for typography.

We should be deliberate in the reason why we choose to make these design decisions and keep in mind that we have very little control over how a user might want to experience the stuff we make.

Button width styles

Fri, 05 Jul 2024 00:00:00 GMT

My wife asked me a question one morning:

Are there any good reasons why a button should have a min-width?

My quick response was “No” and she agreed without much contest. However, I figured I’d ask the internet to see if there were any reasons we might have missed.

Moving forward, we assume that the button we are designing is the smallest possible in any particular set, as larger buttons will be less susceptible to the issues we’ll be addressing.

Accessibility

One of the big blanket statements in the replies was related to accessibility. Specifically citing WCAG 2.5.8 AA which says:

Undersized targets (those less than 24 by 24 CSS pixels) are positioned so that if a 24 CSS pixel diameter circle is centered on the bounding box of each, the circles do not intersect another target or the circle for another undersized target.

It’s important to note that 24 CSS pixels is a minimum and the better practice is to have target areas that meet the WCAG 2.5.5 AAA of 44 CSS pixels.

There are plenty of situations that we could imagine where a larger target would be helpful:

For folks using a device in a moving vehicle.
For folks who use less accurate pointing devices.
For folks that lack fine motor skills.

My stance on this is that button construction will contribute to the overall accessible size using styles like padding and the existing content to meet this without much more to add. Additionally, buttons with words inside should have the proper content that is descriptive and avoid vague labels like “OK.” More on this below.

Localizaton

Having a more descriptive label doesn’t necessarily mean that buttons with only two characters won’t exist. According to Mike Mai, it’s common for pages that display CJK languages to have a button with only two characters.

Meanwhile for languages that would cause the button to be larger than originally designed due to translation, a minimum width would be easily exceeded. In an example I’ve used before, the words “Buy Now!” translated to Mongolian results in the text “Одоо худалдаж авах!” overshooting any reasonable min-width that might have been applied. The min-width is intended for when the label is too small, not when it is large.

Speaking of when a button has a long label, we should not truncate the text in favor of an ideally sized button. We must curate the label in such a way that it is descriptive and concise. If the text must wrap, let the text wrap and continue to be wholly visible. I’ve written a bit more on this topic recently.

Icon button

It is also not uncommon to have a single glyph within a button in the form of a square icon button. If the button is meant to be a square, then its width and height should match by definition. Since we’d most likely want a standardized height for buttons so they align with inputs and other text elements, the width would be naturally restricted to this recurring height.

Therefore, the smallest button in the library should be the square icon button which must meet WCAG 2.5.8 AA as defined earlier; a minimum of 24 CSS pixels in both dimensions. No minimum width would be apparent when set in this configuration using only an icon. The minimum width of the icon button would be the size of the icon plus any additional padding and borders, adding up to at least 24 CSS pixels but optimally 44 CSS pixels.

LooksGood™

There are plenty of responses that provide the opinion that setting the min-width will make buttons with smaller labels visually more appealing than without. Such as if there were two buttons labeled “Yes” and “No”, the designer might expect the width of both buttons to match in size. There isn’t any data from a usability perspective that I could find that supports this design choice as beneficial. It is a matter of subjective design preference. I also believe that better content design would make this unnecessary. The need for a min-width presupposes that the content in the offending button could be improved with a more descriptive label.

Other points

There was a point that listed predictability, consistency, and readability as factors that would involve setting a min-width. In the cases of predictability and consistency, the visual treatment of the button using color, typography, and other styles would contribute more to these factors than the width. I’d even argue that a min-width button would be less visually consistent than one without because of the horizontal padding. A “Yes” button with a min-width set would be perceived as having more padding than buttons that don’t reach the min-width.

Meanwhile, if all buttons were perceived to have identical padding, this would be a more consistent visual treatment. In the case of readability, this is determined by font metrics, icon design, and color contrast, not the width of the containing element.

Another point shared was about buttons in spatial computing. Admittedly, I’m not well-versed in these interfaces so I asked some questions about the interaction design for these. According to the thread, these buttons will grow as you gaze at them with your eyes, indicating that a particular button is an intended target. The button is commonly triggered using a pinch but could also be by finger touch, which aligns with earlier recommendations discussed above. I’d also imagine that visually small buttons could be made larger by changing one’s perspective similar to how browser zoom controls would work, but without the layout shifts.

The only reason

So if we were to assume that the button is designed in good faith, with appropriate padding and borders, using legible font metrics and color contrast, and having either a well-identified icon or descriptive label, that this button would not need a min-width to be set.

However, there is one reason why we might want to consider setting a min-width and it has to do with CSS Flexbox. Kevin Powell has made a great explainer video speaking about the behavior so I recommend watching it for more information. The tl;dr is that because most buttons these days are designed using Flexbox, then I’d recommend including the following rule with the declaration to help with text wrapping when it’s needed:

button {
    min-width: 0;
}

Without it, it’s possible that text within the Flexbox could overflow outside the shape as an unintended consequence of responsive behavior and translation. It’s important for the content to flow naturally, and setting this rule when using Flexbox helps support that expectation.

So from a design perspective, I’m not convinced that setting a minimum width for the button has a reason for usability as long as other aspects of the button are well designed. From the engineering perspective, setting min-width: 0; on the item will help support content wrapping.

Chip Away

Mon, 23 Feb 2026 00:00:00 GMT

One of the most confusing but ubiquitous patterns in design is “small text with a background color that may or may not be interactive”. To some that sounds like a button with an identity crisis but to others they might recognize this as a few names: chip, badge, pill, tag, or even lozenge. It’s bad enough that the definition of these things is contested, but what is worse is because they are all generally so visually similar, it makes it hard for the users to know what they are meant to do.

Let’s play a game

As a little exercise, all of these are from the same design system. Try to guess what the name of each of them is:

Before I reveal the answers, just think about my earlier definition of these things. They all match the description. Remember that users aren’t discerning the small idiosyncrasies between them, they are most likely lumping all of these into the same category “small text with background color”.

Ok, next exercise. Here’s the definition of each of these components:

A visual indicator used to communicate status.
A compact label used to classify, organize, and categorize information.
Used to display numeric status data.

The definitions here might give you a hint about which of these components they are assigned but only because of the content found in the examples. Again, think about what is more likely happening. A designer is probably thinking I need “small text with background color” and every one of these satisfies that criteria. How often do we find designers justifying which one of these things they are meant to use? I’d argue it’s more common to have a preconceived notion of the visual design without thinking why they are choosing that approach. It’s usually gets reduced to “I’ve seen it before” or “this other big company does it” without much of a conversation to justify the decision. We’re encoding a few whys as definitions to justify different components, but in the end we often miss how that why is helping our designers or our users.

The answers are below:

Badge is a visual indicator for numeric values such as tallies and scores.
Lozenge is a visual indicator used to highlight an item’s status for quick recognition.
Tag is a compact label used to classify, organize, and categorize information.

Filters and categorization

The following examples are from Uxcel, specifically their page on “UI Chips”. Take a close look and try to figure out the difference:

These are the first images of their explainer where one of these is described as a “do” and the other as a “don’t”. At a glance, it’s very hard to tell which the do and don’t is. Here’s the text from their explainer:

You might wonder how chips differ from buttons. They can look similar, but they work differently. Chips, especially when used as filters, help users narrow down or adjust what they see without leaving the current view…

Buttons, on the other hand, are for clear, single-purpose actions like “Save,” “Submit,” or “Cancel.” They’re used when the user needs to make a decision or move to the next step.

But isn’t filtering an action? To filter is a verb, therefore an action. And each of these chips is filtering meant for a single-purpose, to filter the entities represented by the label. Buttons aren’t meant to leave the current view either, they are meant to execute an action.

It’s very easy to pick the definition apart to show that there’s not much difference happening here, not just visually but also behavior. The only difference that I could glean from these is that the labels on the chips are nouns, representing the entities that will be affected once you tap the button. Meanwhile, the buttons have verbs telling you what will happen. For buttons, this is good practice. The label is describing an action, and a user reading that label can assume interacting with this element will perform the action on the label.

But the chips example is very ambiguous. Again, users don’t care how you classify this thing as a button or a chip. They are trying to figure out how it is going to help them. So, they’ll look at the chips example and potentially wonder what the “Vegetarian Button” does. Some folks will tap it, some won’t because it’s not clear. Now, let’s see an alternative:

I know what you’re going say: “Donnie, that’s too much text!” In comparison to the original, absolutely. However, you can’t argue that this approach is more clear about how I’m meant to interact with this UI, and what the result will be. If the amount of text on each label is truly bothering, consider a hybrid approach:

But hold on, are those chips in the original comparison image actually filters? Take another look, because these things could simply be describing the attributes of the location, and not actually do anything if you tap them. If that’s the case, then the image barely matches their description of a chip! If these chips aren’t filters, then it’s just a stylized list.

Schrödinger’s button

This is ultimately the largest problem with this pattern. It is very often a guessing game to figure out if this thing is interactive. Take a look at this example and ask yourself, can I click the element that says “Pro”?

The answer is 🤷, it’s Schrödinger’s button. You only know if you can interact with it until you do. Until then you are left guessing about if you can. You might think, what is the harm of tapping the button to find out? You might be surprised in research that shows a type of koumpounophobia; a fear of buttons:

…older adults had many negative emotional user experiences, including fear of pressing buttons and embarrassment of incompetence.

So, it is possible that your user won’t even try and never discover something that you felt was useful because they don’t know what “Pro” does. Does it work like a checkbox and revoke the “Pro” status for this person? Does it tell me what a “Pro” is? Does it tell me why this person is a “Pro”? The fact is, this element is probably not interactive. So, don’t make it look interactive.

Or if it is interactive, tell me what it will do. Make it a verb. Be deliberate in this decision. And of course, make it look like a proper button.

You should also ask, does this need to be in the interface at all? Is it important that a person know this is a pro user? Ask yourself what is that importance. It’s true that social comparison is a motivating factor and seeing someone with a physical conference badge walking around your city can have a fleeting thought “I wonder what they are showing at that conference?” So, having a digital badge on your profile, like a verified badge has a similar effect. If that’s the case, consider using other treatments that show status that are clearly not interactive, such as typographic hierarchy to show importance.

In this example Cally is both a “Pro Member” and a “Photographer”. We display a slight difference between the status that was given to user from the status that was chosen by the user. If icons are well understood within the product’s ecosystem, you can consider adding an icon to further highlight the status.

Tag inputs

Sometimes, this element is used in combination with a text field. The tag input is a pattern where you have an input field that allows you to enter text, and when you hit a special key (like a comma), it creates an entity with the text you entered. The benefit of this pattern is that a user can create several entities on the fly. Otherwise, the user would need to create an entity, give it a label, and save it for each piece of information they want to enter. With a tag input, they can just keep entering text and creating new entities without having to go through the process of creating and saving each one individually.

The challenge with this pattern is accessibility. When keyboard navigating to each chip, how does it focus? At first you’d expect to focus the entire chip, but then the next tabbable element would be the “x” button inside the chip. This means that technically we have an interactive element inside of another interactive element, which is an accessibility violation. This also requires someone to tab twice to move to the next tag.

The more appropriate approach is to make the tag a non-interactive element, and only make the “x” button interactive. This way, when you tab to the next tag, it will focus the “x” button, and you can press it to delete the tag if you want. This also means that you can easily move to the next tag without having to tab twice. Think about it, why would you want a person to focus a newly created tag if the only thing they can do with it is delete it? It doesn’t make sense to have a person focus something that they can’t interact with, and then require them to tab again to interact with it. It’s much more efficient to just focus the interactive element directly.

Another note about accessibility for this pattern is that when you create a new tag, you should announce it to screen readers. This can be done using an ARIA live region, which will allow screen readers to announce the new tag as soon as it’s created. This way, users who rely on screen readers will be aware of the new tag and can interact with it if they choose to.

<div aria-live="polite" aria-atomic="true" class="sr-only" id="announcer"></div>

And then when a new tag is created, you can update the content of the live region:

announcer.textContent = `Tag added: ${value}. Press Backspace to remove.`;

While it is common to visually put instructions on how to use the tag input below the input field, it would be better to show this information above the field. This goes for any input field, but especially for fields that have uncommon behavior, such as eating commas to create tags. Imagine how confusing it would be to have an empty canvas and not know what you’re supposed to be doing with it until later. Having instructions upfront prepare the user for what is about to come.

Don’t forget that users can also dictate in accessible technologies, and depending on the user’s settings, commas may be inserted automatically instead of deliberately. It is possible that for some users, speaking the word comma will enter the literal word “comma” instead of the punctuation. This is something to consider when designing the interaction for this pattern, as it may not be intuitive for all users. There’s also no reliable way to know if the user is dictating, as this is often supplied by the operating system. This also doesn’t account for an Input Method Editor (IME) for non-Latin languages, which may have their own unique behaviors when it comes to punctuation and special characters. It’s important to consider these edge cases when designing the interaction for a tag input, and to provide clear instructions for all users on how to use the feature effectively.

Unless, you simplify by using a pattern that nearly every developer has built as their first project:

No delimiter parsing
No dependence on comma
No IME conflicts
No dictation ambiguity

This is a much more straightforward approach, and it still allows users to create multiple tags on the fly without having to go through the process of creating and saving each one individually. It’s also more accessible for users who may have difficulty with the original pattern, as it doesn’t rely on specific key presses or punctuation to create new tags. Overall, it’s a simpler and more inclusive design choice for a tag input feature.

A hard pill

While this post seems to be stripping all of the fun out of user interface design, the intention is to encourage designers to be more deliberate in their choices. To stop and think about how people outside of their tech circle might use this product. If you are going to use a pattern that has ambiguity, make sure you are doing it for a good reason. If you are using “small text with a background color that may or may not be interactive” just because it looks nice, then you might be alienating users; users who want to pay for your product. It’s important to remember that design is not just about aesthetics, but also about usability and accessibility. By being more intentional in our design choices, we can create interfaces that are not only visually appealing but also easy to use and understand for all users.

Choose wisely

Mon, 15 Aug 2022 00:00:00 GMT

If you believe in free-will, options are most likely a foundational aspect of your philosophy. Designers are responsible for presenting choices to users so that they may select the best option and advance toward a goal. Historically, we have introduced several patterns which support the ability for users to make a choice. In this exploration we will consider some common interface components and understand why we might decide to use one over another.

Ground rules

The abstract concept we’ll be focusing on is a group of similar items and the ways they can be presented and interacted. This means singular buttons and inline links aren’t included in this exploration.

The act of creating an option will also be avoided. Generally speaking, once the option is created, it’ll be included within the existing presentational group of options using one of the approaches described. An example of this might be creating a post category for use in tagging entries in a blog.

While important, this exploration will not be focusing on the curation of the content within an option. Certainly, poor choices in wording or inaccessible options will inhibit the user from making the best choice. The following exploration assumes options are well-crafted.

Definitions

The following patterns will be referenced throughout this exploration:

Button groups: Examples are found in word processing tools for selecting text alignment.
Radio button groups: Examples are found in online surveys to rate quality of service.
Checkbox groups: Examples are found in selecting options to filter products.
Native HTML select options: Examples are found when selecting locations from a list.
Navigational menus: Examples are found in the header of marketing sites.
Context menus: Examples are found as right-click to copy.
Tab groups: Examples are found within web pages as secondary navigation.

Button group confusion

What I’ve defined as button group above is not a common button group found amongst most design systems. The key difference here is the keyboard navigation. A button group is often delivered as just a layout pattern of existing buttons with very little change of visual style and no change in interaction pattern. Each button is accessible via the Tab key like any other button that isn’t in a group. Because of this, I identify these as groups of individual buttons. There’s nothing stopping most systems to allow any sort of interactive component to exist in these groups; like links for example. For this I recommend providing a layout component instead of something specific for buttons.

However, I am specifically calling out the pattern found in toolbars as it is expected to be a single tab stop, where navigation between buttons is done by arrow keys. Visually these are groups of buttons but with a different and warranted enhancement for accessibility. This pattern can also be found in listboxes, comboboxes, and menus which also expect arrow key navigation between options within a single tab stop. A segmented control is also of the same family but more related to radio buttons.

To reiterate, this behavior is not meant for usage with most groups of buttons found within an interface, as each is commonly expected to be an individual tab stop.

It’s also important to define a few terms used for accessibility:

Tab stop: An area of the interface which is focused by the Tab key where additional actions can occur. Links and text input fields are clear tab stop examples, but entire lists of options can also be defined as a single tab stop. The area that should be identified as a tab stop is achieved through accessibility best practices for an experience.
Roving tabindex: A technique to show focus on an element without the use of the Tab key. This is done by toggling the tabIndex of interactive elements. One element in the list will receive a tabIndex="0", while the rest receive tabIndex="-1". This allows the user to re-enter the area using the Tab key and return focus back to the previously focused element. Here’s a video explaining the technique by Rob Dodson.

Instant gratification

One of the attributes of making a selection is the immediate result of the interaction. Patterns that show new content based on the selection are commonly immediate. For example, navigational menus which redirect to new content should be instant. Buttons that update state like deleting a row of data are also expected to happen quickly.

This is in contrast to options which expect a user to make selections and then commit those selections in a final action. This is commonly form elements such as radio buttons, checkboxes and HTML selects. The user will choose these options but no updates to the larger system will be made until the user sends a final command. This is often the case for wizard experiences also, where the act of going to the next step submits the options selected before traversing further.

This means we can divide the patterns into some groups:

Instantaneous
- Button groups
- Navigational menus
- Context menus
- Tab groups
Confirmational
- Radio button groups
- Checkbox groups
- Native HTML select options

Links vs Buttons

Full disclosure, I am a big proponent for clarity of intent. I believe links should have an underline and navigate to new pages, allowing for all the default behaviors an <a/> tag provides. Buttons should have visible padding and execute actions on the current page, allowing for all the default behaviors a <button/> tag provides. With that out of the way, there’s additional level of consideration for the difference.

Links (<a/> elements) are meant to be individual tab stops always. This means that if the link is meant to be navigational and sends the user to a new page, the user should be able to go to this element using just the Tab key.

For buttons (<button/> elements), this isn’t the case when prepared as a proper group of related controls. The group is expected to be a single tab stop. Once within the tab stop, a roving tabindex pattern is used to traverse the controls.

This is a good place to introduce the tab user interface pattern which commonly is treated to look like manilla folder tabs. If the tab interface you prepare expects each tab to be a navigational link that can be revisited using the browser’s URL bar, this means that each tab is an individual tab stop; as link behavior is expected. On the other hand, if each tab is meant to execute a command, thereby keeping the user on the same page, then the entire tab group is one tab stop with roving tabindex navigation. In this way the tab pattern can either act as a navigational menu (using links), or a button group (using buttons). The main decision goes back to the links versus buttons debate to decide which experience to use.

Let’s continue to group our patterns:

Instantaneous
- Navigational
  - Navigational menus
  - Tab groups*
- Functional
  - Button groups
  - Context menus
  - Tab groups*
Confirmational
- Radio button groups
- Checkbox groups
- Native HTML select options

Confirmation follows form

Returning to the confirmational group, these are patterns most commonly found in forms. This aligns to the way which we would fill out paper forms by entering in all the information first before submitting.

One of the most clear indications of usage between these patterns of the group is between checkboxes and radio buttons. Checkboxes are meant for selecting more than one option, while radio buttons are used for selecting a single exclusive option.

Interestingly, the native HTML select allows for both configurations (using the multiple attribute for multiple selections). So the question is, why use the native HTML select when there are other patterns which more clear usage?

One of the properties of the HTML select is the limited amount of data shown. The element is restrictive to a word or phrase which represents the value for selection. The other patterns allow for much more information. In relation, the select only displays the selected value. This means that it is less likely that the user will review the selection since it requires extra interaction. Laying out all the options as checkboxes or radio buttons help the user consider all the possibilities. Additionally, the HTML select options are not bound to the page layout; its options will exist separately from visual flow. This supports the basis of using checkboxes and radios for options which need more detail from options that are concise.

Let’s break down the options one more time:

Instantaneous
- Navigational
  - Navigational menus
  - Tab groups*
- Functional
  - Button groups
  - Context menus
  - Tab groups*
Confirmational
- Verbose
  - Exclusive
    - Radio button groups
  - Multiple
    - Checkbox groups
- Concise
  - Native HTML select options

Flow

Here’s a visual representation of our decision tree:

  
graph TD
    A[Give user a choice]
    A --> B{Happens immediately?}
    B -->|Yes| C[Instantaneous]
    B -->|No| D[Confirmational]
    C --> E{Directed to new page?}
    E -->|Yes| F[Navigational]
    E -->|No| G[Functional]
    D --> H{Include considerations?}
    H -->|Yes| I[Verbose]
    H -->|No| J[Concise]

The flow chart above can help lead a path toward a decision by asking why…

Why does the user need the action to happen immediately?
Why does the user need to remain on the page?
Why does the user need more information about this choice?

Adding purpose to these decisions will ultimately support design decisions with clarity. You can be confident that the pattern chosen is the best one based on the answers to these questions.

Unavailable options

A pattern that may be examined is disabling an option. This could occur because the user hasn’t satisfied criteria or the system is not yet prepared to offer the option. Opinions vary about the decision of showing options that the user is unable to select. I believe the following questions can determine if showing a option as disabled is helpful to the user.

Will the option be available to the user if criteria are met?
Are the criteria for the option clearly shown in context of the option?

If the answer to the questions are “yes” then it may be appropriate to disable the option. However, note that disabled options aren’t detectable to screen readers and commonly lack sufficient color contrast. Providing the criteria for enabling the option will support these deficits. Vitaly Friedman goes into greater detail at Smashing Magazine.

To put it simply, if it isn’t important why include it in the experience? This segues into the next topic.

Abundant options

Presenting the user with too many options introduces a cognitive load and decision paralysis. As described by Hick’s Law, the more choices you present, the longer it will take to reach a decision. This might include halting the current flow to return to at a later time. In contrast, limiting the number of options will improve the user experience. While some patterns expect to provide dozens of choices (eg. country of origin), there might be better design choices to capture the same information (eg. text field filtering of the list).

Use empathy to drive your design choices and your users will be thankful.

Clarity 2024, Backstage

Fri, 27 Sep 2024 00:00:00 GMT

Clarity, the original design systems conference, just wrapped its 9th iteration this year. I was part of the small group of community volunteers that helps put the event together. I’d like to pull back the curtain behind the technical side of the event; somewhat to play Monday-morning quarterback on things I would have improved in my role on my end.

Playback

We planned to have all the talks pre-recorded, so one of the key parts of the setup is to have playback. Having pre-recorded talks helps reduce the need for multiple connections to perform the talk live. It’s hard enough to prepare a presentation, it’ll be even harder to troubleshoot connection problems on top of it.

To do this, I was looking for a dedicated device that would handle playback. In my mind, I was expecting to find a modern device that could provide clean HDMI out, display local time remaining for the media, and physical buttons to navigate files and playback. In all my searching, I couldn’t find the perfect device with those requirements. It’s wild to me that this doesn’t readily exist.

The fact is, much of this is done with software now. Usually you’ll have folks who stream handling everything with a single computer with OBS and a StreamDeck. This is certainly a viable solution but I’m old school. I’ve been streaming for a long time; before Twitch, before even YouTube. I’d take a RCA encoder and hook that up to stream super low-quailty camcorder video using RealPlayer back in the day. So it is important to me that there are separation of concerns. If you have everything being handled in a single spot, if that spot goes down, everything goes down.

The video switcher I use could load the videos inside of it, but I believe a switcher shouldn’t be used to navigate and play the videos. It’s main role is to cue and stream a media source from the outside. So for playback, I ended up using my wife’s spare laptop. This is a subpar solution for a few reasons:

You can’t navigate the files while media is playing.
You’ll have the system UI show during some setup.
You can’t see time remaining on the video to cue talent.

Thank goodness the spacebar was the physical button to start/stop the media. Though I wish the screen wouldn’t have flashed the icons in the corner when doing so. A quality media player wouldn’t need to show that in the feed but in some exterior menu instead. I do wish this is something that can come to the prosumer market or perhaps something that could be more seriously considered in current hardware switchers. My hardware switcher has 8 slots for media but preparing the media is a hassle through the menus.

This laptop was also the “Character Generator”, which is a fancy term for a source that can show text and graphics. This means that I can’t prep any text or graphics for the next segment until I’m clear from the playback. I’d have to cue up the next items during the live Q&A.

Live Q&A

It was important to have some live element to this event so it wouldn’t just be a playlist. When we were in the early stages of coordinating, John Allsopp warned that broadcasting live, especially a conversation, is very tricky and prone to many problems. He’s absolutely right, I definitely wouldn’t recommend trying to do this if you haven’t before. There’s a lot that can go wrong or be otherwise frustrating. I say that from experience because my master’s degree is in live event production and this is the sort of thing that I focused a lot of attention on. Back then, we even had some prototype devices for broadcasting Skype calls and successfully did live chats on a weekly basis. The technology is certainly better now, but still not perfect, especially for a scrappy show like this.

To do the live Q&A, I wanted to leverage a reliable call technology where I could pull the source media out to the feed for later compositing. Zoom is what I chose, along with the help of a program called Zoom Bridge which creates NDI sources from the call. I was unfamiliar with the NDI protocol, but it’s a new way of sending media over the network. This means you can have media playing over a network switch and devices can find that media to be played.

The thing about this technique is that it is bandwidth intensive so I was very worried about attempting to create NDI media streams on top of the bandwidth used for the live stream itself. I took some time to try and make a local network specifically for the NDI sources but I couldn’t figure it out. I’m not an network engineer. The best I can normally do is release/renew an IP config. Ultimately, the tech checks seemed to show this shouldn’t be a problem and after completing the event, it’s clear it wasn’t an issue. I wonder how many NDI sources it would take for it to be noticeable.

Now, that I had NDI sources from Zoom, I had to get them out of the computer and into the switcher. I purchased a NDI to HDMI decoder to get the streams to convert to HDMI for the switcher, however it seems that each decoder could only handle one source. That would mean I’d need two devices, one for each call participant. Instead, I decided to use OBS. OBS has NDI input source options and can also export the program as an NDI source. So, I made a few simple scenes for the live Q&A in OBS, prepared some hotkeys for the number pad on the keyboard, and sent the whole thing out as a single NDI source to the switcher.

The flow during the Q&A portions worked fairly well. Our speaker would join the private Zoom call where Jina and I were waiting. I’d set the participant as the new source in the Zoom Bridge, which gets the media into the premade OBS scenes. After the presentation video finishes, I’d switch to OBS and cue Jina. Then all of the live Q&A switching would happening with OBS and the 3 scenes: Jina, the speaker, and the split screen (also designed by Lauren). This ended up working better than I was expecting. In my experience, I’d used to having all switching happen from one station because it is easy to confuse otherwise. Separating the live Q&A switching from the main program switching helped focus attention to the flow of the conversation. Also helped since my switcher doesn’t have many source inputs and OBS could take many more through software.

Like I said, I’d still rather not use a computer as a source because there’s too many things that can go wrong. This was the case for the first day. During the first day, the Zoom connection was awful. It was hard to tell with just Jina starting since it could have only been her connection, but when Dan signed on it was very clear that my connection was the problem. It was then I noticed the Zoom computer was connected to the house WiFi instead of the main fiber. After I switched to the main fiber, everyone had a much better connection with one flaw.

I could see in my studio that there was an audio delay, and I also received a few reports on it. I had no good way of adjusting this during the live stream because of another topic I’ll bring up soon. At the end of the first day, Jina and I did a quick tech check where I’d focus on synchronizing the audio with the video. Apparently we were an entire second (1000ms) off. I was able to enter a delay in OBS to prepare for the next day.

During the next day, we did another test on the delay. In doing this I found there was no delay! My assumption is that when I switched the Zoom WiFi during the stream, the sources became slightly out of sync. Now that it was a new Zoom call, it must have re-synchronized. So all of the live Q&A portions on the second day were executed very well, and I’m kicking myself for not doing more testing to identify the problems that happened on the first day. A learning experience for sure.

I do wish that there was prosumer device that could handle this stuff more gracefully. Maybe with all the great tech RØDE has been making they could consider it in their next device.

Audio

In just about any event, audio is the most important facet. It’s one thing to be showing images but the content that comes from the audio is most noticeable. This is where I really would have loved to have that dedicated Zoom device instead of a computer. The way my computer settled audio was to simply output the desktop audio to the stream. This would be the same audio that you might hear in the Zoom call you’d have in a meeting. It will include all of the audio for the computer in a single channel out to your speakers or headset, except your microphone audio. I don’t know if the NDI sources would have accepted individual channels of audio as sources in OBS. I think I tried it a few times and never got more than the desktop audio working.

However, because OBS decided that it wanted to use desktop audio as the output, that apparently meant that if I changed my desktop audio output to be my headset, that the audio would not go out to the switcher. That meant I needed to keep the desktop audio as the source, and that the Zoom call would fill my room with sound. This was a problem since I was trying to monitor the live stream which was on a slight delay from the computer. This was incredibly distracting. To provide some relief, I’d keep myself on mute for the Zoom call to spare others from hearing the stream through my microphone. I did try to use headphones on the switcher toward the end of the first day, but that was also awkward when coordinating over the Zoom call.

If I had a better understanding of how the computer and OBS handle routing audio, I would have rathered having separate audio channels for each person, and to have the Zoom call in the headset and the program playing in the room. This was probably most apparent when I went live on camera in the middle of the second day. This was unplanned so I wasn’t sure what sort of audio setup I’d need to adjust. I suspect the echo that was occuring was either the program playback (that I thought I muted) or the Zoom audio coming from the computer. Either way, I did my best to ride the OBS mute button to limit the amount of noise. Hopefully it wasn’t too distracting.

That’s another big reason why I like hardware solutions over software. It’s very clear how the sources are traveling into the equipment as physical cables. I’m sure plenty of folks can relate to struggling with Bluetooth devices connecting and disconnecting, OS switching audio settings as a result. This is actually what happens at the very beginning of Dan’s presentation. I disconnected a source I wasn’t using on the playback laptop and the OS switched to the internal speakers instead of over HDMI where it was originally connected. Luckily I noticed this quickly seeing empty audio levels and did a quick restart. This doesn’t happen when working with hardware, the audio is always connected.

Don’t try this at home

In reality for a production like this, there should be at the very least 4 people handling the parts. One for the video playback, one for handling live Q&A, one for character generation and one for the stream itself. That’s not counting the stage management job that my wife Jennifer graciously volunteered to handle. We were able to get nearly every speaker cued up and live for the 2 day event, with only one person that had a schedule conflict.

After moving to tech I never thought I’d be running live coordinated events again but I’m glad Jina and the team gave us a chance to do it. Many thanks to the speakers, the volunteers, and the community for all its support.

Will the Design Systems House promote itself with a live event production side business? It depends™ 😊

Classname soup

Tue, 17 Jan 2023 00:00:00 GMT

The internet blew up again regarding CSS frameworks and there have been no shortage of responses. While this could just be more fuel to the fire, I hope this will be evergreen and reflect on any similar approaches that are developed over time. This also has the benefit of avoiding the name of any single framework in particular and instead comment on the direction as a whole.

Lightbulb moment

Recently, I realized exactly why I was aversed to utility class resources after watching Fireship.io’s video responding to the recent debates. The lightbulb lit for me specifically at this quote.

The benefit is that you don’t have all these arbitrary classnames anymore and know exactly which styles apply to it.

— Fireship.io

#naming-is-hard strikes again. There’s two parts in the quote that I’ll touch upon.

Knowing styles exactly

Declarative classnames are not scalable. In a world where we lean hard into semantic tokens to help describe the experience in terms of purpose over value, we release control of the final presentation of the design to be informed by tokens way up the stack. We no longer prescribe that this card border thickness in this very specific spot must be 3px. It should instead be applied by way of a mapping of a semantic token to a value in a theme curation exercise.

Therefore, it is not flexible to prescribe themable style via a classname. Using .border-teal-darkest has the same problem as having a token which is --border-teal-darkest applied directly to a component. It’s not semantic. While you could dive deep into this by adding more classnames to address themes, it will become unwieldly. Additionally, I’ve also thoroughly described the perils of calling something “dark” which also has this vulnerability.

It’s hard to think in this abstract way, as folks who have been building UIs to specification have been forced into “pixel-perfection” for years. While we don’t use the term much anymore, the effects remain. Designers will be disappointed if they expect to have exactly this color or precisely this thickness when working within their one context when multiple exist.

Reasoned classnames

If it has a purpose, it should have a name. The screenshot example in the video during the quote shows a large red ‘x’ over some CSS with the following classnames: .main-navbar, .main-navbar-list, .main-navbar-list-item. From this list I can tell exactly what component will be affected by these styles. It should only exist in one part of the project.

But what if it doesn’t? That’s the whole problem with naming. I could have another .main-navbar or worse .btn provided some some third-party library which then starts a style battle. I’m a lover, not a fighter!

One answer is to have a standardized method of coming up with names; similar to the semantic token scheme perhaps including a namespace to distinguish between ownership. I believe a first approach could be to have the semantic token name and the classname to be near identical, differing only in the property that the token should be assigned being encoded into the token.

.ds-main-navbar {
  background-color: var(--ds-main-navbar-background);
}

In practice, I don’t recommend being this specific but the concept is important. If you are too specific in token names, you’ll wind up with thousands of tokens to describe every property of themable appearance. A better approach is to be slightly generic in the semantic token to cover several possible uses, but remain specific in the classname.

/* These are specific styles for the main navigational bar component */
.ds-main-navbar {
  /* token covers the background for all navigational surfaces */
  background-color: var(--ds-surface-navigation-background);
}

The token can be applied to other similar surfaces but the classname identifies this specific component and the styles it needs. This can be similar to the BEM (Block Element Modifier) structure for classnames which identifies the parts of a component.

This functions well for themable properties, but what about layout? Perhaps you don’t want to continue to type out all 59 characters of grid-template-colums: repeat(auto-fit, minmax(240px, 1fr)); over and over again. I think that’s a reasonable critism to have. In that case, it sound like you might have a new component on your hands.

Component driven development

In my opinion, the best approach is to not have classes at all. Instead I believe we should scope the styles to uniquely to the component. This can be accomplished in some CSS frameworks or using Shadow DOM.

Using the Shadow DOM technique, you can leverage id instead of class which further demonstrates that there should only be one of these elements within the component’s scope. In the Shadow DOM, the elements and styles aren’t exposed to the outside DOM so duplication across different components is valid.

<style>
  #main-nav {
    background-color: var(--ds-surface-navigation-background);
  }
</style>
<nav id="main-nav">
  <ul>
    <!-- Generated on mount of the Custom Element -->
  </ul>
</nav>

You could also avoid these attributes altogether in the Shadow DOM if the component is simple and semantic.

<style>
  nav {
    background-color: var(--ds-surface-navigation-background);
  }
</style>
<nav>
  <ul>
    <!-- Generated on mount of the Custom Element -->
  </ul>
</nav>

In CSS-in-JS libraries, this implementation might be more concise.

export const MainNav = styled.nav`
  background-color: var(--ds-surface-navigation-background);
`;

Not all of these components need to be exposed to users. Some of them are internal where the names won’t be so critical. For example, the .main-navbar-list which is internal to the .main-navbar is not important to external users. In both of the directions shown above, you can target elements even more generically if you possess anxiety over naming.

nav > * {
  /* this is the list but I don't want to name it */
}

However, I wouldn’t recommend this since it goes against the first point that if it exists, it should have a name. Just be comforted that internal naming is much easier to iterate on.

In lieu of scoping styles, create a standardized naming strategy that keeps classnames semantic and you’ll be better prepared to support a scalable experience.

Clickable cards

Fri, 08 Nov 2024 00:00:00 GMT

While having a good time with internet friends on Bluesky, I saw a thread asking about Josh Comeau’s website, specifically asking about why the entire card isn’t clickable. Josh’s replies concerning usability is spot on, and I’ve definitely been naughty doing the typical display: block on a <a/> element right here on the blog homepage. The replies in the thread also have some good suggestions but I was wondering if there was alternative. I have two main criteria:

Use HTML & CSS only, so there’s no need to listen for additional behavior.
Ensure that it meets user expectations both in terms of accessibility and also visually.

I think I have something…

Forgotten memories

In the list of HTML tags that people forget about, there’s two that are very often unused: <map/> and <area/>. These are meant to be used with an associated <img/> so a user can click defined regions of an image. The example for <area/> on MDN has a good sample of this.

The idea is that you define the areas’ shapes using some attributes and then group them into the <map/>. Then you assign that to the <img/> using usemap, which is a reference to the <map/>. Each <area/> can accept many of the same attributes of an <a/>, most importantly including href and target.

So what if we could include a visually hidden image the size of the card and then add an href to the entire area of the image? Let’s take a look:

Sourcery

We certainly don’t want to make a request for an image that is only being used to support this behavior. We’d want some resource that was quick and hard-coded. Stack Overflow has a topic on “smallest filesize for transparent single pixel image” which is exactly what we need. I’ll add a few additional attributes as well.

<img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIBAAA="
    aria-hidden="true"
    height="100%"
    width="100%"
    usemap="#name"/>

The aria-hidden="true" is added because this image is strictly to support the area that we want to click, we don’t want to expose it in the accessibility tree. The width and height attributes are ensuring that the image is the full size of the container it is placed within. And the usemap="#name" is meant to reference a <map name="name"/> somewhere in the page.

Next we’ll make the <map/> and <area/>:

<map name="card">
    <area
        alt="Design Systems Hot Takes"
        href="https://blog.damato.design"
        shape="default"
        target="_blank"/>
</map>

The href and target should be clear. The shape="default" tells the <area/> to be the same size as the <img/>. The alt is the same text you’d expect for images, except here we’re using it as the label for the link. On MDN, it mentions that this is used for browsers that don’t show images.

Finally, let’s put all of this in a card:

<div class="card">
    <div class=card-contents">
        Card contents
    </div>
    <map name="card">
        <area
            alt="Design Systems Hot Takes"
            href="https://blog.damato.design"
            shape="default"
            target="_blank"/>
    </map>
    <img src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIBAAA="
        aria-hidden="true"
        height="100%"
        width="100%"
        usemap="#name"/>
</div>

Styles

Now for some styles, and there isn’t a lot so I’m going to write everything below and explain:

.card {
    display: grid;
}

.card:focus-within {
    outline: 5px auto Highlight;
    outline: 5px auto -webkit-focus-ring-color;
}

.card > :not(map) {
    grid-area: 1 / 1 / -1 / -1;
}

.card > map {
    position: absolute;
    transform: scale(0);
}

First, the grid styles are a different way of getting the direct children to fill the container. Traditionally we’d place position: relative; on the .card and then position: absolute; on the img. However, that could cause layering problems since position creates a new stacking context. The grid properties here will make the children fill the container.

Next, the .card:focus-within listens for when the area element is focused and applies a ring to identify this card is ready to be interacted with. You can add your own indication, I’m using the default browser styles.

Finally, the styles for map ensure that it doesn’t take up any space in the composition but is still reachable with assistive technologies. The styles within here are a new way of supporting visually hidden so the alt text is reachable.

I have a CodePen of the implementation below, including the traditional block anchor:

See the Pen Clickable card! by Donnie D’Amato (@fauxserious) on CodePen.

Results

So now this should allow for all the normal link behavior; hovering to see the link destination, right-click to open in new window, etc.. This also allows for some more interesting options. Perhaps you’d want to allow for parts of the card to be clickable so that other text can be selectable, you could adjust the position of the <img/> to cover the area. Maybe you’d want to conditionally allow text in the card to be selectable. Use CSS to hide the <img/>.

Have I tested anything else past what I’ve said here? Nope. But, maybe someone can be further inspired and continue down this path.

Is this really any different from adding a display block <a/> and filling it inside the card like it is done with the <img/>? Sort of, since it would still need content for assistive technologies to read, and you’d need to wrap the content in a <span/> and visually hide it specifically for ATs, or maybe use an aria-label. Maybe it’s easier, but maybe there’s something to the approach above that makes it better in some way?

At the very least, I bet you probably learned about some HTML elements you haven’t heard of. 😉

Close thy enemy

Mon, 09 Jan 2023 00:00:00 GMT

You’ve seen it before, an ‘x’ at the corner of a surface which will allow the user to exit that surface. In design, it seems simple to just place the button at the top corner. To engineer this, we have a few options:

Absolute Position

The first option most folks might consider is something like the following:

.surface {
  position: relative;
}

.surface button.close {
  position: absolute;
  /* https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties */
  inset-block-start: 0; /* logical property for "top" */
  inset-inline-end: 0; /* logical property for "right" */
}

Many design system component libraries use this approach:

The problem with this approach is the way that position: absolute works. When applying position: absolute; to an element, it takes that element out of the normal flow of the document. This means that other elements cannot interact with this element.

In some configurations for the above components, the content (usually the title) could appear visually layered below the close button.

Some implementations solve this for by providing enough padding to the content area so the button never collides. However, this often results in an imbalance of padding and may not be desirable from design.

Flex header

Another method is to add the button as a flex child to a header of the surface.

.surface .header {
  display: flex;
}

.surface .header button.close {
  margin-inline-start: auto;
}

Here’s a list of components across design systems using this approach:

While this avoids a collision between the button and content, it also requires that the header exist which will be at least the height of the close button. In cases where additional header content doesn’t exist this displays a large forehead before the content.

So if the surface doesn’t have a title, the amount of space might not be desirable by design. Certainly, if design is attempting to curate the title, this might have some control. However, incorrect alignment could also result in the close button centering within the header instead of pinning to the corner.

Unique alternatives

There are some other approaches. Salesforce Lightning includes the button outside the modal which might not work for other surfaces. Their alert component uses the position: absolute; technique as an example which will have similar problems as described above. Adobe Spectrum avoids the ‘x’ button entirely and provides an explicit action to close the surface. However, their alert component suffers from problems using the icon accessory in relation to the title in this similar layout.

The “buoyant” approach

Let’s be clear about some requirements. If design is expecting a close button to appear at the top corner:

Padding around the surface should be visually consistent.
The close button should never move from the corner.
The content in the surface should not collide with the close button.

We can leverage two features of CSS to get an intended result.

Recent relative ancestor

In order to get an element to be positioned relative to another, we need to create a relationship. In the case of position: absolute; this relation doesn’t need to be between a direct parent and child. It can be any ancestor. This means we can have a distant child be positioned to ancestor located up the tree.

.surface {
  position: relative;
}

.surface button.close {
  position: absolute;
}

This is no different from the methods we’ve critized above except that the button.close element is a child of another element; our secret sauce…

Floats!

The way we get text to wrap around elements is by using the float property. We’ll float the button toward the right, so that content moves around it.

span.floater {
  float: right; /* inline-end */
}

While we’d like to use CSS Logical Properties for the float, they aren’t well supported. You’ll probably need to adjust the type of float based on the dir.

[dir="rtl"] span.floater {
  float: left;
}

Then our HTML should be setup in the following manner:

<div class="surface">
  <span class="floater">
    <button class="close">×</button>
  </span>
  <!-- Surface content goes here -->
</div>

You’ll need a bunch of other styles to finesse the size of the floating element and button in relation to the content. The final result should look something like this:

See the Pen buoyant button by Donnie D’Amato (@fauxserious) on CodePen.

Let me explain what’s going on here. In the demo above, the blue box represents the span.floater element dimensions. Note that because we’re using position: absolute; for the button element child, it’s not visually inside the span.floater but instead positioned relative to the surface. We set the dimensions of the span.floater so that the content won’t collide with the dimensions of the button and instead wraps around it.

You can remove the demo attribute from the <closable-surface/> element to see the final result without the blue box. I’m using a custom element so that it is easy to edit the content without accidentally altering the markup meant for the buoyant button.

Try removing the title, editing the content, or resizing the window. The content should never collide with the button and always sit at the top corner.

#make-floats-great-again

Colors don't solve problems

Mon, 11 Jul 2022 00:00:00 GMT

It’s unfortunate that the first entry at the Laws of UX is the “Aesthetic-Usability Effect” which is summarized with the following statement.

Users often perceive aesthetically pleasing design as design that’s more usable.

— Jon Yablonski, Laws of UX

The source for this law is from an NN/G article which I find does a much better job summarizing the concept.

Users are more tolerant of minor usability issues when they find an interface visually appealing. This aesthetic-usability effect can mask UI problems and can prevent issue discovery during usability testing.

— Kate Moran, Nielsen Norman Group

The difference between the two statments is that the former suggests that its good to hide usability problems with garnish. The latter addresses that this is a problem when measuring success accurately. I believe that color is part of that avoidable garnish.

Full transparency

I’m color deficient. You might have heard of this as color-blindness however, I am not blind to color. I do not see the world in only black & white. I can see colors, just not as well compared to most people. I can appreciate a good synthwave hot pink most of the time. However I also don’t believe that the world should be black & white. Color provides personality and identity. There’s emotion behind each selection and often relates to an opinion of a piece looking attractive or replusive. It is clearly a driver of some decisions but hardly ones that direct a critical path of usability.

Art is not design

Art is a freedom of an artist’s expression; an attempt to convey a feeling through their medium. It is commonly an egocentric activity to achieve a desired appearance. This is in contrast to design which is striving for altruism and inclusivity. This is supported through pattern recognition and reusing familiar experiences to achieve a goal. Design systems are the ultimate solution for achieving this cohesive experience; establishing trust between the user and the product. One deviation from past experience could be enough for the user to hesitate on the next step or stop the progress indefinitely.

In design, form follows function. It means that something should be usable before it is beautiful. In order to do this, we must identify the problem we need to solve. In a qualified user experience practice, this will not begin with designing an interface but with research. Interviews, competitive analysis, user personas, and all the truth finding techniques to paint the best picture of the problem so that you can begin to hypothesize a solution.

Wirecutting

After completing a phase of user research, the next task is not jumping into high-fidelity, pixel-perfect mockups. I’ll coin the term “wirecutting” for when a designer cuts out this wireframing step to work on prettier things. Wireframing helps visualize the flow and features expected to support the user’s goals. In this process, it is easy to see when cluttered interfaces appear and the priority of elements reevalutated. These are commonly without color and for good reason. If it doesn’t work in black & white, color isn’t going to help. Putting gold leaf on a turd, is a really shiny turd.

I believe in a world where wireframes are piped into a tool which creates high-fidelity mockups using the rules and guidance of a design system. Amazingly, this world is here in the form of Uizard. Using this tool, designers can avoid the nuiances of following the system guidelines and focus on the experience by wireframing. The tool should handle the high-fidelity part of the handoff process. For some folks, this may take some of the fun out of the job. On the other hand, maybe the job was misunderstood in the first place.

Of course this assumes a design system is well established. So let’s now focus specifically in this area.

Budget crayon box

There’s dozens of posts online about how color palettes were created for a design system (Lyft, Github, Adobe). A great deal of talk about color theory and creating tools to help visualize curves of color for the perfect balance. I cannot deny that resulting palettes are often very beautiful and I often need to use the work of others in order to choose color due to my deficiency. However, how much of that palette do you really expect to use? This is the palette created by Ferdy Christant based on Open Color.

That’s a lot of color.

Let’s first just talk about contrast which is a requirement to make something accessible. If you have several steps of color, I’d guess that many of the colors found within the middle of those steps have trouble being accessible with most colors in your palette. This is something that the Stripe team found while revisiting color for accessibility. It’s very possible you could omit much from the middle of the palette to support accessible color choice.

And in Ferdy’s post about working with the palette, there is mention about the lack of accessibility in the palette.

Open Color does not rank well when it comes to contrast. The root cause here is that we’re paying the price of beauty.

— Ferdy Christant

You’ll be paying for more than beauty if hit with an accessibility lawsuit. But Ferdy’s answer is to add more color; 3 more dark tones to each hue. I don’t agree with this suggestion because trying to choose the right color becomes a challenge when there are so many to choose from (ie., Hick’s Law). Limiting the selection drives consistency. I’ll even go so far to say that it enhances creativity because you’ll need to design within constraints which requires out-of-the-(crayon)-box thinking.

Coloring outside the lines

Past contrast, let’s now talk about the application of color within an interface. If you look at many modern interface designs today, they tend to follow a 60/30/10 rule. Some sites like Twitter even let you choose a few colors. This comes from interior design where you choose 3 colors and use them in percentages in your space. This is a loose rule, and opponents of the rule will call out several factors against it.

First, restricting a color palette to only three colors inhibits creative designs. While it prevents overstimulation, exploring more “rebellious” designs make brands stand out from their competitors.

— Catherine Rasgaitis

For the purpose of functional product design, I don’t believe we should be striving for creativity in the application of color. Users are expecting familiar and accessible experiences. Painting with all of the colors of the wind will feel like navigating a rainbow hurricane. The limiting of this color helps set expectations as users achieve their goals.

Even in interior design, the original birth of the rule, it is near impossible to strictly use only three colors. It isn’t realistic. There will be additional hints of other colors outside the chosen selection for elements that make up a room. This is a photo of an actual room in the design systems house.

White is a majority, blue is next most prominent, accents are orange-yellow. Importantly there are other colors too! The green plant, the teal footstools, even a rainbow legoset. Admittedly, the rule should probably be something like 55/25/15, which leaves an additional 5% of various colors not covered by the rule where applicable. For user interface design the majority of color will cover the background, the next most important color covers content, and the final most important covers accents that draw the user toward interactivity.

So for most cases I believe you could probably design the large majority of an interface by having a palette of roughly 10 colors or less.

Cases for more crayons

An area where more colors are typically introduced are parts of an experience that are meant to indicate status. An error state is frequently shown in red. However, if the text describing the error is too small or thin to distinguish color, it could be missed as an error. Furthermore, the color red is prosperous in China. These are all reasons why we should not rely on color alone to indicate status. I recommend having two forms of status indication; one can be color where cultural sensitivity is considered and then some other pattern to support the status.

Another area where color is used is to indicate deviations between near identical entities. This can commonly be found in elements like data visualizations (ie., charts) but can also be found when segregating users in a list of contacts. Changes of color here are meant to separate like items making the collection easier to scan.

I can tell you from experience that I often have difficulty identifying the parts of a data visualization that relies on color to show data but don’t take my word for it. You can imagine how much harder it would be for a blind user to experience. This is again why more emphasis should be given toward presenting the data inclusively, perhaps using a table, and also include a progressive enhancement through a visualization. Putting the color before the data is only helpful for some; let’s consider being help for all. The Carbon folks at IBM have more tips to support data visualization for accessibility and mention more work still needs to be done.

Finish with color

There is a reason why, when you apply stain to a table, the solution you apply is called the “finish”. It happens at the end of the building process. After all the plans are made, the legs cut and fastened, and the top made smooth do you finally apply the coloring. Color can bring the personality to an experience and to call something done. There can be an appropriate time to focus on this work but for the start, keep it simple and use design tokens to support changes for the future. Make color the finish to a usable product.

Complementary Space

Sun, 16 Nov 2025 00:00:00 GMT

Before Mise en Mode, I went on a journey to try to truly understand what it meant to have a design token be “semantic”. The community had a fairly good understanding about what this meant as color, and the benefits that comes from thinking in this way. Text has been perhaps more elusive. Though in recent years we are seeing more and more teams separating the meaning of an “h2” from its visual presentation. Separating the reason why something exists from its style is what semantics is all about.

What was first a blog post here turned into six months of research now titled Complementary Space which aimed to rethink space in the same way. What does it mean to apply space somewhere, how would we name those tokens, and most importantly how to convey the concepts of being comfortable or cozy through these tokens.

This post is meant to revisit the article that I wrote those years ago, share some insights I’ve landed on, and finally to be a memorial as I expect to eventually take the original web page down to reduce cost for all of these domains I have. 😅

Gestalt proximity

The first concept to grasp is the purpose of space which is covered by the Gestalt principle of proximity

The principle of proximity states that items close together are likely to be perceived as part of the same group — sharing similar functionality or traits.

In short, when we apply space somewhere, what we’re doing is conveying a relationship between objects. When there’s more space between items, they are less related than items that are more closely related.

This means that the value that we assign to spacing properties is describing a relationship. There’s two kinds of relationships that we see, parent-child and sibling relations. Parent-child relationships tend to have a larger amount of space, or in terms of relationships, are slightly more distant than siblings. This is a common visual paradigm, where the padding around the card holding the children inside is larger than the gaps between those children (ie., siblings).

Periscope

Historically, we’d use something like a T-shirt scale to say how much space are between the objects. However, as I’ve said before, scales aren’t semantic. It isn’t clear where any of these tokens are meant to go in the experience. It’s subjective.

What I landed on after much development is to have the scope describe the density of a region, not the tokens. To get a better understanding of the idea, let’s watch a moment from the TV show MacGyver. Specifically this clip from episode called “Hell Week”.

In the clip, the male student is competing in a contest which is meant to keep other students from entering their dorm. Each student devises a way to keep the door from opening but all have some solution that allows entry. This student’s idea was to make a miniture version of the room. Everything is copied in detail so that when you look through the door’s eyehole, you see the miniture but it looks like a normal size room.

The point of this example is that trying to determine the space between objects without knowing the frame of reference makes it so those distances are visually equal. Certainly, if we are inside of the room we can see, and more importantly measure, the distance between the bed and desk. When we do this, we can immediately tell that the distance between these items in the life-sized room is much larger than the model. But through the eye-hole you can’t because the frame or reference is gone. Everything is proportional. This is how scale models work. You measure the life-size objects, and then apply some ratio to scale them up or down. Through different lenses these can appear the same but in the larger environment actually be different sizes.

Another way of thinking about this is the distance between you and your front door in comparison to the distance between you and the nearest ocean. The nearest ocean is probably very “far” for most people in comparison to their front door. Now, think about the distance between you and the nearest ocean, and the distance between you and the moon. Suddenly the distance between you and the ocean isn’t far at all. Changing the frame of reference is changing what it means to be far.

The point here is that we can change what it means to be “far” by changing the scope. And because our goal is to semantically define what it means to be far, all we need to do is have different “scopes” that express different kinds of far. More importantly, when I say “far”, I really mean space.

In the following image, I’ve made a component that could either represent the entire page or a card within the page.

I use the same base composition for both of these things. On the right, the smaller components found within the larger one are really just scaled down versions of the larger one. Certainly, we see things like typography scaled down, but we also see the space scaled down too.

In this way, we don’t see the page as a whole. Instead we zoom into individual scopes of the composition and then decide how dense that region should be. Generally the deeper we go, the more dense the composition is expected to be.

What are the tokens?

In all of this research, it was important to me that I could land at a similar outcome to what Nathan Curtis had written about in his work on spacing tokens back many years prior but to have this new way of understanding space. Here’s his approach from the article and the complementary approach side-by-side.

In Nathan’s approach, you’ll see that each space token describes composition of the space and its amount. Inset means it goes around content, stack means it goes between elements on adjacent sides, and gap means it goes between on all sides. In this way, there’s lots of decisions that must happen at each location where space is going to exist that also depend on the composition of the elements.

In Complementary Space you’ll see that there is a single token placed for every location we expect to represent some amount of space. This immediately reduces decision making because there is only one token to choose. This means that the only decision that a person needs to make is the “scope” of the content. In other words, am I expecting to reduce the context down to a lower level of hierarchy than the parent above. Where these scopes occur are represented by the dotted borders surrounding regions of the card in the example.

What else do I need?

Below is a interactive demo of the approach, showing how we can make a region more dense by adding the data-density-shift attribute. See how there are several different amounts of space being applied while using very few differently named tokens, in this case --space-near and --space-away from the original implementation.

See the Pen complementary.space by Donnie D’Amato (@fauxserious) on CodePen.

Again, this isn’t entirely needed as demostrated from the image just before but representing padding and gap as describing relationships seems to describe the purpose more than a single space token.

Either with one token or two, this works by compounding identical selectors. Assuming that the way something becomes more dense is by being identified with data-density-shift, this is how you’d create the levels:

[data-density-shift] {...}
[data-density-shift] [data-density-shift] {...}
[data-density-shift] [data-density-shift] [data-density-shift] {...}

As you can see, we duplicate the data-density-shift attribute selector which shows how deep the region is related to other density shifts. While you could have more control by explicitly giving each shift a number related to depth, this brings a subjective decision in an otherwise binary decision of “should this be more dense that the region above?” This also brings more care to the hierarchy of the page. Things that are less dense are more spread out and unrelated sections of content are clearer than if they were composed without these considerations.

Within each level, we expect the spacing values to decrease, making compositions appear more dense. In the CodePen, I create a few Sass functions to help generate the scale based on the number of levels. In the code below I’ve updated to use padding and gap instead of the earlier near and away.


$attr-sel: "[data-density-shift]";
$levels: 4; /* including body */

/* Fibonacci Sequence */
@function fib($n) {
  @return if($n <= 1, 1, fib($n - 1) + fib($n - 2));
}

@mixin vars($n) {
  --padding: calc(
    #{fib($n + 1)} * var(--density, 8px)
  );
  
  --gap: calc(
    #{fib($n)} * var(--density, 8px)
  );
}


@for $i from 1 through $levels {
  $nest-sel: if($i == 1, "body", selector-nest($nest-sel, $attr-sel));

  #{$nest-sel} {
    @include vars($levels - $i);
  }
}

You might also notice that I’ve replaced the usage of rem with px in the code above. This is a separate topic but in short, if the user increases the font size, this is meant to help with readability and the user isn’t meaning to “read” space. Therefore, using units unrelated to typography are preferred.

Speaking of values, this is an area where you might want to explore even further. For example, on touch devices, you might consider having more space than on devices where a pointer is used. This is to increase the target area of interactive elements and make them slightly easier to interact with than using a finer pointing device. Importantly, this is not the difference between “mobile” and “desktop” as some might have you believe. The reason why we should be making space larger is for interactive targetting, not because something is considered mobile. Since this something that should affect the experience globally, this is a matter of updating the density under a media query.

@media (any-pointer: coarse) {
    :root {
        --density: /* something a bit larger */
    }
}

I recommend reading this post at CSS-Tricks about interaction media queries for further considerations.

Avoiding size variants

A large benefit of the scope-based approach is that size variants for your system are no longer meticiously defined. The size of an element is determined by the context it is placed within. In other words, if the button is meant to be smaller, place the button in a region meant to convey a higher density.

This is assuming that other cosmetic properties of the button are also determined by the density, such as font-size.

An example at my design system illustrates this in code in the following way where denser causes the scope to increase in density (ie., space becomes smaller) and can be added to any element:

<box.div denser gap>
  <Button priority="primary"/>
  <box.div denser gap>
    <Button priority="primary"/>
  </box.div>
</box.div>

Because the size of the gap is wholly determined by the surrounding scope, gap becomes a flag that merely indicates if space should exist between the children at all.

While this does create the ability to have more levels of space than you should ever use, I recommend having 3 to start. The highest level designed to support marketing pages, the next level designed to support general productivity dashboards, and the last level to help with the composition of cards and other focused regions. This assumes that you are representing padding and gap as tokens. If not, you might require more levels to accurately describe different kinds of space from scope alone.

When will you be ready?

The reality is that we are still teaching teams semantic color, let alone semantic space. People continue to hard code values into places where they just can’t be bothered to do the right thing. Until we change the mindset of the industry, we’ll be stuck doing things the old-fashioned way, wondering why it’s so hard to make new expressions of our experiences.

So, instead of trying to implement in your company’s design system. I recommend trying to implement into your own personal projects. That way, the understanding of how everything works doesn’t need to go beyond you. Give it a shot, and let me know how it goes? Let’s make space complementary. 🤝

CSS Only Contrast

Wed, 04 Jun 2025 00:00:00 GMT

I think many of us who work with CSS and accessibility have been looking for a solution that helps provide the right amount of contrast for a given color. It’s floated around as a function within different CSS color specifications, currently found as contrast-color() in CSS Color Module Level 5 with the following syntax:

background: var(--color);
color: contrast-color(var(--color));

Unfortunately, this isn’t available in any browser and there’s no references found for it in MDN or caniuse. So, do we just keep waiting? Maybe not!

Prior art

Over 5 years ago, there was a post on CSS Tricks that began to poke at this problem. Josh Bader outlined a method that takes the channels of an RGB color and combines the values into a luminance value to be reassigned into a new RGB color.

:root {
  --red: 28;
  --green: 150;
  --blue: 130;

  --accessible-channel: calc(
    (
      (
        (
          (var(--red) * 299) +
          (var(--green) * 587) +
          (var(--blue) * 114)
        ) / 1000
      ) - 128
    ) * -1000
  );
  --accessible-color: rgb(
    var(--accessible-channel)
    var(--accessible-channel)
    var(--accessible-channel)
  );
}

The problem with this approach is that you needed to know the amount of each channel such that it could be combined together. This made it tedious to define a color because it’s uncommon to have to set color channels individually, especially when we begin to use variables and tokens which are curated by folks that aren’t close to the code.

Luckily, we do have some modern CSS that can help with this and get us much closer to a good developer experience with only CSS.

Relative color syntax

The new CSS Relative Color Syntax part of baseline 2024 allows you to get the individual channels of a color function and mutate the output. Here’s a simple example:

background: rgb(from var(--color) r r r);

We can identify relative color with the from keyword in the color function. What this would do is take the red channel of the var(--color) and assign that value to the R, G, and B channels of a new color. In other words, using the red channel of the given color to make a new grayscale color. You should see that this is the missing piece to Josh’s idea, so here’s how we’re going to put it together.

First, we’re going to simplify Josh’s implementation a bit. Here’s the calculation we’re going to use instead:

clamp(0, (((r * .299) + (g * .587) + (b * .114)) - 128) * -1000, 255);

Doing it this way omits the / 1000 by using decimals for the magic luminance numbers. This will return the amount for each RGB channel to be either black or white. This means we’d need to duplicate the same calculation a few times in the relative color function.

rgb(
    from var(--color)
    clamp(0, (((r * .299) + (g * .587) + (b * .114)) - 128) * -1000, 255)
    clamp(0, (((r * .299) + (g * .587) + (b * .114)) - 128) * -1000, 255)
    clamp(0, (((r * .299) + (g * .587) + (b * .114)) - 128) * -1000, 255)
);

We need to duplicate this because the relative color syntax must return a color, not an individual number, so we need to do the same calculation at each channel. It’s sort of like doing the procedure all in a single function but as a requirement due to how relative colors work. This makes the code a little messy, so instead I’ll recommend registering a CSS custom property that can be reused:

@property --channel {
    syntax: "*";
    inherits: false;
    initial-value: clamp(
        0,
        (((r * .299) + (g * .587) + (b * .114)) - 128) * -1000,
        255
    );
}

Now that we have that, we can finally use the --channel variable within the relative color syntax to create the new color:

.color {
    --color: #bada55;
    background: var(--color);
    color: rgb(
        from var(--color)
        var(--channel)
        var(--channel)
        var(--channel)
    );
}

You could also opt to hide the relative syntax in another variable so your peers don’t need to remember the syntax and can use a custom property instead:

/* tokens */
:root {
    --color: #bada55;
    --contrast-color: rgb(
        from var(--color)
        var(--channel)
        var(--channel)
        var(--channel)
    );
}

/* app */
.color {
    background: var(--color);
    color: var(--contrast-color);
}

Check out the codepen below which includes a color picker and notice how the text changes color from black to white depending on your chosen color:

See the Pen CSS only WCAG contrast color by Donnie D’Amato (@fauxserious) on CodePen.

EDIT (2025-06-04): After sharing the approach Matt Ström-Awn made some improvements. Here’s a quote from the thread in the Design System’s Slack:

super cool! you sparked my curiosity; i know that the wcag contrast algorithm uses xyz’s ‘y’ value as its definition of relative luminosity; so if you do the relative color in xyz instead of rgb it simplifies the math a bit.
color: color(from var(--color) xyz
 round(up, min(1, max(0, 0.18 - y)))
 round(up, min(1, max(0, 0.18 - y)))
 round(up, min(1, max(0, 0.18 - y)))
);

Admittedly, I’m not good with color math but I know Matt is so I trust this is a better approach.

Defending Tailwind

Thu, 06 Mar 2025 00:00:00 GMT

If you told me 2 years ago that I was going to write this post, I would have scoffed at the thought. But after a deeper think related to the current state of affairs when it comes to development today, I get it.

The thumbnail used to promote the Code & Pixels podcast says it all.

I’m very confident that there will never be a time where I will consciously choose Tailwind to style my work. I have too much experience working with CSS to need it. But it wasn’t until a few years ago that I had a wake up call about the gap between my skill and the skills of over developers around me.

Hiring greatness

When I worked for Compass, I was a part of practically every frontend engineering hire starting at my 3rd week of employment there. I’ve attributed it to the person asking me the CSS question disclosing that it took him an entire week to do what I did in 20 minutes during the interview. He had nothing left to ask after blowing away any doubt I’d be able to do the job.

In that time, we created what I can only describe as the best frontend engineering team I’ll probably ever see. Every person with the title frontend engineer was solid in CSS. No problems centering elements, boxes aligned nicely, and responsive design was at the top of everyone’s mind. I was still involved to kickstart newer projects with complex layout needs. The use of CSS grid on the listing page is still largely of my doing, now over 6 years old.

I got a rude awakening when leaving Compass, when new my senior director told me that I was an outlier. I didn’t know how true that was until more recently.

More important

What I’m realizing now is there’s more of a focus on just getting it done. An engineer gets a design thrown over the fence and their job is to “just do it”. The organization wants to get it done as quickly as possible. This means there’s a lack of care in things that are deprioritized. When the majority of full stack engineers are trying to wrangle CSS, it isn’t important to them how to organize that CSS. They just want to set this color on that element and move on to more important things.

That’s where Tailwind comes in.

What’s “good”

There’s two “good” things about Tailwind which I’ll address separately in paragraphs below:

You don’t need to think of a name for the thing that needs styles.
There’s no context switching between the file where you write styles to the file where those styles are being applied.

I can definitely agree that naming something .wrapper is awful. It gives no context to where it is or what it is doing. It’s often a challenge to think of a good name to provide a hook for these styles. Especially styles that are being used once and in a project that might have multiple teams trying to name their .card and having things conflict. Going the small step of namespacing the class names manually is too much forethought, so we’d rather complain that CSS is broken.

Should we assume that a good engineer would have good naming skills? We could, but in most facets of programming you don’t need to because of scope. There’s countless main() calls out there. The feature of CSS being global causes headaches for folks looking for scoped styles. Overrides bleed into unintended places and it becomes a big hassle in the way of more important work.

This is a reason why libraries like Styled Components got so popular. The component you created in React was created from declaring styles.

const Title = styled.h1`
  font-size: 1.5em;
  text-align: center;
  color: #BF4F74;
`;

Boom! You’ve created a component and added the styles in one shot. And because of the hashed classes underneath, conflicts are avoided. I actually agree with this approach. This is a component-first way of thinking. The reuse is in the components, not in the styles. It’s a lot of the reason why I adopted Shadow DOM early on. Tailwind does this too, just with more native syntax in HTML.

This makes way into the second point of context switching. Historically, you’d have to create something in your HTML structure for you to then hook into with CSS styles in a separate file. You’d have to remember what that name was in order to style it. On top of this, you’d also have to switch to the rendered result to see what the effect was. There’s a lot of screens to switch in between just to see what’s happening. It makes a lot of sense to reduce that by writing everything in a single file.

I have empathy for this since recently writing Astro components. All the code for an Astro component is in a single .astro file. I’ve noticed that I tend to write a few lines of HTML, maybe even less of JS, but the large majority of the file is CSS. It’s clear to me that much of the time spent coding in frameworks is CSS and engineers are going to want to reduce that time.

With Tailwind, a person can write the HTML and CSS in one shot. Is it a lot of HTML now? Most likely, but we can tuck that away in the code editor. The organization of styles is wired to the organization of the HTML. It’s a two-for-one special and that must be better, right?

What’s bad

Responsibility and scale.

The naming convention that Tailwind uses forces the engineer to be in charge of when a CSS value gets applied. If you want to have a theming system that can change between different values, what color-red-500 means can’t change, it must continue to be a red. It’s entirely possible that the color-red-500 is not appropriate for the new context, and some engineer must go in and add new logic with some new class name.

I don’t know about other folks, but I don’t want my role to be reduced to responding to every call for a new cosmetic change in the interface. Adding new logic to juggle these classes. I want the folks who ask for the change to do it themselves. Tailwind’s naming convention won’t let you do that. Maybe this is job security, but its also looming technical debt.

If you did want to have flexibility with some class naming convention, classes would need to be named semantically. As in, what the purpose of the thing is, not how it is styled since that could change over time. The purpose of the thing doesn’t change. Unfortunately, creating custom names is precisely what Tailwind recommends to avoid.

Need a small utility to nudge something? That’s a deeper problem with either the design or the engineering of the component. That should be addressed with revisiting the composition, not by adding a utility to pummel the style into submission. But we don’t have time to discuss that. Add the utility, it’s what they are there for. We’ll fix it ~~later~~ never.

The fact is folks who use Tailwind aren’t thinking about responsibility and scale in this way. They are thinking how can I push this out as fast as possible. And Tailwind is great for that. Educating on best practices is always hard. In the year 2025, I still see people struggling with responsive design techniques. So setting color-red-500 permanently isn’t going away tomorrow and the marketing of Tailwind is going to make that exceptionally difficult. We can hope that folks realize this sooner rather than later.

But I guess you could just have AI rewrite it now so no problemo?

Design Attractors

Fri, 26 Sep 2025 00:00:00 GMT

This week I tuned into The Question by Ben Callahan, co-hosted by Natalya Shelburne. During the chat I shared one of my patented hot takes: the design system specialist role will eventually disappear. Of course, if that’s true, it doesn’t bode well for me or for the rest of us in the meeting. Design systems are what we do. The rebuttal in the chat was strong: systems are becoming more complex than ever, and organizations need our expertise to make sense of it all.

Our role today

Much of our work today is about agreement in an organization. In fact, when people ask me to define a design system, I often reply with that single word: agreement. The resources we maintain represent those agreements. A design system maintainer doesn’t really care what color a button is. They care about getting the organization to agree on which color it should be.

The complexity of our role lies in managing expectations before these agreements are made: the expectations of users who will one day interact with the products, and the expectations of peers who are building the next version of those products. When marketing says they need a carousel, the challenge isn’t the carousel itself, it’s gathering requirements across humans: our users and our peers. That process produces tokens, components, and guidelines. Abstractly, though, those are just agreements.

Chaos theory

From Wikipedia:

Chaos theory states that within the apparent randomness of chaotic complex systems, there are underlying patterns, interconnection, constant feedback loops, repetition, self-similarity, fractals and self-organization.

I see design systems as subjects of chaos theory. The complexity comes from infinite, undefined human requirements that maintainers must observe and distill into deliverables. But it’s that last word self-organization that feels like the next step.

The knee-jerk reaction is to say a self-organized design system is impossible. Under traditional methods, that’s probably true. After all, this role exists precisely because someone has to deliberately gather requirements and deliver resources. However, I believe we’ve already answered many of these requirements. Much of the knowledge is common and repeatedly applied. We’ve already settled on many truths about building design systems, whether we recognize it or not.

The perfect button

What is wrong with this button?

Most practitioners would agree the background and text colors lack sufficient contrast. According to the WCAG the ratio should be at least 4.5:1. We’ve landed on a stable configuration for the relationship between a button’s background and text. We now expect all buttons to meet this contrast ratio in order to be useful.

This is what I call a design attractor. In chaos theory, an attractor is the stable state toward which a system evolves over time. In design, for a button to be a button, it must also be interactive. This is a design attractor. From there, users expect some visual treatment to distinguish it from non-interactive elements. Exactly what that treatment looks like depends on the local agreements within an organization, but once settled, that’s another design attractor.

This is why I believe in Brad Frost’s Global Design System idea. We know what a button is supposed to be and do. So why are we constantly recreating buttons with that knowledge? Functionally, we’ve already converged toward the answers, toward design attractors. These are the stable solutions that emerge as the natural equilibrium of usability, accessibility, and implementation constraints.

In the world of AI

AI tools today can take a prompt and deliver mediocre user experiences. But how can they even do that? Because they too have developed design attractors, including ones that we haven’t yet defined. They “know” what a button is and can reference those rules to produce another that meets expectations. While they can’t yet replicate the exact button from your specific design system, we’re not far off. We didn’t need to explain the concept of a button to these systems. They figured it out.

If they can do that, why couldn’t they learn more from additional information? And by “information,” I mean requirements. Today, AI gathers requirements for individual tasks. Tomorrow, it could gather requirements for entire organizations and deliver outputs that meet shared human expectations.

The largest argument here is one of expression. This is why the Global Design System idea is hard to grasp. The button at Home Depot isn’t the same as the button at Visa, or so it seems. In reality, they’re functionally the same button. The difference is in local agreements: Home Depot’s cosmetic style versus Visa’s. Even those stylistic choices still follow the same design attractors. Remember the contrast ratio requirement? Both Home Depot and Visa buttons differ in appearance but follow the same underlying rules.

I believe there’s a world where AI synthesizes design attractors at scale, allowing a design system to self-organize within an organization. A designer would contribute simply by designing. That contribution would influence the larger system and shift the design attractor slightly. If someone introduced a low-contrast button, it would have little impact against the weight of prior knowledge of higher-contrast buttons. Bad behavior contributes very little; good behavior contributes naturally toward the attractor.

A person shouldn’t need to look up guidelines, tokens, or components to work. Those resources should be embedded in their context. And even if an experience is claimed to be novel, we’re never truly starting from scratch. Styles themselves would be learned and refined over time, converging toward agreement as the system internalizes how the organization operates.

Where are the people?

What keeps our roles relevant today is AI’s lack of accuracy. We’ve all seen reports of “vibe-coded” work that humans must revisit. And with the complexity of managing expectations across design and development, any inaccuracy erodes trust. Lose trust, and the system collapses. Our roles exist because organizations trust us to deliver accurate agreements, no matter how messy the human dynamics.

But we should be prepared for a future where AI becomes trustworthy enough to take on more of this work. Certainly, there are ethical concerns far beyond design systems. But for now, it’s enough to recognize that design attractors exist and we can either harness them ourselves, or let the machines do it for us.

What will you decide?

Done with components

Wed, 30 Apr 2025 00:00:00 GMT

I’m done building components. 🙅

This feeling was already strong for me. Teams are always in need of their own components for experiences that are unique to the platform. That means they need their own infrastructure for component development. These get built in isolation and don’t have the same level of communication that components in the core design system would have. This is something that a design system can’t stop and really shouldn’t stop.

That’s why I see a future in the “component marketplace”, where all components are meant to be built which gives visibility not only across teams who want to use existing resources other teams have built but for leadership to clearly understand the landscape of their design language. Its consistency or its lack thereof. This would require some sort of desire for teams to start building on the marketplace. Maybe it gives them auto-docs or a testing harness that is easy to use. Maybe it gives them metrics into how people are using their stuff. Maybe there’s some other attraction that I’m overlooking.

I know what you’re thinking, this is how we get a dozen different buttons across the organization because anyone can put them there. And that’s the point. If the organization wants all of those buttons, they can have them. And that’s often how a design system starts. We do the classic “button audit” find that there’s 12 different kinds and the design system team is born. But what if that audit was not a moment in time, but a dashboard? What if your design leadership could open it up at any time and decide if this was acceptable?

I think this visibility and access would clearly describe the behavior of design leadership. Organizations that want consistency would take actionable steps against the resources found in the marketplace, potentially sending out their design systems team to work with those creators for alignment. On the flip side, organizations that don’t care will continue not caring and it’ll show very clearly. Until then, design leadership can blissfully hide behind not having enough resources to do the audit and no one can be sure there are inconsistencies at all. 🫣

The last straw

This past weekend, my disdain for building components was solidified. I realized what a definitive difference is between a design system and a component library was.

I’ve always said that a design system is a matter of agreement. It’s what the organization collectively agrees should be the overall strategy when it comes to design. However, what happens when that agreement is objectively wrong? This can be compounded by larger organizations proudly displaying poor choices. Those choices are replicated and then defended by the bandwagon effect. This results in a component library. They’re just components based on feelings. People want components, so they get components.

Does a design system have a component library? Sure, but the difference is the thoughtfulness of their inclusion. Is it easy to make your own button? Sure, but it probably doesn’t account for the 3-part blog post published by Adobe Spectrum about handling touch devices due to various browser inconsistencies.

But who cares right? The deadline is tomorrow, and you just need a button that LooksGood™. You have no time to understand all that goes into it. You just see that it isn’t exactly the button that you need so you make your own. How hard could it be? It works on my machine and everyone uses a Mac 16” Pro Ultimate HD Max (I have no idea what the names of these things are). Button #13 is born.

That’s why I’m now making a clear distinction between a component library and a design system. The collection of various shiny objects and the thoughtful curation of related usable resources.

Importantly, just because thought was involved doesn’t immediately make it a design system. You could think that a certain use-case is an exception, but oftentimes that’s where the thinking stops. The design system is meant to have the resources to take all of the information and synthesize it down to the perfect component. Realistically, we don’t have resources to do this. Either we don’t get the time, cooperation, or complete requirements. It’s garbage in and garbage out. No wonder people are losing faith in design systems.

But I haven’t. That’s why I’ve dedicated my free time to them because I’m confident there are perfect versions of them. Versions that could work for everyone. And continuing to copy existing systems strapped for resources themselves isn’t where we’ll find improvements. We need to pivot for universal solutions.

This is because I’m a user too. And every time I visit a site with wild inconsistencies and poor usability I know I have the experience to make an impact and you can too. 💪

DS Events, Backstage

Tue, 19 Sep 2023 00:00:00 GMT

Last month I had the pleasure and honor of being invited to speak in a webinar hosted by Knapsack about theming in complex ecosystems. On that day, there were 3 different design system related events happening; two of them scheduled at the same time. It was at this point I thought that it would be helpful to have all the events in our community to be in one place. So I did what any of us do: I bought a domain.

Helping hands

After I announced the idea in a tweet that day, Josh Harwood mentioned he had a similar idea (and also similar domain) so we ended up collaborating on the project. First jamming with ideas on LinkedIn but later using the Design Systems Slack which is much better suited for this kind of work. My wife Jen was also involved in the process, making this a Design Systems House project.

Concept

The idea was simple, we want some feed of events that you can view all events that have design systems content. What the registration link is, if it’s online or in-person (or both) and most importantly when the event will be in relation to other events. Josh gathered a lot of different concepts to compare and identified the treatments that we liked the most. We trimmed down some of the ideas for the sake of an MVP; something that gets the general idea across.

Design

A blank canvas is always a hard place to start. Luckily I had something for a long time ago (my second codepen) which was going to kick this off.

See the Pen Material Design Hover Animated Calendar Icon by Donnie D’Amato (@fauxserious) on CodePen.

I created this pen in 2015 after seeing the design of the Google Calendar icon and gave it some small animation on hover. I was super proud of it back then so I’m glad it finally found a home in a project after all these years. I thought it would be functional by flipping to the date as your scroll.

The event card design was mostly composed of the essential data we wanted to show; the who, what, where, when, and how. I recommended that the location tags were a separate treatment from other qualifiers to make them easier to identify. I felt if we had a collection of tags that were related, scanning them would be more difficult. Granted, we did also add filters so maybe this is less of a concern now.

Development

The important thing to know about me is that I don’t often build applications. I’m commonly petrified of trying to connect to a database so if I was going to pull this off, I knew I needed something simple. I’ve been loving Astro recently for it’s ability to do absolute magic and since what we were making was essentially a blog where each post is an event, it seemed like a good choice. Eventually, we decided that it didn’t make sense for each event to have its own page, since we weren’t showing much more information between the feed and the page. Plus, the purpose for folks visiting isn’t to stay on this site, but to go register at another.

Dates

Inevitably, this kind of a site will require a heavy use of datetime manipulation. Unlike many developers, the Date() object doesn’t scare me; I’ve been working with it for years and understand what it’s doing most often. Here’s some of the finer points of the system in this regard.

Writing a UTC date into the client is trivial when the timezone is included. It’ll be localized when finally rendered as a string.
Speaking of rendering as a localized string, you always want to reach for Intl.DateTimeFormat and its related methods. It even has the ability to give you the parts of a localized date. We use this for the mini calendar pages.
The harder part is having the client enter a datetime and sending it as UTC. The form that creates an event uses a <input type="datetime-local"/> which should give some indication of what it does. However, this was the easiest way to put a datetime input on the page.

Timezones

A helpful fact about working with Josh is that he lives in New Zealand, on the complete opposite side of the world from me in New York. For him, it is all too common for him to need to translate dates and times into his local time just to see if they are remotely available to participate. The process of converting to local time is annoying and we wanted to change that. This is where the global timezone input was born and it was a bit of a challenge.

The list of timezones is very simple, as is getting the user’s current timezone. One line of code each:

const timezones = Intl.supportedValuesOf('timeZone');
const userTZ = Intl.DateTimeFormat().resolvedOptions().timeZone;

The hard part is getting the UTC offset from the timezone name. For that, I had to do some digging but here’s the final result:

function getUtcOffset(timeZone) {
    const timeZoneName = Intl.DateTimeFormat("ia", {
        timeZoneName: "shortOffset",
        timeZone,
    })
        .formatToParts()
        .find((i) => i.type === "timeZoneName").value;
    const matchData = timeZoneName.match(/([+-])(\d+)(?::(\d+))?/);
    if (!matchData) return '';
    const [, sign, hour, minute] = matchData;
    return [sign, (hour || '0').padStart(2, '0'), (minute || '0').padStart(2, '0')].join('');
}

Using the timezone name, format it’s parts using 'ia' (Interlingua) to return the timeZoneName value.
That value should include the UTC offset with some parts that we parse out with a Regular Expression.
We deconstruct the Regular Expression result and reconcatenate with padded digits.

Using that function, with the value from a <input type="datetime-local">, I can create a UTC time in the client with a bit more concatenation.

function onChange({ target }) {
    const isoUtcDate = new Date(`${target.value}:00${getUtcOffset(timeZone)}`).toISOString();
}

There might be a cleaner way to do this if I was to dive into source of date-fns or moment. Something to look into for later.

Now the global timezone input will change all of the dates and times to the user’s selected timezone. This is very helpful when inputting a new event; so you don’t need to lookup what it is for your timezone. You can enter the information in the timezone announced by the event.

One of the fast-follows we’ll need to do is including the timezone for physical events. Since seeing the local datetime when the event is posted in another timezone is confusing. This should be just saving the user’s timezone when the data is input for physical events, assuming they aren’t trying to convert themselves. For the moment, the time at each event links to the global timezone input so a person can update it themselves but it would probably be helpful to display this on the physical events upfront. It’s also not immediately clear which timezone a physical event might be in for all visitors.

Images

What is a post without an image? We knew we wanted to give each event some more personality than just the event details. So including an image was important. My idea was to have a few options; image upload or image “search”. The image upload is easy using <input type="file"/> with a little bit of CSS magic to make it look consistent with other inputs. However, the image search was much more involved.

The idea was for the user to input a URL and we’d intelligently get an image based on the URL. Here’s the steps:

If the URL is an image, use it.
If the URL is an HTML page, check for an Open Graph image and use that.
If the URL is an HTML page and doesn’t have an Open Graph image, take a screenshot.

From my experience, whenever I hear screenshot, I immediately think I need a headless chrome browser to render the HTML. I initially started using Playwright and got everything working in development on my local machine. However, as soon as I uploaded the build to Netlify, it failed. Why? Playwright is too large. I tried looking at tutorials for folks successfully using it or Puppeteer in a Netlify function but nothing I tried worked.

I was pretty defeated after several hours of work trying to figure out how to make this smaller. At the end of it all, I came to my wife with a big hug and all she said was “is there anything else you could do?” That’s when it hit me; maybe I don’t need headless chrome at all?

For two of the 3 options, all I’m really doing is a fetch() request and I don’t need any dependencies for that. That left the last option, the screenshot. I searched for a few hours, trying different packages and looking at their sizes. I finally found one that worked; red-snapper. I don’t know how, but this package is only 160kB (gzip) and makes screenshots pretty easily. The one gotcha is that you’ll want to add the delay option so the page has a chance to load.

One small addition for this was including an AbortController to the fetch as it’s possible a URL might not be valid so instead of the normal timeout, we abort ourselves.

async function fetchWithTimeout(resource, options = {}) {
    const { timeout = 8000 } = options;
    
    const controller = new AbortController();
    const id = setTimeout(() => controller.abort(), timeout);
  
    const response = await fetch(resource, {
      ...options,
      signal: controller.signal  
    });
    clearTimeout(id);
  
    return response;
}

Verifying

So if a person makes a new event, how do we review it? I knew I wanted to avoid creating some RBAC system all for the sake of 3 of us looking at some data once in a while. I had the idea of using Github PRs for reviewing the submissions. However, when I started looking at the official docs, I was immediately overwhelmed. There’s just so much you need to know to get things working. That’s when I caved; I asked ChatGPT to just tell me how to do it.

As much as I believe that technology will eventually help up do things more efficiently, I will rarely use it personally. There’s something about having the ability to do it myself that makes me feel useful. The Github docs on the other hand make me feel completely inadequate. I think the other reason why I think this was appropriate is because this isn’t really my area of expertise. My world is the front of the frontend so that’s where I want to comfortably keep my expertise.

Back on track and a few await calls later, I can create a PR for the repository with a new event submission. Now we can just login using Github, make approvals and merge with an auto-deploy. It even has branch previews courtesy of Netlify!

Eventually, we’ll make the form more intelligent. The error messaging isn’t great and we’d like to have a predetermined list of locations to choose before creating a new one. However, as long as there is a good attempt at completing it, it’ll submit. Plus, someone from the team can always correct an entry before it’s posted.

Reviewing the past

One of the things we discussed about was what happens when events are complete? Do we not show them, or maybe show them differently? Do we have the ability to link to resources produced by the event? I had strong feelings about the last point. It was important to me that we review an event once. Otherwise it would be exhausting trying to collect all the information from past events on a regular basis. Additionally, if we were going to put the responsibility on the person who submitted the event in the first place; I’d need some way of reidentifying who they were to update the post. That returns back to the RBAC problem; now with user creation. I squashed the idea just because of my abilities but I do see the benefit in a more complete system.

As for the other features of past events. We opted to do a pagination approach, where the first event at the top of the feed in the homepage is the next upcoming event and following events go forwards in time. If you go back one page, the first event at the top will be the most recent past event and subsequent events go further back in time. Historical events are stylized in a sepia filter (including the pagination button when you will travel to a historical page) to make them look more old-timey.

Pagination

Speaking of pagination, this was trickier than I expected since we aren’t starting at the first or last event, but something in the middle. When you load the page, we determine what today’s date is and then mark the next event according to that date. Then we separate pages offset by that date. I had a few tries trying to get this to work and had plenty of fumbles. Not because of the date comparisons, since the Date() object value is a number, but juggling what to show on which page.

Eventually, I figured to just segregate the events as if they were paged each time you filter and/or paginate but I wasn’t quite sure what that algorithm looked like. Here’s what my thought process was.

Get today’s date, find the next event in the list and get it’s index.
Chunk the events (into pages) so that the index is the first in its chunk.
Find the chunk that has the index and return that chunk.
If paginating, return the chunk offset by the target chunk and given page.

I was feeling a bit confused here too, so I tried giving some prompts to ChatGPT here too. However, it was not given me the right results and I knew why. It would find the next event and just move it to the first of some chunk. What I wanted was for the the first chunk to be adjusted so that the target event would wind up as the first. After seeing the general approach, I realized I just needed the handy % operator. Here’s the final function:

chunk(arr = [], size, target) {
    const chunks = [];
    let currentChunk = [];
    let chunkSize = arr.indexOf(target) % size || size;

    if (arr.length < chunkSize) {
        return [arr];
    }

    for (const item of arr) {
        currentChunk.push(item);

        if (currentChunk.length === chunkSize) {
            chunks.push(currentChunk);
            currentChunk = [];
            chunkSize = size;
        }
    }

    if (!chunks.includes(currentChunk)) {
        chunks.push(currentChunk);
    }

    return chunks;
}

So if I had an array with the numbers 1 through 15, and wanted the size to be 5 but the target as 8, the resulting array would look like this:

[[1, 2], [3, 4, 5, 6, 7], [8, 9, 10, 11, 12], [13, 14, 15]]

Notice how the 8 is at the first position in its chunk.

Web Components in Astro

I love web components and I’ve been using them for years. Astro supports web components but it’s not well documented. I had a lot of learnings trying to use them in this project and here’s some takeaways that will be helpful.

You don’t need to use the ShadowDOM, Astro will encapsulate styles within the framework.
You can create a one-page .astro component as a web component, and import into other places across the project.
Spread Astro.props on the component and <slot/> is your friend.

<my-component { ...Astro.props }>
    <slot><!-- default content can go here --></slot>
</my-component>

<style>
/* Encapsulated styles are here, no ShadowDOM required */
</style>

<script>
    class MyComponent extends HTMLElement {
        constructor() {
            super();
            /* Do whatever you need here */
        }
    }

    customElements.define('my-component', MyComponent);
</script>

And then in another .astro file (assuming you have a @components alias):

---
import MyComponent from '@components/MyComponent.astro';
---

<MyComponent id="my-component">
    <span>Stuff for the slot</span>
</MyComponent>

I did a mix of this kind of web component and ShadowDOM ones. You can identify the older components from the newer ones because of this.

Global events

I also needed the components to talk to each other. Normally I’d select them from the DOM to begin listening but. I got lazy and just sent most of the events over the document, so many of the components have a customEvent method that sends a detail key in the event with the data it has processed for another component to pick up and use for something. One of the longest chains in the system goes like this:

On timezone change, get the full event list.
On full event list request, filter the events.
On filter complete, paginate the results.
On pagination complete, render the results.

It’s possible that other events will trigger the flow. For example, you can trigger the filters without requiring a timezone request, which also sends a message to reset pagination (since filtering will re-adjust the results on pages).

Filtering

And speaking of filtering, this was a bit tricky as well. The direction I chose was that if a filter was checked, it should be shown. So if nothing is checked, then nothing is shown. Then we check all the filters by default so the visitor sees everything by default and they can remove as needed. The data behind it looks like it might work the same, but it doesn’t. Specifically the “Free and Premium” filter which reads from a single data point free.

If both are checked I need to show both free: true and free: false events.
If one is unchecked, I need to hide what the checkbox represents.
If both are unchecked, I need to hide both.

Meanwhile, the “In-person and Remote” filter works much easier:

If In-person is unchecked, hide in-person events.
If Remote is unchecked, hide online events.

We considered having filters for location but that would require an API key to some geolocation service which would have cost some more money. We hope to collect some locations in the coming months to use for filtering as a next step.

Release ready

A site needs all the finishing touches. Jen made the site’s Open Graph and Twitter images. She also chose the colors for the site since I’m color deficient. Josh recommended an .ics file to be created for subscriptions, so people can just add our calendar to see the events as they are added. Josh also put together the list of events that were upcoming as they were announced so we could add to the site when we were ready. There’s a lot more ideas that were at play but not enough time to implement. We’ll collect more feedback and have time to revisit later this year.

We’re excited to finally show off this past month’s worth of afterhours work to bring our community closer together. Visit the site and subscribe to a feed. If you know of a design systems event coming, help our community by adding it.

Dynamic Astro Collections

Mon, 10 Apr 2023 00:00:00 GMT

When I first heard of Astro it sounded incredible. I thought of it as the next step after working with 11ty. That step is requiring framework support such as React, Vue, or others. While I often avoid frameworks, a framework allows for a shared understanding with a team to achieve a result within the guardrails, even if convoluted.

So for documentation sites that expect to host components written in a framework, Astro seems like a solid choice. However, my initial review of the project had some serious critism when finally attempting to build a site.

Low maintenance

One of the most important qualities of a documentation site is for it to be low maintenance. This can result in lots of different kinds of optimizations but one of the first I think about is how easy it is to create a new page and have it immediately appear in a navigational interface. It’s a non-starter if I need to configure simple navigation by letting the project know that I made a new page and where that new page is in the project. We can do better, but at the time Astro just couldn’t do this without accessing some internal methods and even then it didn’t seem possible without rebuilding the entire site. The ergonomics weren’t great and I decided to pause on the project.

Content collections

Astro has come a long way since my complaints. Earlier this year with the release of their v2.0, they have introduced Content Collections. Much of their post is talking about it being typesafe which is good but what I was more excited about was the ability to fetch content and manipulate it to render navigation.

The documentation suggests a few ways to configure a collection but all of them assume you are manually curating the collection. I’d like to avoid this so you don’t need to provide much instruction past “put files here”.

Assume the following project /src file structure, reduced for brevity. We’ll be discussing each top-level directory and its setup to get this to work.

├── components
│   └── MainNavigation
│       └── index.jsx
├── content
│   ├── components
│   │   ├── button.mdx
│   │   └── ...
│   ├── foundations
│   │   ├── color.mdx
│   │   └── ...
│   ├── ...
│   └── config.js
├── layouts
│   └── Page.astro
├── pages
│   ├── [collection]
│   │   └── [...slug].astro
│   └── index.astro
├── utils
│   └── getAllCollections.js
└── ...

Content

The following is an example of how to define a collection from the Astro docs. The most important part here is the config.js file shown below.

// 1. Import utilities from `astro:content`
import { z, defineCollection } from 'astro:content';
// 2. Define your collection(s)
const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
  }),
});
// 3. Export a single `collections` object to register your collection(s)
//    This key should match your collection directory name in "src/content"
export const collections = {
  'blog': blogCollection,
};

Note the last comment. The key needs to match your collection directory name. This means that when you add a new directory, this file needs to know and have definitions added. I want to avoid that, so here’s my version:

import path from 'path';
import { z, defineCollection } from 'astro:content';
const glob = import.meta.glob('./**'); /* vite */

export const collectionNames = Object.keys(glob).map((filepath) => path.basename(path.dirname(filepath)));

const schema = {
  schema: z.object({
    title: z.string()
  })
};

function assignCollection(acc, name) {
  return Object.assign(acc, { [name]: defineCollection({ ...schema }) });
} 

export const collections = collectionNames.reduce(assignCollection, {});

The first new part is using the glob function from Vite to get all files relative to this config file. We could be more specific here to look only for .md{x,} but this works fine as-is.

After using the glob function to get the files, we parse the filepaths to get the directory that each one is in. This assumes that each section (eg., /blog) is only one level deep. This will return an array of directory names that we’ll use later. For us, this return ['components', 'foundations'].

Finally, the collectionNames array is reduced using the assignCollection function. This creates a new collection definition with each section in the same way we would have done it manually in the original example. During the build step, Astro will create types based on the schema.

Before moving on, make sure you have some content in the markdown files (including the title frontmatter) to test out.

Pages

Next we’ll dynamically render our pages. We’ve set up a dynamic route at [collection][...slug].astro. As you might have guessed, the collection part is the directory name found within /content from earlier. For our file structure, this’ll eventually write components and foundations into the url. The slug is created from the file names in each of these directories (button and color). Here’s how we get that to work using frontmatter in the [...slug].astro file which is mostly copied from the official documentation.

import Page from '@layouts/Page.astro';
import getAllCollections from '@utils/getAllCollections.js';

export async function getStaticPaths() {
  const content = await getAllCollections();
  return content.map((entry) => {
    params: { slug: entry.slug, collection: entry.collection }
    props: { entry }
  });
}

const { entry } = Astro.props;
const { Content } = await entry.render();

A few things to note. The @layouts alias points to the /layouts directory where I have a single Page.astro as the base layout. The @utils alias points to reusable functions. These aliases can be setup in the tsconfig.json file at the root of the project. The getAllCollections function we will need to use twice. Once here to make the paths to content, and a second time to build navigation. I imagine there’s a way for this to run once, but this was easiest for me while I explored this solution.

This is what the getAllCollections function looks like:

import { getCollection } from 'astro:content';
import { collectionNames } from '@content/config';

export default async function getAllCollections() {
  const collections = await Promise.all(
    collectionNames.map((name) => getCollection(name));
  );
  return collections.flat();
}

The getCollection function from Astro will get the data for a single given collection. We have created a list of collections back at the content/config.js file as an export called collectionNames. So we loop over that to get all of the content and write the section it came from within the metadata. After resolving all the promises, we flatten the result because this is a single-level navigational structure. If you need nesting, you might not want to flatten the results here and have your own tree returned.

At this point we should be rendering pages dynamically. However, we’d also like to automatically generate a navigational interface from this too.

Layouts

In the Page.astro file, we’ll need to manipulate the result of the getAllCollections function to create a tree for navigation.

import path from 'path';
import getAllCollections from '@utils/getAllCollections.js';

function buildNavigation(collections) {
  return collections.reduce((acc, entry) => {
    // collection is the collectionName string
    const { collection } = entry;
    if (!acc[collection]) acc[collection] = {};
    const { slug, data } = collection;
    acc[collection][data.title] = path.join(import.meta.env.BASE_URL, collection, slug);
  }, {})
}

const collections = await getAllCollections();
const tree = buildNavigation(collections);

As we loop over the items in the collection, we get the title and build the url.

Components

Finally we create a navigation component to consume the tree. This could be done in any framework, even as an Astro component since it can be a list of links. I’ve chosen to use React to have several subcomponents in the same file.

import React from 'react';

function Section({ section, entries }) {
  const navigation = Object.entries(entries);
  if (!navigation.length) return null;

  return (
    <li>
      <span>{section}</span>
      <ul>
        { navigation.map(([title, url]) => 
          <Item name={ title } url={ url } key={ name }/>
        )}
      </ul>
    </li>
  );
}

function Item({ title, url }) {
  return (
    <li>
      <a href={ url }>{ title }</a>
    </li>
  );
}

export default function MainNavigation({ tree }) {
  const navigation = Object.entries(tree);
  if (!navigation.length) return null;

  return (
    <nav>
      <ul>
        { navigation.map(([section, entries]) => 
          <Section section={ section } entries={ entries } key={ section }/>
        )}
      </ul>
    </nav>
  )
}

There’s nothing special to see here. The incoming tree prop is the object that represents the navigation for the content made in the buildNavigation function from earlier. The component will traverse the tree and render out the links.

Finally, back in the Page.astro file, import the <MainNavigation/> and render it in the body passing in the tree.

<MainNavigation tree={ tree }>

And that’s it! Now as markdown pages are created in the /content directory, they are automatically added to the navigation.

Dynamic Storybook

Tue, 14 Jun 2022 00:00:00 GMT

When I was exploring the next version of the design system for Compass, I was really interested in how I could keep designers from recreating symbols that we already have represented in code. They’d have to painstakingly make all of the possible states and interactions for every component for the design library. I knew there was a better way so I cobbled a few systems together in order to do it.

Legacy system

I was an early adopter of Storybook and leveraged it to visualize the components I was building for the new design system. Writing a story was helpful to create one ideal state, or perhaps wiring it into the knobs addon allows for different configurations to happen with a few button clicks. However, what I really wanted was to generate stories based on the configuration options for each component. I was working on a very early prototype with web components so I didn’t have proptypes to hook into. I opted to create an component.props.js file for each component to help generate configurations.

From here, I used a package called combos to create all the possible permutations of options and then create a new Storybook file to read with those new generated components. This was also used to create the files required for html-sketchapp, which could render the HTML into Sketch symbols.

Component Story Format

Storybook is no longer focusing on their initial implementation of writing stories, the storiesOf() function, in favor of the Component Story Format (CSF). The CSF is described as an open standard for UI component examples based on JavaScript ES6 modules. And the way to write a story seems fairly simple:

export default { title: 'atoms/Button' };
export const text = () => <Button>Hello</Button>;
export const emoji = () => <Button>😀😎👍💯</Button>;

The default export is the metadata about your story; the title, the component, and maybe some additional configuration options. Each named export is a story. So in the above example, you’d have two stories. One named “Text” and one named “Emoji”. And coming soon, CSF v3 will introduce an even smaller amount of code to create a story:

export default { component: Button };
export const text = { args: { children: 'Hello' } };
export const emoji = { args: { children: '😀😎👍💯' } };

However, if you know anything about the JavaScript module ecosystem you’ll see the problem with my goal. There’s no way to generate stories using CSF. In fact, Storybook doesn’t even treat this file as a real module at first. Storybook will actually read this file, create an abstract syntax tree (AST) and then begin parsing the file for information [source].

Let’s compare this to the original storiesOf() method of writing stories.

storiesOf('atoms/Button', module)
  .add('text', () => <Button>Hello</Button>)
  .add('emoji', () => <Button>😀😎👍💯</Button>)

You can see that the original method of writing stories is more flexible and allows for someone to create a collection of stories and begin iterating to add to Storybook. Here’s a cute one-liner to define a collection of stories.

const stories = {
  text: () => <Button>Hello</Button>,
  emoji: () => <Button>😀😎👍💯</Button>,
};
Object.entries(stories).reduce((acc, ([name, fn])) => acc.add(name, fn), storiesOf('Button', module));

Interestingly, it seems that CSF compiled to storiesOf() for Storybook but I’m not sure if that’s still the case.

If it ain’t broke

While Storybook no longer recommends the storiesOf() approach because it conflicts with improvement plans; we can still use it today. Here’s how I’d begin to integrate with a React ecosystem; reading PropTypes to generate stories.

First, we need a way to read proptypes from a component. Luckily, there’s a package for that: parse-prop-types. Here’s how we might begin to use this:

import parsePropTypes from 'parse-prop-types';

export default function (component) {
  const proptypes = parsePropTypes(component);
}

If you get a collection of types that all return as 'custom', you’ll need to include the following before defining proptypes for each component.

import 'parse-prop-types';

For more information, like the return object structure, I recommend reading the project’s README.md.

Next, we’ll need to prepare a collection of properties and possible values. For type: 'bool' and type: 'oneOf', the values are fairly straight forward. We’ll put these in a lookup object for easy access.

const DEFAULT_TYPE_ASSIGN = {
  'bool': () => [false, true],
  'oneOf': ({ meta }) => meta.type.value,
}

For the inputs like number or string, we’ll need to allow custom fixtures to be included. We’ll prepare an options argument for our function to supply this.

export default function (component, options) {
  const { fixtures } = options;
  const proptypes = parsePropTypes(component);
}

The fixtures option will be an object that has each prop as a key and an array of possible values. Now we can send that into our assignments; choosing the correct fixture prior to running the function. We’ll see how this works later.

const DEFAULT_TYPE_ASSIGN = {
  'bool': () => [false, true],
  'oneOf': ({ meta }) => meta.type.value,
  'string': ({ fixture }) => fixture,
  'number': ({ fixture }) => fixture,
}

You can continue to add more as needed. I specifically omit the func type since it’s not a visual change but you can include it if it’ll help your project.

Ok, we’re ready to loop through all of the proptypes.


const DEFAULT_TYPE_ASSIGN = {
  'bool': (acc, { property } ) => Object.assign(acc, { [property]: [false, true] }),
  'string': (acc, { property, fixture }) => Object.assign(acc, { [property]: fixture }),
  'number': (acc, { property, fixture }) => Object.assign(acc, { [property]: fixture }),
  'oneOf': (acc, { property, meta } ) => Object.assign(acc, { [property]: meta.type.value }),
}

const isFn = (fn) => typeof fn === 'function';

const values = Object.entries(propTypes).reduce((acc, [property, meta]) => {
  const fn = DEFAULT_TYPE_ASSIGN[meta.type.name];
  return isFn(fn) ? fn(acc, { meta, property, fixture: fixtures[property] }) : acc;
}, {});

Notice, I’ve updated the functions in the lookup to have an accumulator as the first parameter; each will return the accumulator with the values for each property if it exists. Otherwise, it will return the unaltered accumulator.

Ok, now we’re ready to create permutations. I’m using a more recent package for this: combinate. Let’s start putting everything together.

import parsePropTypes from 'parse-prop-types';
import combinate from 'combinate';

const DEFAULT_TYPE_ASSIGN = {
  'bool': (acc, { property } ) => Object.assign(acc, { [property]: [false, true] }),
  'string': (acc, { property, fixture }) => Object.assign(acc, { [property]: fixture }),
  'number': (acc, { property, fixture }) => Object.assign(acc, { [property]: fixture }),
  'oneOf': (acc, { property, meta } ) => Object.assign(acc, { [property]: meta.type.value }),
}

const isFn = (fn) => typeof fn === 'function';

export default function (component, options) {
  const { fixtures } = options || {};
  const propTypes = parsePropTypes(component);
  const values = Object.entries(propTypes).reduce((acc, [property, meta]) => {
    const fn = DEFAULT_TYPE_ASSIGN[meta.type.name];
    return isFn(fn) ? fn(acc, { meta, property, fixture: fixtures[property] }) : acc;
  }, {});

  const storyArgs = combinate(values);
}

The new storyArgs variable holds an array of objects, but we’re not quite done yet. We need to have one large collection with the structure of { name: { ...args } }, where the name is a unique identifier for each story. I opted for a simple slugify of the JSON to create the identifier.

import slugify from '@sindresorhus/slugify';

const storyArgs = combinate(values).reduce((acc, combo) => {
  const str = JSON.stringify(combo);
  return Object.assign(acc, { [slugify(str)]: combo });
}, {});

At this point you can just return the resulting storyArgs and pipe them into the storiesOf() method approach that I suggested above:

import React from 'react';
import { default as Button } from './Button';
import { storiesOf } from '@storybook/react';
import everythingAllAtOnce from '../src'; // Your custom generator function

const fixtures = { text: ['hello', '😀😎👍💯'] };
const stories = everythingAllAtOnce(Button, { fixtures })
Object.entries(stories).reduce((acc, ([name, args])) => acc.add(name, () => <Button { ...args }/>), storiesOf('Button', module));

Or, if you’re really fancy, you could provide more options to just have the function run the storiesOf() method internally.

everythingAllAtOnce(Button, {
  fixtures,
  storiesOf, // Used internally to begin defining the stories produced
  callback: (args) => <Button { ...args }/>, // How each story should render with the given args
});

Not showing the code to implement here, you can use your imagination.

Cool, what should we do with this?

For starters, this would a good way to begin generating assets for your component library. The story.to.design tool by ‹div›RIOTS can transform stories into Figma components. This’ll help keep the Figma library up to date with the code because it’s pulling from the code. Imagine, writing minimal code to generate all of these assets!

It’s also a good way to determine configurations that you may not have expected. Perhaps you notice with review of the permutations, icons in inline buttons don’t work well, so you might want to set a conditional in the component to either warn or omit the icons.

Speaking of checking configurations, this would be great for testing. You could ensure a check in every configuration for some baseline metrics and even assert that all configurations that use the same props will render in the same expected way. This is truly a full coverage scenario without writing much code.

Full circle

This brings me back to the introduction of the CSF format; which doesn’t support this type of behavior at all. There’s a document outlining the possibility of “Storybook Combos”, which is only a proposal with no affirmitive direction yet.

I hope that whatever the future holds for Storybook that the team sees the benefits of storiesOf() and attempts to support the ability for dynamic stories in the future. I’m sure the design system community has more use-cases for dynamic stories that are past just the needs outlined above.

Feeding trolls

Tue, 28 Jun 2022 00:00:00 GMT

I published gridless.design a year ago this month and the initial response was overwhelming. Many people across the design industry shared and discussed these ideas for the coming weeks and I really enjoyed seeing all of the positive affirmations and interest in how we might avoid grids in artboards to hand off responsive web designs.

However, there were others that didn’t understand the point I was trying to make. This is my opportunity to address these comments and help clarify where the mark was missed.

It reads like a long-form rant complete with broken grammar.

— del_rio

Rant is probably true. The fact that we’ve been attempting to design the web like a canvas instead of a document is a complaint about the norms that we’ve accepted. It’s important to state the problem before providing a solution.

As for the broken grammar, I think that’s a bit unfair. I’m a native English speaker but my grammar shouldn’t be criticized for the idea I’m trying to convey.

Not a single argument was supported with a citation even though they’re presented as “it is recommended”

— del_rio

While must of the historical part of the thesis goes uncited and could be improved, it’s not as important as the gridless approach which is net-new. How do you cite new ideas? The gridless approach is novel and never before documented. The closest concept is responsive design but it is not the same since the target for the change is artboard exploration specifically; not the web. The recommendations are based on the observations which are documented here in this thesis.

It also has a ridiculously long introduction that explains the basics and superficial history of web design/development which seems utterly pointless considering the target audience.

— teokk

The point of the history is to provide a primer to all the concepts that caused the grid to be included in the web design process and what the web aimed to support.

Hacker News

These were responses to a blog post by Michelle Barker about my writing entitled “Is it time to ditch the design grid?“.

No, of course, not, grid is a fundamental structure in graphic design.

— qkqk

That’s the thing, we aren’t talking about “graphic” design, we’re talking about “web” design. Graphic design principles can translate to the web but sometimes not directly. This is one of those cases. The traditional artboard is not an accurate representation of the web. Identifying this is the first step to considering new approaches to support what the web expects.

no, no, no. Remember “top: 50%; transform: translateY(-50%);” to vertically center things before Flexbox and Grid? We’re not going back to those days!

— qkqk

The commenter is reacting to the Fab Four approach. The negative dimension that I am quoted on writing is the foundational part of the calculation that allows for a container-query-like layout conditional in that approach. The approach is very complicated looking at first glance and admittedly it isn’t helpful with all the additional variables that I included in order for the gap property to be supported but the end result of allowing the contents to determine when they should change the layout instead of the page is clearly helpful as precedented by native container queries coming to browsers very soon.

Renaming the column-gap property to —gap-spacing doesn’t mean you’re “not using a grid.”

— qkqk

This person might have missed the intro of gridless.design but I call out that I am not talking about display: grid; as an tool to avoid. You can use things that are named “grid” in the process but I’m specifically interested in how we can avoid including the design grid in the hand off process to engineers and even further not using it at all when designing for the web. It has very little to do with the CSS property of the same name.

As somebody who just began using grids in their designs, I can say that grids can have a really nice effect on a lot of layouts.

— Rd6n6

It’s true! Grids make layouts easy and its very much the reason why they work so well for graphic design. However, the final publishing of a graphic design will always have the same layout of elements, the same copy, the same orientation, etc.. On the web, this simply is not the case. What your originally provided in your design will very often not be the same as what your end-user sees. I call out the affects of translation alone and how words will often break out of neatly designed containers. Forcing your content into pink cages will ultimately break usability in designs in the most extreme cases.

I think learning about the design grid for people introduced to design is helpful as a elementary concept but for more scalable experiences, the grid will do more harm than good.

Visually, the “no” grid website just looked like a website created with CSS Grid. I was expecting some sort of design that would be different. Are we missing something?

— djstein

Yes, you’re missing the content of the site! The site itself was not designed using a design grid but instead designed within the rules of the web. You might be able to provide some 12 column overlay that could roughly should some alignment on the web pages but it would be a coincidence.

I think the idea is not that the design is without a grid, but more on how it handles being resized

— oo0shiny

No, the design of the site is truly completed without a design grid. However, while the design of the site was done without a design grid, the content is more important here.

The principles of a grid-based design are still adhered to though. This isn’t “gridless” in any real sense

— michaelscott

The principles you might be referring to are Gestalt principles which I call out as foundational to the gridless concepts. The design grid helps designers adhere to those principles but those principles do not come from the grid.

I was surprised by how many right angles, rectangles, and perpendicular lines I saw for a site focused on not using a grid.

— itronitron

Cute. Alignment found in a web page does not need to be the result of a design grid. It will be a result of applying Gestalt principles with the rules of authoring web documents.

This seems like more of a commentary on responsive design than on grid based layouts. There’s a big difference between designing for print/for the web, and a really good designer will be able to give you a grid layout that performs well between breakpoints.

— spcebar

I was on board with this until the last phrase. I believe a informed designer will give you guidance about what should occur when the ideal layout isn’t possible on a user’s device. Not necessarily as a designed comp, but as a conversation. Prescribing what happens at a breakpoint is a lazy solution, in my opinion. Considering how elements might shift in different viewports, orientations, translations, writing-modes, etc. is not scalable as artboards. Having conversations will make more inclusive designs.

I, personally, prescribe to the 1px grid system - where I write all my widths, heights and offsets in multiples of 1px. It helps keep things consistent.

— munk-a

Thanks, I hate it.

Fetching web component definitions

Tue, 12 Apr 2022 00:00:00 GMT

I love web components. Being able to just plop a custom element onto a page with all the functionality baked in without needing a framework or bundling to make it work is just liberating. I know there’s a lot of overhead that comes with it that libraries and frameworks aim to abstract but I just enjoy having the low-level ability to do whatever you want.

The trickiest part of web components for me has been how to identify when a web components, which is written as HTML, needs to be defined through JavaScript. From a performance point-of-view, we don’t want to send JavaScript to the page for components that aren’t there. On the flip side, we don’t want to miss components that apppear later in the lifecycle of the page.

The technique I’m about to explain is something I was working on at Compass but was never completed. Since then I’ve also enhanced the approach to be a bit easier to setup.

Registrar

The core of the approach uses an immediately invoked function expression (IIFE) which does a few things:

Listens for new custom elements appearing on the page.
Fetches definitions for elements that are not defined.
Listens within new shadow roots for additional elements.

Let’s describe how it does each of these.

Listening for new custom elements

The technique for detecting when an element appears in the DOM is not new. It was first discovered by Daniel Buchner as early as 2012. This was the basis behind identifying when a custom element appears on the page with a few changes.

First, I use visibility as the trigger for the animation. The reason for this is because it is not commonly used for animations like opacity would be. This avoids possible conflicts where these elements would be animated more traditionally. So the declaration block that triggers the animation would begin to look like this:

... {
  animation: undefined-detection .1ms;
}

@keyframes undefined-detection {
  to { visibility: visible; }
}

The missing piece is the selector to target these custom elements. In my original implementation, I would generate the list of elements to find here however, there is a better way. Because what we are looking for is custom elements that are undefined, there’s a CSS selector that can target all of these.

:not(:defined) {
  animation: undefined-detection .1ms;
}

@keyframes undefined-detection {
  to { visibility: visible; }
}

Yep, that’s it. Now the undefined-detection animation will trigger for all custom elements that are not yet defined.

So we will write this CSS to the <head/> of the page within the registrar and begin listening for the animation.

const ANIMATION_NAME = 'undefined-detection';
const CSS = `
  :not(:defined) { animation: ${ANIMATION_NAME} } 
  @keyframes ${ANIMATION_NAME} { to { visibility: visible } }
`;

(function registrar() {
  function observe(root) {
    if (!root) return;
    root.addEventListener('animationstart', onAnimationStart);
    const styles = Object.assign(document.createElement('style'), {
      type: 'text/css',
      textContent: CSS,
    });
    document.head.insertBefore(styles, document.head.lastChild);
  }

  function onAnimationStart({ animationName, target }) {
    if (animationName !== ANIMATION_NAME) return;
    // tagName is the custom element name
    const tagName = target.tagName.toLowerCase();
    // target is the element identified
  }

  observe(document.documentElement);
})()

Fetching the definition

This requires a bit of infrastructure. In my custom element library, each component is bundled into its own IIFE, available at components/[COMPONENT_NAME].iife.js in relation to the registrar. We can then determine the location of the components when the registrar is invoked with the following script.

const SOURCE_DIR = new URL(document.currentScript.src).href.replace(/[^/]*$/, '');

The code above determines the url where the current script is located and then removes the registrar.iife.js file name. I haven’t found a cleaner way to do this without the ugly regex and without requiring to know the file name here. I wish browsers had the path module from Node.

Then we can determine the location of the components by building a url with this variable.

const src = new URL(`components/${tagName}.iife.js`, SOURCE_DIR);

From there, it’s easy to load the definition at this location. Here’s what the registrar looks like with this included.

const ANIMATION_NAME = 'undefined-detection';
const CSS = `
  :not(:defined) { animation: ${ANIMATION_NAME} } 
  @keyframes ${ANIMATION_NAME} { to { visibility: visible } }
`;
const SOURCE_DIR = new URL(document.currentScript.src).href.replace(/[^/]*$/, '');

(function registrar() {
  const elements = new Set();

  function observe(root) {
    if (!root) return;
    root.addEventListener('animationstart', onAnimationStart);
    const styles = Object.assign(document.createElement('style'), {
      type: 'text/css',
      textContent: CSS,
    });
    document.head.insertBefore(styles, document.head.lastChild);
  }

  function onAnimationStart({ animationName, target }) {
    if (animationName !== ANIMATION_NAME) return;
    const tagName = target.tagName.toLowerCase();
    register(tagName);
  }

  function register(tagName) {
    if (elements.has(tagName)) return;
    elements.add(tagName);
    const script = Object.assign(document.createElement('script'), {
      type: 'text/javascript',
      defer: true,
      onload: () => script.remove(),
      onerror: () => script.remove(),
      src: new URL(`components/${tagName}.iife.js`, SOURCE_DIR)
    });
    document.head.appendChild(script);
  }

  observe(document.documentElement);
})()

The additional parts added are to ensure we don’t fetch definitions for things we are currently loading or have already loaded and to clean up the scripts being added to the page after they have completed.

Handling shadow roots

So we’ve solved for when custom elements appear on the page but not when they appear within other custom elements. There’s a little more work to do here.

When a custom element is identified, we’ll want to listen inside of its shadow root for undefined elements. We can do that in the event trigger.

function onAnimationStart({ animationName, target }) {
  if (animationName !== ANIMATION_NAME) return;
  const tagName = target.tagName.toLowerCase();
  register(tagName);

  // When the custom element is defined, begin looking for custom elements within
  window.customElements.whenDefined(tagName).then(() => observe(target.shadowRoot));
}

This will also require us to change the observe function since shadow roots do not have a <head/>. This is what the final registrar function looks like.

const ANIMATION_NAME = 'undefined-detection';
const CSS = `
  :not(:defined) { animation: ${ANIMATION_NAME} } 
  @keyframes ${ANIMATION_NAME} { to { visibility: visible } }
`;
const SOURCE_DIR = new URL(document.currentScript.src).href.replace(/[^/]*$/, '');

(function registrar() {
  const elements = new Set();

  // Determine the anchor and target to set the resources
  function location(root) {
    return root === document.documentElement
      ? { anchor: document.head, target: document.head.lastChild }
      : { anchor: root, target: root.firstChild };
  }

  function observe(root) {
    if (!root) return;
    root.addEventListener('animationstart', onAnimationStart);
    const styles = Object.assign(document.createElement('style'), {
      type: 'text/css',
      textContent: CSS,
    });

    // Here's where we determine where to attach the resources
    const { anchor, target } = location(root);
    anchor.insertBefore(styles, target);
  }

  function onAnimationStart({ animationName, target }) {
    if (animationName !== ANIMATION_NAME) return;
    const tagName = target.tagName.toLowerCase();
    register(tagName);
    window.customElements.whenDefined(tagName).then(() => observe(target.shadowRoot));
  }

  function register(tagName) {
    if (elements.has(tagName)) return;
    elements.add(tagName);
    const script = Object.assign(document.createElement('script'), {
      type: 'text/javascript',
      defer: true,
      onload: () => script.remove(),
      onerror: () => script.remove(),
      src: new URL(`components/${tagName}.iife.js`, SOURCE_DIR)
    });
    document.head.appendChild(script);
  }

  observe(document.documentElement);
})()

Missing pieces

One edge case that this approach might not catch is when custom elements are dynamically added to defined elements.

In other words, if <my-element> appears on the page, we define it and immediately add the listener to only that shadow root. While it does determine if any custom elements within its lifecycle need definitions, later <my-element> components added to the page will already be defined and therefore not trigger dynamically added custom elements within those later components (because the triggering resources aren’t added to subsquent shadow roots).

To have true coverage, the triggering resources would need to be added to all shadow roots. Luckily, this could be solved by importing the node detection CSS separately within each component which will trigger the registrar to fetch the definition; something that could be part of the library building script.

import CSS from '../registrar.js';
class MyElement extends window.HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }).innerHTML = `<style type="text/css">${CSS}</style>`;
  }
}
window.customElements.define('my-element', MyElement);

Listening for defined

You may have considered another approach to use node detection to just look for defined elements.

:defined {
  animation: defined-detection .1ms;
}

From there we could just add the target resources to each element; skipping the customElements.whenDefined check since the CSS animation trigger should catch it instead.

root.addEventListener('animationend', ({ animationName, target }) => {
   if (animationName !== 'defined-detection') return;
   observe(target.shadowRoot);
})

There’s one catch, the :defined selector will trigger for all elements (<html/>, <div/>, <p/>, etc.) and for every single one of them found on the page. While you could certainly filter for specific custom elements with open shadow roots, it’s still a lot of callbacks firing. Another reason why having a list of elements to update or pre-updating with the triggering resources seems to be better approaches.

All together now

Once you have the files bundled and deployed, you can just add the registrar to each page and it’ll begin fetching definitions. I’ll add defer so it doesn’t block the page from loading.

<script src="registrar.iife.js" defer>

And that’s it, we’re automagically getting the definitions for web components on-demand!

Fit Text Responsibly

Fri, 05 Dec 2025 00:00:00 GMT

Adam Argyle made a post on Bluesky today announcing a new property called text-grow is now available in Chrome Canary 145+. Much of the folks I follow there have been very excited about it. But I’m here to tell you to be careful.

About fit text

The concept of fit text is not new. The idea is that the size of the text will adapt to each line such that every line fills the width of the container. It’s sort of like text justification, but instead of adjusting the spacing between words and letters, it adjusts the size of the text itself. Here’s the video from Adam’s post:

Lea Verou asked around the internet to get use-cases for the behavior and while there’s no shortage of reasons why someone might want it, this calls for the Jurassic Park meme.

Accessibility awareness

Any time that we mess with the size of text, it makes me think of how my parents have made changes in their devices to set the text size for it to be more legible. I think about how the text we enter into our experiences is not necessarily the text that another user will see after translating it. It drives the point home that the less we try to control how text appears, the better the experiences are for the widest audience.

In Adam’s post on his website, he’s linked to several resources. One of them is the discussion about adding this feature to CSS. I want to call out some of the quotes from the discussion specifically regarding accessibility:

I just finished a research project on personalization and accessibility (under review) and the most common action taken by people who are considered low vision is to customize text size. Inability to change text size is a pretty significant barrier for many people. Meta-analysis research from 2020 estimates that around 600 million people worldwide would be considered on the spectrum of “low vision” to blind, which was roughly 8% of the world population in 2020. These numbers are expected to grow, due to compounding socio-economic factors, by 2050. This isn’t just a small slice of people.

— frankelavsky

Making text dependent on the viewport has always been problematic for accessibility, this is well documented. This is why we usually advise not to use clamp or vh/vw units in font sizes. It just overrides user preferences unnecessarily.
The only way this could pass muster is to require browsers to include an opt-out to the behavior. Or to ignore it when users zoom in, which would defeat the purpose of the proposal.
I second Patrick’s pointer at LVTF and general W3C horizontal review. It might be good to generally outline when you get specific accessibility input to ensure that proposals are feasible to implement so that all users can use them.

— yatil

The explainer mentions that there’s still an open question about accessibility for this:

If an end-user tries to enlarge font size, UAs should not fit enlarged lines to the container width. Is minimum-font setting enough?

My worry is similar to the one I have with folks reordering elements visually with CSS. Just because we have CSS technologies, doesn’t necessarily mean that they should be used in any situation. It’s not often that folks really consider the impact of every CSS decision. The large majority of developers are just picking the first solution that works and move on. Taking a moment to consider how our decisison affect more than us is a fading responsibly.

Maybe not for screens

All that said, I think this can be used responsibly. I think for folks using CSS for print media, this could be a useful tool since after text is printed there’s no way of having user settings affect it. Many of the folks that provided visual examples in Lea’s post providing media meant for printing. In reading some of the other replies, it really looks like many of the use-cases are for non-web things. This example is from Kris des Chacals asking for this property for use in OBS.

Maybe the problem is that CSS is becoming too powerful and now we want to use it for everything. I know I do. 😅

Fluid Headings

Fri, 10 Oct 2025 00:00:00 GMT

There’s no shortage of posts that explain how to perform responsive typography. Here’s a small sample of them:

And that’s just articles from a single website!

However, in those articles no one really mentions what qualities you are meant to look out for when figuring out the values. I’ll admit the closest article to this is the first article which explains that if you use only viewport units for a font-size that it’ll break the zoom expectations in the browser, which will cause a WCAG 1.4.4 failure. The recommendation there is to always include a non-viewport unit in the calculation with your viewport unit.

Well, I’m about to turn that on its head. 🙃

What I set out to do is to have a rule that helps explain what the transition should be for heading font sizes between large and small screen sizes. In other words, what the middle value of a CSS clamp() function is expected to be.

Min and Max

First, we need a few numbers to start. The first two are up to you, your font family, and typescale. These will be the minimum size and the maximum size your heading is meant to be. For the purposes of example and to exaggerate the effect, let’s consider this in terms of marketing display text. Really big and fun text on desktop but somehow needs to be reasonable on a small device. In this example, I’m just going to make variables for these and they’ll be in the places where you’d expect in the clamp() function:

.text-heading {
    font-size: clamp(
        var(--heading-smallest),
        /* heading change */,
        var(--heading-largest)
    );
}

The middle value is what we’re going to calculate, and we’re going to do that with a few more numbers. A minimum viewport size and a “maximum” viewport size.

The minimum size that I’ll recommend is 320px. This comes from the WCAG 1.4.10 about reflow.

Vertical scrolling content at a width equivalent to 320 CSS pixels

The “maximum” is not really the maximum viewport size. It’s closer to being a breakpoint of sorts. What this size is meant to be is the point in which the largest size that the heading is meant to be starts shrinking to the smaller size. It’ll stop shrinking at 320px. What we’re going to explore is what that size is meant to be.

My thinking for this starts with the recommendation of number of characters for body copy, which is somewhere between 40 and 80 characters depending on your source. I typically pick a number in the middle, 60 characters, to represent the optimal reading length. Importantly, this is speaking about paragraphs. This is not meant to be the same number for headings, and in my research I couldn’t find a number that represents what the optimal character length for headings is meant to be. If there is one, please let me know.

To make up for this, I figured that we typically want to lockup paragraphs with the heading. We want them to visually match together. If we’re still speaking in terms of characters and the body copy can be represented as 60rch (assuming that the root font size dictates body copy), then we could also set the heading maximum length in terms of those characters. So that means that the “maximum” viewport width should be 60rch for headings.

It’s also possible that this feels too large for you. If you disagree and feel that the length of the heading is meant to be shorter than the related copy, then feel free to update this value. But the expectation is that this a maximum length that causes the wrapping behavior of the heading to achieve LooksGood™ status.

Time for the math

Ok, these will be all of the values we need to determine the middle number. Here’s the formula:

$m=(y_2-y_1)/(x_2-x_1)$

If that looks familiar, it’s because you may have read my other typographic posts that discuss a rate of change. This is trying to determine the slope of a line. Let’s write this in terms of CSS:

.text-heading {
    --m: calc(
        (var(--heading-largest) - var(--heading-smallest))
        / (60rch - 320px)
    );
}

Except this wont work this way in CSS. We’re not able to divide with a unit number, which would be the result of 60rch - 320px. While you could do some fun hacks to make this work, I’m going to suggest something different: to make everything in terms of rem.

The --heading-largest and --heading-smallest are probably in terms of rem already or something relative to font-size like rem. So if we update the numbers below to also be rem, then we don’t need the units in the denominator. In my experience, this seems to be the following:

.text-heading {
    --m: calc(
        (var(--heading-largest) - var(--heading-smallest))
        / (30 - 20) /* 30rem - 20rem */
    );
}

Now what we need to do is relate this to how the viewport changes. I specifically recommend viewport over container because having different sized headings depending on the container instead of the context of the content could be hierarchically confusing. Having all of the same heading behave identically maintains the hierarchical relationship across all areas uniformly.

Scaling text

The last part is borrowed from this post on CSS-Tricks, which also explores responsive typography but has a special distinction: when you resize the examples, the text looks like it scales as if you wired scale() to the viewport for the text. I found this to be the missing part to fluid headings.

My goal was to keep the wrapping composition between the “maximum” and minimum. While Pedro’s post uses JavaScript to do the heavy lifting (because the dividing problems we mentioned earlier), we can get there in CSS. In fact, our implementation is arguably easier than his because we want this change to be linear. In other words, as the viewport changes, the rate of change is a straight line between the max and min. What this does is maintain the wrapping composition of the heading between the max and min. This is that scaling effect from the post.

Here’s how we’d finish this:

.text-heading {
    --m: calc(
        (var(--heading-largest) - var(--heading-smallest))
        / (30 - 20) /* 30rem - 20rem */
    );
    font-size: clamp(
        var(--heading-smallest),
        var(--m) * 100vw,
        var(--heading-largest)
    );
}

Remember, the recommendation is for viewport units in the font-size to be accompanied by some non-viewport units, which is what the --m is providing. --heading-largest and --heading-smallest are font sizes you’ve set for headings.

You can check a working example out on my design system playground or if you just want to watch the magic, I have a animated GIF below:

Hopefully, this takes less of the guess work into the numbers that are meant to appear in the clamp() and maintains typographic lockups more regularly.

Font size dimensions

Fri, 20 Jun 2025 00:00:00 GMT

First, we used pixels to describe the size of things on the web. Most digital tools and technologies communicated in pixels so this seemed like a logical decision to use. Over time, we’ve received other units in CSS that were relative to some other amount. Percentages were based on the parent element and many other units were based on font size.

The use of font size was highly misunderstood across our practice for years. One of the earliest concepts was converting (r)em to pixels since many people weren’t familiar with the new units, but saw benefits to using (r)em in other areas outside of updating the size of the font. Unfortunately, this eventually turned into the bad practice of setting font-size: 62.5% on the html element.

Space

In my later work, I did adopt the concept of using (r)em to define elements outside of font size, specifically space. This looked promising since areas that had larger typography also typically have larger spacing. However, I’ve more recently walked that back. This is because of accessibility.

If we decide to use font relative units to define space and a user decides to increase the font size of the text, this would also increase the amount of space between elements. This would make the overall composition very large. I realized this while exploring Complementary Space, because I could separate what space meant at different regions. It made more sense to keep the amount of space effectively static (using pixels) between elements as long as the perceived hierarchy was maintained. As an example, as long as the space found in the hero section was larger in relation to the space found in table cells, the text could be sized up for legibility while maintaining the essence of hierarchy. This would keep the overall layout smaller while allowing the text to be as large as the user needed.

Width

Another place where people tend to try using relative units is for defining the width, either explicitly or as a limit. One of my principles for composition layout is to not define widths and let the content dictate the size of its container. This isn’t always possible. One common example is when using display: grid. I tend to use the repeat(auto-fit, minmax()) technique to define columns dynamically and this requires some dimension for the minimum or maximum. Most of the time I set this as minmax(260px, 1fr) for card containing layouts and the 260px has very much been a LooksGood™ value that I didn’t put much thought into.

So are relative font units helpful or hurtful when defining width? To get an answer we need to understand why we are setting a value for the width at all. Generally, we set a width on an element so it maintains an expected size, but why? As a thought experiment, we can consider an element primarily made up of text, we want the text to have an optimal reading composition. Lines that aren’t too long but also lines that aren’t too short. This also depends on the kind of content. Optimal line length for long form articles is around 60 characters, give or take. We can use that number to set a maximum width for the article; 60ch.

We don’t need to go too much further to see that the number of characters is something we take into account when speaking about the width of an element. We can imagine this in the opposite direction, if the element is too small, the lines look smooshed. Here’s where we find the key insight. If we defined the width of an element using relative font units, and the user increases the font size, what happens? Think about it.

Let’s use 30ch as a maximum width, which is approximately the 260px value from earlier, not counting the card padding using common font metrics for the body. As the user increases the font size, what 30ch means will also increase as pixels. This means that the 30 characters will continue to be 30 characters, just larger in pixels. Visually, this would look like if we scaled the whole element up. This maintains the overall composition as the font size increases.

On the other hand, if we used a 260px maximum width, the sheer size of large text would wrap too quickly, causing premature line wrapping because the pixels aren’t increasing with the size of the text. For this reason, I now recommend using relative font sizes, more specifically (r)ch units, to define widths. That is, if you truly need to define a width at all. For me, the best case is to still avoid setting a width wherever possible and let the content dictate the size.

Breakpoints

The reason that I had the idea for this article is due to this post on LinkedIn by Matthew Wood. He explains the advantage of using (r)em for media and container queries. He outlines how the approach helps support specific articles within the WCAG, 1.4.4 and 1.4.10.

Due to the common use of minimum and maximum widths in breakpoints, and our earlier exploration into the benefits of maintaining layout composition when using relative font units for this, I can agree that using relative font units for breakpoints would be preferred over pixel values. That is, if you need breakpoints at all.

As I wrote years ago within Gridless Design, the web was made to flow like a document. So if something doesn’t fit, the best way to handle it is to let the element wrap underneath. The more custom you want that behavior to be, the more difficult it is to appropriately handle how it is meant to behave for different user preferences and devices.

Summary

These are my new rules of thumb based on the earlier explorations:

Use fixed pixel units (px) for spacing.
Avoid setting dimensions wherever possible.
If you must set a dimension, use font relative units ((r)ch).

I wouldn’t consider these rigid, but I would refrain from deviating unless you truly understand why.

And for heavens sake don’t make tokens for dimensions. Dimensions are specific to the layout. This includes breakpoints because when the layout breaks isn’t due to being a specific device. It’s because the current composition visually breaks at this point. Unless you’re making tokens to define the parts of layout, avoid making tokens for dimensions.

The Hottest Box

Mon, 16 Sep 2024 00:00:00 GMT

Over the past year, I’ve had the task of creating layout components for an organization. This is something that was initially confused about. My initial assumption was that everyone knows about flexbox! It’s our lord and layout savior! Jokes about centering content should have vanished away now that we can use flexbox! Oh, how naïve I was.

Realistically, the developer landscape doesn’t hone these skills well, and instead hides them behind APIs; even if those very APIs are identical to what a person would write in CSS. It’s true, people will do anything to avoid writing code in a .css file.

Honestly, I stumbled all over making a robust layout component. The following is considerations I take into account and how I might build a new component if I was given another opportunity.

Layout

The first thing I’d take into consideration is layout using flexbox. I’m avoiding introducing grid configurations here. I’ve found that in the years I’ve been working with CSS, grid is the lesser used layout technique. It certainly has benefits over flexbox in many cases, but the majority of layout needs revolve around aligning items on a single axis in a container.

Much of the confusion about flexbox comes from the alignment properties; align-items and justify-content. They are very easy to get mixed up and, the results can be unexpected when you change the flex-direction. I believe an improvement here would be to simplify the API.

<Box stretch stack>Hello world!</Box>

The first thing I’d introduce is the boolean properties of stretch and stack. The stretch flag would switch between inline-flex and flex so the container can fill its parent. The stack flag would toggle on flex-direction: column so the children stack in a single column. I’d also include wrap to align directly to flex-wrap: wrap.

With that out of the way, now we need to address the alignment properties. Generally, the expectation for someone manipulating layout is to place the content in one of 9 locations within the container. For example, take the following CSS:

.box {
    display: flex;
    align-items: start;
    justify-content: end;
}

This code will place the content in the top-right corner of an LTR container. But with one line of code, it’ll completely flip the position to the bottom-left corner:

.box {
    display: flex;
+   flex-direction: column;
    align-items: start;
    justify-content: end;
}

In my opinion, this is unexpected. The intention to show the items in a row versus a column shouldn’t have an effect on the alignment in this case. Instead, I’d like to see an approach where someone could configure the items such that the stack has no effect.

Furthermore, I’d like to lean into CSS Logical Properties, such that configuration inputs have aliases; left / top would transform to start and right / bottom transforms to end, of course allowing these values directly as well. I could imagine some flag that turns off (eg., logical=false) this translation in cases where we want to force the direction regardless of the writing mode.

<Box logical={ false }>
    Media player timeline
</Box>

Importantly, we’d need to inform what axis to apply the start or end. Logical properties describe that the horizontal axis is the “inline” direction, and the vertical axis is the “block” direction. As we have seen, when we update the flex-direction, these axes flip where I’d argue this is largely unexpected. So instead of using align and justify, I’d suggest inline and block, similar to how padding and margin would be modernly applied.

With this all in mind, we’d have the following:

<Box
    stack
    inline="left"
    block="bottom">
    Hello world!
</Box>

Regardless if the stack was applied or not, the children of this LTR container would be placed in the bottom-left corner. In an RTL container, the items would be placed in the bottom-right corner because logical defaults to true.

The final element to consider here is handling the concept of “self”. The flexbox ecosystem allows an item to essentially override the placement given by the parent through properties such as align-self and justify-self. Knowing this, we can also see a potential problem with the current API. The words inline and block aren’t clear as to what they are affecting. A better API naming convention would be more clear about what these are doing. That is why the flexbox APIs include the words items and content; they are affecting the elements inside this container, not the container itself.

This means that we should have similar but separate APIs for the concept of affecting the elements inside versus the element itself. We can communicate that layout is affecting the interior children with inset (ie., interior setup) and the exterior self with outset:

<Box
    inset={{ inline: 'start', block: 'end' }}
    outset={{ /* Similar options */ }}>
    Hello world!
</Box>

We could also consider shorthands that handle these with a single value; affecting both inline and block in the same way. The following would place the text horizontally and vertically within the box:

<Box inset='center'>
    Hello world!
</Box>

One more thing to mention is the more nuianced alignment properties, such as justify-content: space-between. Since we’re hiding implementation details to match some new expectations, I’d consider an option that would effectively override the given inline or block (depending on the stack flag) to distribute the children.

<Box stack inset="center" distribute="between">
    <Box>Child 1</Box>
    <Box>Child 2</Box>
    <Box>Child 3</Box>
</Box>

In this example, the justify-content would be set as space-between instead of center. I’m avoiding the word “space” here to not confuse with other spacing properties such as padding or gap which we’ll introduce later.

Appearance

By default, it makes sense to allow this container to be invisible when a configuration is omitted. This helps with general layout approaches, allowing boxes to be arranged without explicitly showing boundaries. However, in some cases we may want to have a box appear segregated from other boxes.

Aligning with the idea of Mise en Mode, appearance properties would be informed by the use of intents (ie., strict semantic tokens) where we’d consider the priority that this box is meant to convey. So the box with the highest priority would be presented in a way that was clear to a user that they should pay attention here first before looking at other elements. This suggests that there is a priority setting that could either be numeric (1, 2, 3, and so on) or Latinate ordinal numbers (primary, secondary, etc.). I’d recommend the latter and having only default, secondary, and primary. This reduces the decision-making paralysis; making it more clear which to use. Having a number system of significant size makes it challenging to determine the most appropriate number. I also suggest using the term default over including tertiary as if you need an additional level, you can include it later.

Continuing with the Mise en Mode concept, this allows any box to present itself with any color combination as provided by the current mode. This means, if you need a purple gradient to convey the supreme intelligence of AI, you can do it by informing the intents with new values, not by providing new tokens directly to a component.

I believe the priority of any box is more closely tied to the concept of surfaces. We could imagine that the default priority to be the base level of the page where most UI elements would live. Next, the secondary level could be reserved for elements that are meant to appear on top of the UI but are contextual to some anchor. You can think of flyouts like context menus or tooltips. These are introduced because there is some more important information for you to take in before continuing, but they aren’t typically the most important thing to do. Finally, the primary level would be a full disruption like a modal, which is meant to appear on top of everything blocking further progress.

<Box aria-modal="true" inset="center" priority="primary">
   Hello world!
</Box>

Any one of these priorities would apply additional presentational styles to the element to allow it to convey the priority consistently. This is so our users can subconsciously learn the hierarchical order of the content and make better decisions.

Spacing

Continuing with Mise en Mode, more specifically its origins of Complementary Space, I believe we’ll only need two spacing options for box: padding and gap. These would be flags and not expecting values like T-shirt sizing. This is because the mode would inform the size.

/* Example 1 */
<Box padding gap>
    <Box>Child 1</Box>
    <Box>Child 2</Box>
</Box>

/* Example 2 */
<Box padding gap data-mode="density-shift">
    <Box>Child 1</Box>
    <Box>Child 2</Box>
</Box>

The data-mode in the second example indicates that a mode changes occurs here. This would affect all intents of this element and below new values. The density-shift value would refer to a mode that expects the density to shift down one level, such that padding and gap are smaller than if this mode wasn’t applied; as in the first example.

You might consider simply adding mode as the option instead. I’m specifically using data-mode to indicate that this isn’t specific to <Box/> but more related to Mise en Mode. If this element is meant to be the base of all other elements, then mode could be appropriate.

If Complementary Space is too radical of an idea, feel free to wade in the depths of applying T-shirt sizing values.

Loading

Some work that was being done in parallel to the layout component was that of a skeleton loader. For many systems, this is a separate component than any others in the system for the specific purpose of displaying a placeholder while work is done in the background. This has the perception that the system is processing, as opposed to having a blank area waiting for content to appear.

It was at this time that I realized that if the skeleton component represented content, and the box component was meant to arrange content, what if the box could represent placeholder content until it was provided? In other words, we can mark <Box/> elements with an attribute that shows a skeleton loading presentation if the element has no content. Consider the following simple card layout:

<Box stack padding gap>
    <Media src={ src } />
    <Box stack padding gap data-mode="density-shift">
        <Box standby>{ title }</Box>
        <Box standby>{ description }</Box>
        <Box standby>{ actions }</Box>
    </Box>
</Box>

The standby flag would show a skeleton loading presentation to elements if no content is provided. That could be done with the CSS :empty selector.

[data-standby]:empty {
    /* Skeleton loading presentation */
}

Once content is added, the selector would no longer match and the skeleton styles would be removed through CSS. We could also consider being explicit about when the loader should be shown by using the value of data-standby="true".

The purpose of embedding the ability to display a skeleton in any layout is powerful; assuming performance cannot be improved. This means that you can have a layout reused between the expected result and the lack of information with a single composition; just add content. No need to create a separate layout for when the content is missing and another for when the content is finally resolved.

Semantics

Something I’ve glossed over is how to assign the element that this component represents. In some systems, this is done with another prop that informs the HTML tag name to use (<Box as="section"/>). Instead, I’d recommend trying a different approach.

<box.section>
    Hello world!
</box.section>

In this way, it is more clear that the section part of the element is related to the element that will be rendered. Using as could be more ambiguous to what the prop is meant to do, such as the word variant. You could also consider a more generic default export as Box that refers to a simple box.div.

Demo

Here’s a demo of the concept, missing all the mode changing.

See the Pen The Hottest Box by Donnie D’Amato (@fauxserious) on CodePen.

EDIT (2024-09-26): Devon Govett recently posted a similar approach where a <Skeleton/> wrapper is added to any component in the system which will cause media and text elements inside to shimmer. Based on what I’ve written above, of course I really resonate with this. I like how the wrapping component is the trigger because you can also add accessibility attributes in there to markup the loading state within.

There’s some feedback in the replies that challenges how the system is supposed to know what the content looks like. The fact is that we don’t need to know what the content looks like, we need to know what kind of content it is.

This is why thinking about design as intention over aesthetics is the key to systems thinking and how we could support this approach. For example, the intention for a heading is commonly for introducing a short concept or label. Therefore, the loading presentation for the area where a heading should appear could always be displayed as a single block instead of considering several lines. Certainly, it is entirely possible that the final content does create multiple lines however, the purpose of the skeleton is not to match one-for-one with the incoming content. It is meant to indicate perceived progress using a loose blueprint of the expected content.

We already know the styles for the text that will appear once the content comes through, including the font size. We can use that font size to set the minimum height of the skeleton placeholder, perhaps using the new lh unit. Also know that any styles that we use for the skeleton do not need to remain for when the content is applied. If the lh unit isn’t appropriate for the incoming font, then no need to set a minimum height when the element is :not(:empty).

For paragraphs, you can pick a number of lines to display when we expect a paragraph. You could even be more considerate and wire in a container query that changes the number of lines based on the size of the paragraph. Wider paragraph containers larger than 60ch in width can display 2 lines, while smaller widths can display 3. This could imitate line wrapping for the same repeatable placeholder content. This way, a paragraph in a loading hero section would show 2 lines, while a more narrow card would show 3 lines.

The easiest one of these content elements to consider is the image or really any media. Best practice for loading media is to set the dimensions in the HTML to help with content shifts which would clearly dictate the size of the container for the skeleton. In the event you couldn’t do this, you could have predetermined expectations for that media; square, 4:3, 16:9, and even a circle for avatars. These styles are already most likely applied to the media element already, so we shouldn’t need to use too much imagination about how this skeleton might look.

Hovercraft

Thu, 24 Aug 2023 00:00:00 GMT

In a world where we apply personality to every little interaction for those sweet engagement metrics, the :hover CSS pseudo selector is one of the easiest ways for folks to “make it pop”. However, I’ll argue that perhaps we don’t need to put so much design into it; at least from a token maintenance perspective.

Looking good, feeling good

It is very common to have colors of a button change when a pointing device hovers over an interactive button. We often design for this because we’ve seen it before. It just feels right. You could argue it might not look interactive if it didn’t respond to the incoming cursor. Even the default user-agent button has a hover effect, how could one possibly defend not including this effect?

To start, let’s look at the default <a/> element and how that behaves. You’ll notice that most user-agent defaults don’t have any color change for the text. I’d theorize that there are two reasons for this. First, accessible text color is a challenge, especially when attempting to show a shade change on glyphs that are only a few pixels wide. This is the reason why most of the effects we decide to put on links are not color changes, but some other visual treatment like an underline visibility change or animation.

The second reason is the foundation of my argument; the cursor changes when you hover on these elements.

When a sighted user sees something they assume is interactive on screen, they’ll find the cursor and navigate it to the target. Once the cursor is in the interactive area of the target, it is common to provide feedback to the user that says we are in an interactive area now, clicking here will do something. The cursor change on links is enough of a signifier to the user that you may interact with this special text.

For the default user-agent <button/> styles, the cursor does not change. It remains the default arrow cursor.

Making change

The reason for the cursor difference on hover between links and buttons has some history and can be otherwise debated.

There’s a belief that the hand (pointer) cursor means clickable, but this is wrong and potentially problematic.

— Adam Silver

The issue with this statement is there’s nothing (past technical specifications) that tells daily users of the web the pointer cursor means you are hovering on a link. We have introduced the pattern of the cursor change for buttons, and for general interactivity, over time through shared expectations. This can be thought of as similar to the hamburger menu, which originally meant nothing to most users but has been learned over time; even if other more verbose design patterns exist. The hamburger menu has become ubiquitous, as has the pointer on buttons.

Due to this learning, I believe we could leverage the cursor change in the same way it has been done for links; the sole indicator of an interactive area awaiting your next move. That’s right, no color changes or fun 3D effects. Just a single pointer.

Form follows function

If a user is confused about an interactive element being a link or button, it does not come down to the type of cursor chosen. The Button vs. Link debate is mostly rooted in resting visual preference. Users expect underlined text to behave like a link. While text elements with padding and colored backgrounds often behave as buttons. Our users have grown to identify these patterns through repeated experiences across dozens of sites per day.

It would be beneficial to supply our users with expected experiences as any deviation can cause unwanted friction. A button using an underline and no padding will behave unexpectedly to a user, no matter how pretty it is. It is advised to offer sensible design treatments that maintain user expectations and common functionality.

Importantly, users will often use their eyes to identify and develop their expectations before ever moving the mouse to the target. This happens before the cursor has the possibility of changing. They are quickly making assumptions about what the target can do, all before they ever get a chance to hover it. And for folks not using their eyes; they’ll never experience the effect at all.

In the wild

I’ve gone through the 123 implementations of the button component at the Component Gallery; how many of them don’t use the pointer on hover? 6; 4% of all buttons found on the site do not change the cursor on hover. While the Bandwagon effect can certainly be a factor, this is most likely from patterns forged from real-world use. Know that the first interactive area on the web was the link, so we have grown to expect the pointer to appear as an interactive identifier in other areas in turn.

Further considerations

For folks who aren’t using a mouse to navigate, they need focus styles. The hover effect might not ever be displayed to these users. As a more complete recommendation, focus styles between interactive elements should match so a user can follow a standard identifiable treatment across the site.
For folks on touch devices, hover doesn’t exist except for some fleeting finger presses that occur after the interaction. In most cases, a person’s finger will otherwise obscure the effect when provided.
Using the cursor alone also avoids the need to curate specific colors for every type of button. No need to have a separate color for the default primary state and primary hover.
For buttons that have a selected state; omitting separate styles for hovering helps avoid the need to define a different appearance between unselected hover and selected hover. Otherwise, the number of definitions will increase not only for :hover but now include [aria-selected="true"]:hover for every single type of button in your library.
In CSS, instead of specifically writing a :hover style, the cursor: pointer; can be written on the button selector. No need for a new selector at all!

Consider a vote for cursor:pointer today!

Telling the truth

In reality, I don’t believe that a single cursor change is enough to indicate interactivity. A best practice of experience design is to have multiple signifiers to indicate new information. This is why using only color to indicate an error isn’t enough. It is better to include an icon to further enforce the status of the new message or state.

In this way, instead of choosing an entirely new color to indicate hover, one recommendation could be filtering the given color in some way on hover.

button:hover {
    cursor: pointer;
    filter: saturate(0.8);
}

For many colors, a slight shift in saturation should not cause accessibility concerns past what has been curated for the default state. If this approach causes the resulting color to not provide enough contrast between the text and background, that might mean the initial color itself is too close to the threshold and would serve better with more contrast. On the other hand, if the change isn’t perceptable to color-deficient folks, the cursor will be enough to indicate the intention, as suggested above.

In my perspective, there are often too many tokens to curate and anything that can be done to reduce the set and subsequent naming of additional tokens is a step in a maintainable direction. Omitting the hovered state as a themable variable helps reduce complexity and permutations.

Perhaps, we need a new way of looking at the ecosystem.

Design system business model where you have to pay for every token you use.

— Mark A. Cianfrani

This isn’t the model we deserve, but it’s the one we need right now.

Interoperable tokens

Thu, 16 Jan 2025 00:00:00 GMT

In my design system playground, one of my small goals was to have the ability to import a design token identically between CSS and JavaScript. Here’s an example of the developer experience I was expecting and succeed in making: to use tokens.$action_primary_backgroundColor as a value reference in both .scss and .js files identically.

Writing (S)CSS.

@use '../tokens.module';

button:where([data-priority="primary"]) {
    background-color: tokens.$action_primary_backgroundColor;
}

Writing JS(X).

import tokens from './_tokens.module.scss';

function PrimaryButton(props) {
  return (
    <button
        {...props}
        style={{ 
            backgroundColor: tokens.$action_primary_backgroundColor
        }}/>
  );
}

The important part is that the intention of using the background color for primary buttons is shared between the CSS and the JavaScript. tokens.$action_primary_backgroundColor is identical between these examples while being applied in different languages. This method helps reduce the context switching between writing CSS and writing JS to get the expected styling value.

Working source

I’ll cut to the chase, the following is a _tokens.module.scss file that all the components have access to. Here’s the file I use in my system. You’ll want to generate this file based on how you create and manage tokens in your system. You should expect many, many more entries in this file than what is shown below. This example is only supporting tokens.$some_token between .scss and .js files.

/** For .scss, $some_token does not need to match the --some_token  */
$some_token: var(--some_token);

/** For .js, the #{'$some_token'} needs match $some_token */
:export {
    #{'$some_token'}: $some_token;
}

Prerequisites

As you might tell, there are some requirements to this in order for the DX to work well.

You’ll need to ensure that the CSS custom property --some_token has a value and is present on each page such that var(--some_token) is later resolved. You could opt to not use a CSS custom property here if the value don’t change. However, if you have or plan to have dark mode in your system, then you don’t want to hardcode the values here.
You’ll need to be using CSS modules to get the JS import working, using the :export pseudo selector. Most JS frameworks support CSS modules with minimal configuration. The word module in the file name is required for the CSS Modules processing to pick this up as a CSS Module, so it can be imported into .js files.
You’ll need to be using SCSS to get the @use and $ variable syntax working in your .scss files. The leading _ in the file name _tokens.module.scss is required for the @use syntax to work. This will expose a tokens key in the SCSS based on the file name. In other words, to get the tokens. syntax in your files, your file name should start with _tokens..

Required characters

There’s lots of token naming constructions out there that delimit the sections of the token. For this to work, the underscore (_) is one of the only characters that will work between (S)CSS and JS.

The dot delimiter (.) will not be valid in .scss files.
The hyphen delimiter (-) will not be valid in .js files.

When you generate the _tokens.module.scss file, you’ll want to convert any delimiter to an underscore. As an example, if you have a token button.primary.backgroundColor, you’ll want to prepare that as button_primary_backgroundColor to be used in source files. This makes the name usable between .scss and .js files in an identical way.

The leading $ is expected for the SCSS ecosystem to be used as a variable. This is carried over into the JS ecosystem for consistency.

You can review the source of my system to find additional details:

Late start

Thu, 11 Sep 2025 00:00:00 GMT

I’ve been in the process of writing a book over the past year and the hardest part for me isn’t the writing, it’s the publishing. I’ve changed publishing systems a few times over the course of this work. I’ll most likely have a larger post speaking about the process later, but the current way that I’m expecting to prepare the book for publishing is with CSS. Yep, that’s right. Get your @page styles ready!

Getting the options that a more appropriate layout system like InDesign would have isn’t really possible in most browsers today. If I really wanted to lean into all of the features that CSS could have, I’d consider using PrinceXML. Though as it stands right now, I think I’ll have a good book without it.

That said, there was some really challenging constraints that I had to work through. One of those things was page numbers.

Meeting expectations

One of the cool things about CSS is the counter() function. This acts a bit like using state in CSS in limited way. To explain, here’s what using state in React might look like:

function MyCounter() {
    const [count, setCount] = useState(0);
    return (
        <button onClick={ setCount(count + 1) }>
            { count }
        </button>
    )
}

We can effectively do the same thing in CSS. Here’s a basic setup with some comments that explain what each of these relate to:

ul {
    /* const [count, setCount] = useState(0) */
    counter-reset: count;
}

li {
    /* setCount(count + 1) */
    counter-increment: count;
}

li::marker {
    /* (print) count */
    content: counter(count);
}

One of the bigger differences is that the count increases when an element exists at a selector. I imagine we could get some interesting state machine stuff with selecting values from inputs. But that’s not what we’re after today. Instead, I want to delay the start of the numbers.

If you open up a technical book, you’ll find that the page numbers don’t start right after your crack open the cover. There’s a few a pages that either don’t have numbers, or have a different counting system like lowercase Roman numerals. Doing this in React would be fairly easy, we can set the start of the counter to a negative number and only print the number if the value is larger than 0:

function MyCounter() {
    const [count, setCount] = useState(0);
    return (
        <button onClick={ setCount(count + 1) }>
            { count > 0 ? count : '' }
        </button>
    )
}

In CSS, we don’t have this fine-grained conditional logic just yet. There’s definitely ways to do some tricky operations and maybe there is a way to do it using some of the newer functions, but I found something that’s a little more appropriate when dealing with counters. The new @counter-style at-rule.

Custom counters

CSS has had keywords that describe the method of counting for a long time. It’s the same way we’d often remove the style from <ul/> elements to drop the bullets for other presentations.

ul {
    list-style-type: none;
}

For something like a <ol/> element, the list-style-type is set as decimal. You may also know that <ol/> elements have a special start property that allows us to start the count at a different number. Immediately, you’d think that we’d use that like our negative setState(-3) from before. And while you can, it won’t work for my use case. Since I’m using @page to display page numbers in print media, there’s no “element” for us to apply it to. That’s ok, CSS counters have a syntax that allow us to update the start for a counter and we can make it increment at each page.

Here, I’m going to start the count at the first page, name the counter page, and increment at every page:

@page :first {
    counter-reset: page -3;
}

@page {
    counter-increment: page;
}

That’s a good start, but the problem is that the first page will print the number -3 at the bottom which is not what we’re looking for. Instead, I’d like these to be blank. To do this we’re going to need two @counter-style declarations:

@counter-style false-start {
    system: extends decimal;
    range: 1 infinite;
    fallback: blank-only;
}

@counter-style blank-only {
    system: cyclic;
    symbols:  ;
}

The first @counter-style has the name false-start which extends the decimal system which would normally be no different than the default counter. However, the first key here is that the range is set to 1 infinite which say to only use positive numbers starting at 1. When using range you can also use a fallback which says if the counter produces a number that cannot be written, use this style as a fallback.

The second @counter-style uses system: cyclic; which is normally used to cycle through the given symbols. In my case, I’ve provided whitespace. This means that when a negative number is passed into the counter, it will print whitespace. This allows me to set an offset and only print numbers starting at 1 exactly where I want them to start. Here’s the whole code using @page, and a Codepen demonstrating it using <li/> elements.

@counter-style false-start {
    system: extends decimal;
    range: 1 infinite;
    fallback: blank-only;
}

@counter-style blank-only {
    system: cyclic;
    symbols:  ;
}

@page {
    counter-increment: page;
}

@page :first {
    counter-reset: page -3;
}

@page :left {
    @bottom-left-corner {
        content: counter(page, false-start);
    }
}

@page :left {
    @bottom-right-corner {
        content: counter(page, false-start);
    }
}

See the Pen Late start with @counter-style by Donnie D’Amato (@fauxserious) on CodePen.

Sure, my use-case is very specific but maybe there’s someone else out there looking to write a book and not looking to learn a new language to do it.

CSS is awesome and it could be awesomer. Rachel Andrew has an article published over 10 years ago that outlines some of the other cool things that we could have.

h1 { 
  string-set: doctitle content(); 
}

What the hell is this? It’s taking the content of the <title> and writing it into the <h1> on the page! While I have no idea what this means for an accessible web page, this is meant for print and adding the content into the margins of the book. This ability of grabbing HTML content to use in CSS is incredible. It would open up a lot of possibilities (and poor behavior). There’s even a full @footnote feature in there too.

Unfortunately, these aren’t in any browsers today. I guess who is printing things anyway now that the reading is done with AI? Silly me.

Less Gridless

Wed, 09 Apr 2025 00:00:00 GMT

I released Gridless Design nearly 4 years ago as a response to a frustration I saw in the industry. Similar to the desire for responsive design, it was a call for folks making digital applications to take the foundations on the web into consideration when creating things on top of it. It has the same foundational argument attached to “should designers code” because it asks designers to understand that the web is not an artboard. It also helps engineers support designs when a grid is no longer part of the handoff.

Gridless Design was my first project that got a lot of discussion across the industry. Most leaders in our practice agreed with the take, while others with less experience were skeptical to say the least. I’ve had analytics tied to the site for a long time, and it continues to be a top performer among my other work. Some of the places that currently link to the work are:

This is among other internal resource sites like Sharepoint and Jira. I’m glad the concept has gotten so popular. And that’s a bit about what this post is about. I think it’s time to sunset the site.

Grids are gone

4 years later, I can’t remember the last time I saw a design grid being shared amongst designers. Either externally on social media, or internally in product design teams. It would seem that the concept has either been very successful or other factors like responsivie design itself have made it more clear than Gridless Design as a goal could have done alone. Maybe the popularity of Tailwind which doesn’t use a design grid was another facet. Even AI could have been a factor.

No matter the reason why the design grid has faded into the distance for digital design, that was the purpose for the site. It would seem it has fullfilled its purpose and now I can consider bringing it down.

While I’ve been writing the book about Mise en Mode, I’ve also considered what other topics would be good for a book. When I thought about Gridless Design being my first large work as a possibility, I considered how relevant it would be. This caused all of the reflection I’ve had in this post, which is leading me to this decision. Plus, it always helps to drop a domain that costs $50 per year from your account.

What’s next

Gridless Design isn’t going away completely. It’s clear that the resource has been helpful to some people over the past few years and it could continue to be helpful for folks in years to come. So, here’s the plan:

Finish the book.
Move & update the content to be hosted at one of my other main properties.
Update the site explaining the move, include the new link.
Let the site expire within the year after the site is updated.

Nothing is changing right now. The book is still the priority. Look out for the plan to take effect within the next year.

It’s been fun getting rid of grid with you.

Logical Optical

Thu, 27 Mar 2025 00:00:00 GMT

I got into an argument on LinkedIn this week about design choices. Very on brand for me. It started with this image:

The post was defending the choices made in the image, and went on to say that people who aren’t designers have no business questioning these decisions. The weird part about it was that this person wasn’t a designer according to their profile. Since they’ve blocked me from rebutting I can’t link to the post, but I want to take the opportunity to explain that I understand why the logo is not truly a circle, but I’m less convinced about the bar in the field.

The fallacy of optical alignment

Much of my research is uncovering why we make design decisions. This makes the decision repeatable by following some set of rules for when a new but understood pattern emerges. When it comes to optical alignment, there’s a large collection of articles made by designers who will explain that some shapes shouldn’t be mathematically centered, and instead should be “nudged” to make them look centered to the eye. I’ll be referencing some of the images from the very first post at the top of my search results for “optical alignment ui”.

This is what we have typically called “optical centering”. And the post above even includes the word “eyeballing”. Here’s an example from the post but is also found in many similar articles:

When we measure the sides of the icon in the middle, they don’t match. However, the icon looks like its centered in the middle of the container. Is this just how our eyes work? Are our eyes imperfect? No, you are still centering the icon. It’s just using a different center. In fact, the triangle is a great example of a shape that has lots of centers. Here’s an image from another post, which demonstrates how this would work in a circular container:

The post where that image is from also shows that the technique being described doesn’t necessarily work for all icons. All icons are not squares or triangles so how are we suppose to think of this? Let’s look at another example which is linked to optical alignment.

Area not dimension

Here’s another image from the first article:

The post explains that we need to increase the size of the circle because the square looks larger. However, the post doesn’t explain how much you are meant to increase it by. Is it until it LooksGood™? Even the post they’ve linked to doesn’t explain how to do it. The best suggestion is to blur the icon but that seems even less precise. So what’s the answer?

The visual weight looks different between the square and circle of the same height because they are different. What we actually want is shapes of a similar area. Here’s an image from another post that discusses optical alignment:

As you can see, we now have a repeatable process to help understand why the circle is larger. In fact, we have created tools to help us with this:

This is the keyline grid provided from Google’s Material Design documentation. That’s right, the guy who wrote Gridless Design is recommending a grid as a tool. This is used to help designers draw icons with a consistent size and alignment. There’s more detail about how to use this grid at the documentation page.

But let’s look deeper into this grid with our new found knowledge. Let’s measure the area of the main shapes provided by the grid. If we count the number of grid squares we should get an approximation for the area of the circle found within the keylines using the following formula for a circle:

$\pi r^2= \pi 100 \approx 314$

So 314 grid units is our approximation for the area of the circle. Now let’s check the area of the square found within the keylines:

$w^2= 18^2= 324$

Is this the best we can do for the grid? Let’s check where the width is a smaller or larger grid:

$w^2= 16^2= 256$

$w^2= 20^2= 400$

We can see that this is the closest we can get to have the circle and square match in area. Only off by about 10 grid units. With a higher fidelity grid, we could get even more precise. But the bottom line here is that we’re trying to make shapes of equal area when we are “optically” sizing these elements. That’s why this grid is recommended and why it works.

Math isn’t being thrown out the window in favor of design, most people are using the wrong math.

Circling back

Returning to the image that started it all. I’m not a typographer, so I’m under qualified to speak about how to adjust the G in the logo so it LooksGood™. And in reply to the post, I said that right now I’d chalk it up to pure brand personality. I have confidence there are qualities of typographic glyphs that follow some of the thinking I’ve demonstrated here but I don’t know precisely how they relate so I won’t comment on it now.

However, that bar in the search field. I can’t agree with that. And it’s true I’ve never noticed it before, and often times when I’m just navigating around a user-interface I don’t notice things that are off by a few pixels. This isn’t because I’m not a designer (though I do consider myself one), this is because I’m not spending the amount of time staring at a user interface decision to care about what went into it. Only unless it looks out of place while I’m using it does it catch my eye and these few pixels weren’t enough to stop me.

This describes one of the largest biases in our work, staring at it for too long. In the best case scenario, the user doesn’t remember anything about your work. They got the task done, and they moved on with life. The amount of time some of industry spends staring at the details can be wasteful in the grand opera of user experience. So if the space between top and bottom of this bar was deliberate, I’m not confident many people would have noticed unless you had the time to stare at it.

But since we’re looking at it, let’s talk about it. Or rather, let’s talk about another search bar that the original author shared in the comments: Atlassian’s search bar.

The original poster argued that if Atlassian is also misaligning their icons that it all must be some conspiricy against proper alignment techniques. That response is an exaggeration instead of taking a moment to think why they could have done this. Let’s look at a few things by making some lines and pixel measurements.

One of the first things we can see is that there is alignment. The team may have chose to align the icon to the baseline of the text. The next thing we can see is that it would seem that the text isn’t truly centered within the frame. Is that intentional? No, at least not in the way the web designers were expecting it to happen. We can see what’s happening when we inspect the box in devtools.

Measuring by eye in my editor isn’t getting me perfect results! What gives? This is most likely due to how the font sits within the line-height box. There’s a great post about this if you want to dive into it. But what’s most likely happening is that the font doesn’t sit in the vertical center of the 24px line height box, which causes the space on top to be larger than the bottom. If this was a custom font provided by Atlassian, they would be in control of how the font sits in this box. However, they’ve chosen to use ui-sans-serif which will use the current font of the operating system the user is using. So they have no real control about which font that is or how that font sits in the line height box.

Back to the icon, if we continue inspecting, we’ll find that the icon is not found within a perfect square even though the icon width and height are declared identically.

How could this be intentional if the size is declared as 24 but not rendering as 24? In my opinion, this wasn’t intentional. The fact is that the amount of difference between the rendering and the intented size is so slight that it wouldn’t matter to look into it further. The icon LooksGood™ so we ship it. In this case, it’s doing the job so it’s fine to move on to something else.

However, if they really wanted to make the icon a 24x24 square, it’s only a matter of adding flex-shrink: 0 to the direct child of the flex container holding the icon and the input elements. This is a common rule I tend to put on my icon elements when they appear in flex containers because they can be easily squished. The flex-shrink: 0 tells the <svg/> that it shouldn’t be affected by siblings that are growing to take up space.

As for centering to the baseline, this could be intentional or it could just be an artifact of the elements used to compose this component. The element being used to hold the icon is a <span/> element which is classified as an inline element so it behaves like text. This means its size can be affected by line height among other properties. If we were to change this to display: flex (or even inline-flex), then the box doesn’t behave like an inline element anymore because the flex algorithm takes precedence. Making that change, along with the earlier flex-shrink: 0 change on this element inside the current flex container set with align-items: center would vertically align the icon and text as best as the CSS algorithm can do.

Whether or not these decisions were deliberate or oversights, I can’t tell from the outside. Only the author of the component could disclose that. We’d always like to think these large companies are making choices intentionally but in reality there’s often so much going on with not enough resources that it’s often a matter of being good enough. I’ve found other areas where improvements could be made but you have to weigh the effort over the impact. Does it really matter if the icon isn’t perfectly centered? Will the user care or will it stop them from proceeding?

Space bar

So when it comes to the bar in the original image, my best guess there isn’t that it was planned to line up with the icons outside of the search bar, since that is against Gestalt’s law of proximity. It’s more likely that it was an unnoticed few pixels in an otherwise good enough to ship component. If they actually do line up with the icons outside, I think that’s more serendipitous than meticulous. Die-hard designers can justify this all they want with “known design principles” but I find understanding why to be more powerful and harder to refute. Since no one but the original implementer could tell us, all folks tend to do is assume that it was intentional because this is a big company. As we now know this doesn’t need to be the only story.

The point here is that you shouldn’t just take what other folks have said as gospel, especially in the case of design at large organizations. Challenging the norms is how we get innovation as long as we explain the reasoning behind what we do. When you explain those repeatable reasons, you are more likely to gain agreement than through trying to convey your feelings. The difficulty here is that we cannot itemize every single decision we make in design, especially in the production environments of building products. In many cases, we just need to get the proof of concept out the door and good enough for the next round of funding. That’s why we hear so many cases of poor accessibility, performance, and personalization in the majority of experiences. We have no time to explain why, it needs to be out yesterday. We have no time to fix it when we find out it could be improved, we have another priority. That gets repeated by other smaller organizations hoping that the big dogs did it well and that’s how we get bad patterns, like floating labels.

And when a design systems architect tells you they have experience in this topic, blocking them from the conversation really emphasizes how much your argument LooksGood™. 😏

Low inspectations

Wed, 01 Mar 2023 00:00:00 GMT

The design hand-off process is often troublesome because of intentions lost in translation. We’ve created expertise in this space between design and engineering to help smooth the exercise but we often try to find ways to bridge the gap without human intervention. One of these ways is generating resources to use from the design tool.

I saw a great Figma for developers video shared on social media last month. This is definitely a part of the role that isn’t often taught, leaving most engineers stumbling around the interface. There’s a lot of helpful points made in the short presentation but I need to be critical about one area in particular; the inspect panel.

Proceed with caution

I consider the inspect panel to be a trap. Admittedly, calling it a trap is dramatic but it’s also meant to warn folks who accept what the panel provides verbatim; possibly believing it’s the blessed approach. I’ll be referring to Figma’s inspect panel in the following examples as the most popular tool to date but any design tool feature that claims to output code should be treated with skepticism.

Coordinate system

Figma, like many design tools, place assets on a coordinate system. Elements are added to the artboard and positioned relatively to the top-left corner. This isn’t native to web layout, which works as a document where elements added are positioned relative to each other. DOM elements are situationally-aware of their ancestors and siblings to adjust their position. Could you change the positioning strategy for web elements? Yes, but you’ll have a much harder time getting them to be accessible and responsive when you break out of the native document flow. Until design tools present the web using native alignment, developers will be left to intepret what a fixed coordinate system should do within document flow. The auto-layout concepts gets us to begin crossing this bridge but we’re not entirely on the other side yet.

💡 Shy from properties that update or declare the explicit position of an element such as position, top, and left. Consider using modern CSS techniques like display: flex; to place the element in the preferred location. Work with the designer to learn about the intentions between different user and device preferences.

Hyper local font styles

Another feature of the web is that text styles cascade down to lower elements. You don’t need to explicitly provide the text styles at every bit of copy. Especially if you limit the number of fonts to improve performance. If you set the font styles for body copy on the <body/> element, you don’t need to reduplicate the font definition at the element which contains the copy. Unfortunately, Figma provides text styles for every individual bit of copy in the artboard. While you can be sure that this bit of text will get the styles when you copy from the inspect panel; you could optimize for less CSS by setting the appropriate style higher in the cascade. This is also great for when you need to update the font styles globally.

💡 Set the font properties higher up (like at the <body/>) to allow the natural cascade to inform lower elements. Only update the property at the location where it doesn’t match with the cascade.

Missing units

Figma and other design tools that claim they are for web design do not have web units. The rem unit is particularly important on the web, but other units like percentage are also valuable when communicating layouts. Just watch out for magic numbers. The inspect panel is notorious for displaying verbose width and height values in pixels. Expert CSS authors will tell you that applying these as given in your code is bad practice. We’d rather allow the content to dictate the size of the container or base the dimensions off of some other relative proportion so every container is flexible to any content.

💡 Ignore height and width properties when found and let the content determine how large the container should be. Consider max-width or max-height for large composition constraints. Work with the designer to determine what web units would work best in areas where they are needed. Avoid using pixels units for layout properties. Using pixels for decorative elements might be appropriate (ie. border-width).

Miscellaneous

box-sizing: Hopefully this is already found higher in the cascade and applied globally as border-box. This is what it should have been by default.
isolation: This property creates a new stacking context and you most likely won’t need to apply this property when you see it in the panel. For more information on stacking contexts and when they are helpful, I recommend Josh W. Comeau’s article.
order: This property should be avoided. While it can change the order of elements as they are displayed visually, the HTML won’t match. Change the layout order as HTML instead of this property.
overflow: You should reserve this property to create a scrollable containers. Setting overflow past this reason will cause clipping in containers and other side-effects; such as creating a new block-formatting context.
z-index: You should try to avoid setting this property, especially in the case of considering a larger elevation system where collisions are unavoidable. For more information on why z-index should be considered an escape-hatch, I recommend Josh W. Comeau’s article. Yes, I’ve linked it twice in one post; it’s that important.

Stop, collaborate, and listen

Ultimately, your developer should be empowered to provide feedback on the design. Likewise, the developer shouldn’t depend on what the expect panel presents as perfectly appropriate. There is an expertise in translation that must occur which only comes with practice and experience. Work together towards finding the best execution of the intended design. Dare I say, even include them in the process. This can be the start of a beautiful partnership.

Meaningless curves ahead

Tue, 07 Feb 2023 00:00:00 GMT

The tiered system of design tokens has been fairly well-established to include semantic tokens. Color, typography, and even spacing can be described through semantic means. This drives the question, how do we name other properties semantically to further describe a generic experience?

Nested rounding

This article at Cloud Four goes into the idea of nested rounding in detail. Essentially, we want the radius on rounded corners between nested elements to follow a shared focus (ie., center of a circle). The math is very simple, here it is using CSS notation:

.child {
    border-radius: calc(
        var(--ancestor-element-radius) - 
        var(--distance-from-ancestor)
    );
}

Ultimately, we’d like to think of rounding in terms of semantics. However, because we want the rounding to be derived from elements, we can avoid semantics entirely. In practice, the reason we might use semantics is when we have decisions to make that are more complicated than just on/off. Semantics are used to describe the why we chose this value from a plethora of other possible values. In our rounding treatment, we shouldn’t have more than one value. It should be a binary decision to include rounding or not and let other factors determine how round to achieve the nesting effect.

In other words, when curating an experience, we’d like to simply mark elements which should receive nested rounding. Later, we provide some themable amount used by the rounding calculation which affects the rounding of marked elements in a uniform manner. We do not prescribe the rounding amount at any one element explicitly, we simply expect the appropriate nested rounding to exist when turned on.

However, we have some problems to try and overcome.

Deriving values

The first problem is trying to get the --ancestor-element-radius and --distance-from-ancestor values for the formula. The ancestor part provides a clue to what makes this so difficult. The nested rounding calculation is dependent on the relationship between two elements. This is different from a semantic spacing approach as we only select a spacing token to convey a relationship. In the rounding formula, the final value is computed using the resulting relationship when the rounding is meant to be applied.

When trying to fill the --distance-from-ancestor value, it’s very likely that we will have several elements nested which may or may not include their own methods of supplying space. The properties of margin, padding, gap, and additional position and transform properties can all have a hand at visually presenting how far two elements are from each other, thereby making the --distance-from-ancestor value very challenging to determine.

Let’s assume we have a system which can readily provide the --distance-from-ancestor. The --ancestor-element-radius in a perfect system would also be derived by the formula. So where does the base radius come from that influences all other nested rounding? Would it make sense for the <body/> to declare the first amount of rounding? Conceptually this seems incorrect since we don’t expect the <body/> element to have rounding at all. Though, we can simply choose not to apply rounding at the <body/> and rather only define the value here.

Another problem with starting from the top would be that some elements would never receive rounding. If you have a button which expects rounding to appear in two different places, it is possible that they receive different rounding amounts based on how many nested ancestors are marked for rounding between them. This could cause the same button to look different just by its placement within the layout.

So, instead of starting at the top, could we start at the bottom? That is, could we declare what the smallest rounding is and then have marked ancestor elements use that value? After all, the center of the radius that determines the rounding must exist inside this element. Perhaps a new calculation would look like this:

.parent {
    border-radius: calc(
        var(--deepest-element-radius) + 
        var(--distance-from-deepest)
    );
}

In this way, the --deepest-element-radius can now be a fixed number, provided by a theme because there should be no smaller rounding applied. All rounding that occurs above this element is derived from this base amount. For the purposes of our exploration, let’s call these deepest elements the rounding focus, as they possess the center which all ancestor element rounding radii would be computed in this system.

The logic within marked ancestor elements would identify their deepest rounding focus and calculate the distance between their bounding boxes to determine the --distance-from-ancestor. We already know the difficulties in attempting this from above, but let’s continue assuming we have a system in place which can prescribe the distance somehow.

Existential crisis

In explaining the logic to calculate the ancestor’s rounding, I simplified the approach dramatically. In reality there’s dozens of considerations that we’d need to account for. One of the largest problems returns back to rounding determined by an element’s existence.

Imagine we have a card layout and all cards are marked to include rounding but no cards include any elements which initiate rounding; our “rounding focus” elements. This would mean that none of the cards have rounded corners. When we add our rounded button to one of the cards, rounding would exist only on that card.

If you’re thinking we could include a “virtual” rounding focus, a hidden element which triggers rounding, how do we allow the ancestors to measure the distance between edges? It’s possible the cards’ internal structures are completely different between them, making the rounding varied as well. What would be more desirable is for all sibling cards have the same rounding, whether they have a rounding focus or not. Except we’ve already determined that nested rounding is only determined between an element and ancestor, not from siblings. Do we then have further markings for rounded siblings to share values? Which sibling rounding takes priority?

We’re not done with problems. If we put the rounding focus element within the card, what distance should we measure? We could take the shortest distance and apply to all corners. However, what happens if we position that button in the center of the card; does the card become a circle because the button is positioned so far from the edges? Ok, perhaps we can set limits on the rounding using max(). But then if this hits the max, outer marked elements would get the same max radius thereby breaking the nesting effect.

Level headed

At this point you might ask why we haven’t done what has been before; create levels of rounding. Since we don’t need to be semantic, maybe this becomes a viable option?

Let’s say we start at the base level again with a rounded button, then we have a card component which gets the next level up. What happens when we include a rounded input with a rounded button inside? We would need to insert a rounding level in between. The loom of insertion is the biggest drawback using levels. How could we possibly account for all the layout nesting configurations which may be rounded to avoid levels being added or orphaned?

At this point we’re really more in search of a layout system than just a rounding system. Prescribing layouts could warrant the possibility of informing how round parts should be due to restrictions set by components of the system. We could know exactly what elements exist and the amount of space between them. Creating a robust layout system is outside the scope of this exploration since that would attempt to define all possible layouts for any hypothetical experience; a monumental task.

So for the moment, I don’t believe there’s any possibility of a semantic nested rounding system due to the natural dependencies on existing elements. We’re unfortunately stuck with a more meaningless system which can provide few nesting effects for curated components.

But maybe that’s the point. Other properties are decided in an experience based on qualities like feedback, hierarchy, and relationship:

The color orange often indicates a warning.
Large text can support a section outline heading.
Less space between items means they are related.

If this isn’t branding, what information does corner rounding convey past being round? Goose egg 🥚.

Minefield Context Protocol

Wed, 26 Nov 2025 00:00:00 GMT

AI is everywhere in tech now. It is in the tools we use, the products we build, and the way we interact with users. It feels like if you aren’t with AI, you are behind. While there’s plenty of questionable AI use, one thing is for sure: AI is making waves. And it’s really hard to keep up with the latest.

One of the concepts that are gaining lots of discussion is the “MCP” which stands for Model Context Protocol. Anytime I’d ask what an MCP is, I’d usually hear it described as an API. So then, why isn’t it just called an API? Because it’s not really an API. Sound confusing? You bet!

Just like how I learned to code from actually building something. I decided if I was going to truly learn what this thing was, I’d have to build one. So I did and this is how that went.

If this sounds familiar to you, I did speak about this on Wireframe on Monday. You can think of this as the accompanying blog post. If you prefer listening to what I went through to make this, go ahead and click the link.

You have too much stuff

Some of the feedback that I get from folks who follow my work is that I do too many things. It’s hard to keep track of my latest research findings or development projects. Even my wife who works in the same field and lives under the same roof has trouble keeping up with my work. On top of this, much of my work is very abstract and hypothetical. It makes it hard to fully apply my work into real world scenarios without understanding all of the research behind it. Not to mention all the other factors that could contribute to friction in the implementation.

So what if there was one place to learn about my work conveyed in a approachable way? Some way that you could learn about my work within the context of your own work? That’s what I set out to build, my own MCP server that aggregates my work and research findings into a single place.

To do this, I needed two major units of work. I needed an MCP server to connect with MCP clients and I needed the server to fetch data from my domains in a way helpful for these systems to comphrehend.

End-domain data

First, I wanted each of my end-domains: my personal site, the blog, and my design system to expose their data in a structured way. It was important to me that I’d follow some acceptabled standards for exposing this data. My thought was that I wanted these sites to opt-in for AI discovery.

The way I found to do this is with using a llms.txt file which has an emerging standard. This file is like a sitemap but for AI. The content is actually markdown. Here’s a sample:

# Title

> Optional description goes here

Optional details go here

## Section name

- [Link title](https://link_url): Optional link details

## Optional

- [Link title](https://link_url)

Importantly, the links found in the file that go to content should also be markdown files. That means my site needed to serve not just the HTML pages, but also the Markdown source files. This way, the MCP server could fetch the raw content and parse it for AI consumption.

For my personal site and the blog, this was fairly straightfoward because they are both written in Markdown and rendering that as raw text is a few lines of code for a [slug].md.js file:

import { getCollection } from 'astro:content';

export async function getStaticPaths() {
    const entries = await getCollection('posts');
    return entries.map((entry) => {
        return {
            params: { slug: entry.id },
            props: { entry },
        }
    });
}

export async function GET({ props }) {
    return new Response(props.entry.body, {
        status: 200,
        headers: { 'Content-Type': 'text/plain; charset=utf-8' }
    });
}

The real problem was Storybook. Since the source for the files there are written in stories.tsx files, it’s not a simple 1:1 translation. Admittedly, I vibe-coded the solution to this and wound up with nearly 1000 lines of code. Luckily, my system is open-source so you can grab this and remix it how you like for your own purposes.

The script does a few things:

Finds all the stories.tsx files in the src/components directory.
Parses the file to extract JSDoc, component category and name, and stories.
Determines the props from the imported component type definition.
Renders component stories as JSX instead of the less useful Story source.
Generates a Markdown file for each component and a llms.txt file with all of the components.

With this in place, all of my end-domains are now exposing their data in a structured way for AI discovery and consumption.

The MCP server

My MCP server is a very simple Netlify project. It was heavily inspired by this guide on Netlify. Much of the scaffolding is the same except registering tools and resources which is the main difference.

Resources & Tools

When I went into this project, I was under the impression that everything I was going to offer from this server would have been resources. Resources are basically static files that the server can provide. It’s like requesting a library book. You receive the book with no modifications to the content, just as it is.

For resources there’s two actions that clients need to accept: list resources and get resource. List resources is telling the client what is available, and get resource is fetching the content of a resource. This maps 1:1 to what was created at the end-domains earlier. The llms.txt is the list of resources, while each of the Markdown files is a get. The slightly annoying thing is that we need to transform the llms.txt Markdown into structured data. While I made my own using the Markdown AST tools, there seems to be a newly created package that might help in the parsing. Though I take pause to it not having a link to the source to know what it is doing.

Once you have it parsed, you can register each as a resource. For my MCP, I wanted the resources to have the following URI structure:

subdomain://category/slug

The MCP specification allow you to make up your own URI scheme and my sites generally follow this shallow pattern. This is a resource URI meant for the server to use internally to look up its resources. Then you can use the official MCP Typescript SDK to register the resource template assuming you have LIST_RESOURCES_META to configure the resource and a function listResources() to handle the fetching:

server.registerResource(
    'resources',
    new ResourceTemplate('{subdomain}://{category}/{slug}', { list: undefined }),
    LIST_RESOURCES_META,
    listResources
);

The thing that bothered me is that { list: undefined } setting. It was unclear what the purpose of that was, and after some vibe-coding sessions, Claude suggested I use the server.setRequestHandler() method to define resources. So, if you’re building something similar, you might want that method over the helper methods found prominently in the README.md for the SDK. Especially since my resources are dynamic; they don’t truly exist on the server.

A gotcha here is that some MCP clients, systems that speak to MCP servers, don’t support reading resources. They need a tool to access the resources. So, that required that I include tools. Tools is fancy word for something that can process data. Generally we’d think of something like a POST request for an API. In this case, in order for some clients to access the resources, I needed to create a pathway for them to make the request. For my system, it was recommended to use the server.setRequestHandler() again, but as per the README.md, registering a tool is done like this, assuming you have a GET_RESOURCE_META to configure the tool and a function getResource() to perform the lookup:

server.registerTool(
    'get_resource',
    GET_RESOURCE_META,
    getResource
);

STDIO vs HTTPS

Another thing that was being thrown around as common knowledge was MCP servers and clients having better support for STDIO over HTTPS. Because I program primarily on the web, I didn’t know what STDIO was. I just thought it was some other way of making the same server. In reality, STDIO is a way of identifying a MCP server than is meant to be installed locally on a persons computer. The HTTPS MCP server is a more recent development, which explains why I found it really hard to develop and test. My way of testing was just pushing the server up and hitting it in Cursor to see if I could connect and have it respond. Definitely not scalable, and I hope there’s better tools out there that can help in this area. The Netlify article speaks about making a hybrid server, and there’s something called MCP Bundles that could be cool to try. Though I prefer the HTTP version. I find hitting a URL much easier than downloading and installing something.

What now?

The server is located at mcp.damato.design and the homepage has instructions on how you can add it to your MCP client of choice. This helps show my aptitude with AI technologies, while providing access to my research in a contextual way. It was filled with areas of my own learning and seeing all of the gotchas and missing standards shows how much people are still trying to figure all of this out. It was effectively a weekend project, and something you might want to consider trying to keep your skills in the game. Happy vibing?

Mixinimation

Thu, 30 Jan 2025 00:00:00 GMT

In speaking with a colleague, we were discussing solutions for people who were unable to use a framework’s custom component that still expected to have the styles for that component. Think of how you might have a React <Button/> that would need to be visually similar to some static HTML page <button/>.

Folks writing CSS normally should quickly identify that placing all of the necessary styles under a single identifiable selector that can be applied to the element is the normal way of getting the job done.

.my-button {
    /** Reusable styles for the button here */
}

<button class="my-button">Click me</button>

This assumes that the styles for .my-button are found on the same page as the HTML <button class="my-button"/>. This is a reasonable method for having reusable styles.

But maybe you don’t have the ability to update the HTML, how would you change the CSS such that the buttons would receive the styles? What you should first land on is updating the selector to be more generic:

button {
    /** Reusable styles for the button here */
}

However, it’s possible that we don’t want to affect all buttons this way. Specifically, we want to have some reusable styles that are written for the common <Button/> component, but we also want to take those same styles and create a new stylesheet specific for when we can’t access the HTML. In other words, we don’t want to write the same styles twice, but we do want to change what those styles target. How could we do this?

If you’re familiar with the CSS tooling ecosystem, you might suggest using a @mixin syntax made popular by Sass. That will allow the styles to be written once, and be reused underneath different selectors.

@mixin my-button {
    /** Reusable styles for the button here */
}

/** In the <Button/> component styles */
.my-button {
    @include my-button;
}

/** In the restricted HTML styles */
button {
    @include my-button;
}

Unfortunately, this is not native CSS syntax yet. So, this assumes that you are using a preprocessor to transform the @mixin syntax into native CSS that the browser can parse. Though, I was curious; is there a way we can get mixin behavior in CSS today? And I think there is…

Keyframes

The @keyframes syntax is a method to add a collection of styles to an element. Typically, we’d define blocks of declarations for each point in the keyframe timeline. We could define all of these styles as the from and to points, causing these styles to be applied for the entire duration of the animation.

@keyframes mixin-button {
    from, to { /** Reusable styles */ }
}

Next, we can write the animation value as the following:

.my-button {
    animation: mixin-button 0.001ms forwards;
}

The animation shorthand has three values. The first is the animation-name value which refers to the @keyframes name set earlier. The next is the animation-duration which cannot be 0, the default. Setting to a very small value causes the animation to be nearly immediate. The animation-fill-mode is set to forwards to ensure that the styles provided by the animation continue past the end of the animation so they persist after the very short duration.

Now remembering to write those three values in the shorthand can be a bit cumbersome, so instead we can hide all of this in a CSS custom property.

@property --mixin-button {
  syntax: "*";
  inherits: false;
  initial-value: mixin-button 0.001ms forwards;
}

This allows us to use the following syntax to apply all of the styles using a single property-value pair under a selector.

/** In the <Button/> component styles */
.my-button {
    animation: var(--mixin-button);
}

/** In the restricted HTML styles */
button {
    animation: var(--mixin-button);
}

Here’s the whole implementation working in Codepen:

See the Pen Mixinimation by Donnie D’Amato (@fauxserious) on CodePen.

<Laughs maniacally into his computer>

Drawbacks

Ignoring the hacky nature of applying all the styles by hiding them underneath the animation property, one drawback to this will also be where actual animations would be expected for these elements. While there is a syntax to apply multiple animations to a single element, I’m not sure how these might conflict. Additionally, if you are using a node detection script, the animation would fire for all of these elements if listening for animations.

My recommendation: try it out, put it in the dark corner of your toolbox but, avoid reaching for this unless you really have challenging constraints. We’re all waiting patiently for more native solutions and with CSS moving fast, it’ll be here sooner than we realize.

My Top 4

Fri, 15 Aug 2025 00:00:00 GMT

For a recent episode of wireframe, I borrowed some questions from another person’s AMA. Overall, good questions but one of them stuck out to me where I wanted to give it more thought:

You are asked to build a website but you can use only 4 CSS properties, what are those?

It’s clear to me that you’d have to think strategically about this. While I’d say that something like display is super powerful, it also often requires additional properties to make things behave afterward. So, the key is to think of properties that stand on their own and can have some significant impact once used. Additionally, it’s pretty clear what we’re going to be working on is a Craiglist-like design since I can’t use a lot of properties for aesthetic purposes.

Without further ado, here’s my picks:

`overflow-wrap`

This might be a property you aren’t using but I truly believe it should be in people’s resets. Specifically overflow-wrap: break-word. This ensures that long text such as URLs don’t break out of their containers. While it’s possible you might not need it on your site today, you’ll probably want to have it for the future.

`max-width`

The prime example I’m thinking of is <img> elements rendering as larger than their container. Setting max-width: 100% on these, along with other similar elements will help ensure that they don’t break layouts. This would also be helpful to keep long lines of text from occuring for readability. Even if the content itself might not be centered nicely on the page without something like margin-inline: auto.

`margin`

Speaking of margin, I’m adding it to my list. Between the ability to horizontally center content and some of the egregious values set in browser defaults, having this will really clean up the overall hierarchy and presentation of a page. The use of the shorthand values will help here so that I can get horizontal centering with margin: 0 auto and fix defaults with margin: 0 0 8px.

`scroll-behavior`

The reason I’m adding this, specifically scroll-behavior: smooth, is for hash routing on links. For example, when I’m reading working group specifications and click a link, it often jumps somewhere making it really hard to know if I was navigated to another page or where this next section is relative to the old section I was just looking at. Smoothly scrolling after clicking the link makes the relationship more clear. Importantly, this would need to be inside of a @media (prefers-reduced-motion) rule to be ignored for folks who are sensitive to motion. So, it’s possible my fourth rule could be wasted because of this.

I made a quick sample page to demonstrate the usage.

See the Pen Untitled by Donnie D’Amato (@fauxserious) on CodePen.

What are your top 4? 🤔

No more modals

Sun, 05 Jun 2022 00:00:00 GMT

Have you ever landed on a web page and have it immediately ask you for a location? How about while you are reading an article and, after you scroll down to read more, you get an advertisement covering your next paragraph? These are super annoying patterns but why are they annoying?

Surprising popups

When a user has a specific goal in mind and an interruption occurs, the user will find it annoying if that interruption does not relate to their current workflow. This can be expanded to any generic UX pattern; where expectations aren’t met and frustration increases. However, there is a special place for popups because they interrupt.

There is a fine line between the popup and the modal. The modal must be related to the user’s current workflow. This means that the user triggered this popup and it meets the user’s expectations.

The designer could choose a modal to interrupt the user (as all popups do) and cause the user to slow down for some important information in order to proceed. A good example is the destructive confirmation modal which helps ensure that the delete button press was intended. The user is expected to do a bit more work here so important data isn’t erased. So, the designer requires one more hit target to be pressed before continuing. The modal here also shows that the user can return to the original state just behind the message and that nothing has changed yet.

Along with this previous idea, another valid reason to provide a modal is to show the user that they are still within the current context. A good example here is adding an image to a blog post. It would be more helpful to show that the user’s content remains while completing a new task of selecting an asset from the gallery. If we were to provide a new page for this experience, the user would not be confident that their content was saved. Showing that their content is persistent behind the modal establishes trust that the user will return as they once left.

So to recap, you may consider using a modal:

if you believe the user must slow down before continuing the current task.
if you believe the user does not trust that current changes will persist while they need to complete a different but related task.

Questionable practices

I’ve seen dozens of workflows using a modal which could have been another pattern entirely:

If the user could return to the experience using a url; the experience should probably be a new page.
If the user needs to create or edit an entity with many fields (eg.: a profile, a product); the experience should probably be a new page or incorporated into the current experience.
If the user needs to edit a value; the experience should probably be incorporated into the current experience.

An example that I’ve seen recently is a profile review experience. Once clicking your avatar in the application a modal appears above your current workflow. From here you can edit fields and save to return. However, you may also change your avatar photo. After selecting a photo, you are presented another modal allowing the user to resize the photo and save the changes, returning you to the previous modal. So how could this experience be redesigned?

First, clicking on your profile should navigate the user to their profile. We expect this to be a url and therefore a new page. From here, the user is given several fields of values they can edit directly. Let’s continue with this pattern by allowing the user to edit their avatar here as well. Use a slider to resize and drag-and-drop to reposition the photo in the thumbnail. The profile would hold the original image and on save, it would provide an avatar sized adjustment of that original for use across the site. We’ve taken a multi-modal experience to a zero-modal one.

Let’s be clear here, I’m not recommending to remove all modals from experiences. As mentioned above, if the user was able to delete their profile, a modal confirming the action would be helpful for the reasons stated above. Although even this could be avoided by requiring the user type a word or phrase into a field before executing the destructive action. It shows deliberate intent over accidental button clicks.

It’s common to find modals used to login or signup. Consider using a separate page unless you allow the user to make customizations before creating an account. In this case, you’ll consider using a modal to show unauthenticated progress is maintained while they complete the signup process. Make sure the signup process is reduced down to the essential fields. Allow the user to include additional information later in their profile.

NN/Group also provides a few additional recommendations for when to use modals. One of the examples is a wizard which breaks down a complicated workflow into steps. What’s important here is the second paragraph:

However, it’s important to note that a modal with multiple steps will just prolong the amount of time spent away from the main tasks, making it more likely that users will forget what they were doing in the first place.

— https://www.nngroup.com/articles/modal-nonmodal-dialog

In my opinion this describes that we shouldn’t be using a modal for wizards and instead provide a navigational pattern linking to pages sequentially; allowing the user to return to steps easily. This is also relevant to their following comment about lessening a user’s effort. The point of designing an experience is to do just that. So, asking if the user is working with an agent could be a question exposed as a checkbox while filling out the form for a open house. That selection could be saved for subsequent open house requests. This simplifies the experience instead of disrupting the user with a question the system forgot to ask when it was more relevant.

Speaking of the real estate industry, many web sites of this genre use a lightbox (ie. a carousel in a modal) due to the need for viewing a set of high quality images of a property. Without diving too deeply into the decision to use a carousel, the decision to use a modal is debateable. Full screen images could be provided as separate urls; making the photos easily sharable to other interested parties. Closing the experience could return the user back to the listing; just like a close button would. Browser navigation could also assist in wayfinding between photos and the original listing along with common carousel-like controls.

Accessibility

Attempting to make a modal fully accessible is a serious challenge. For example, you’ll need to indicate that a new area of the page has been created, and focus must enter this area and be trapped for the duration of the experience until the task is complete. At which point, focus must return to the initial trigger of the modal. What actually receives focus (a child of the modal or the modal itself) is actually up for debate; making a recommendation for it unclear. Additionally, events should not occur behind the modal which is easier said than done. Even with the new inert attribute, ensuring that other elements are still accessible could be tricky with the introduction of third-party resources that need events outside of the modal.

As you might imagine, things become increasing difficult with more modals added to the experience. How to juggle focus? What the screen reader should announce? How to navigate between these popups?

Even the native <dialog/> element isn’t shipped fully accessible. At the moment, we can’t even trust the browsers to support accessibility like other elements do. There’s no avoiding some amount of custom behavior which is bound to have variations of approach and unintended feature gaps.

As a design constraint

The modal should not live at the top of the designer’s toolbox. Make it a design constraint instead. Explore possible workflows without the modal and see how far you can get. I have confidence that most experiences can avoid the modal pattern for something more useful.

It’s important to truly design with emphathy when crafting an experience. Perhaps, we should provide a double confirmation pattern before choosing some design directions? Imagine that!

On being extra

Wed, 29 May 2024 00:00:00 GMT

While I don’t recommend scales within the semantic set, it could be helpful in your primitives. One way of providing a scale is through something called “T-shirt sizing”. In this method, each size is provided in a similar way to how you might find sizes of clothing in a store. You might choose this type of scale when you expect the middle value to be the default and have values exist in opposite directions. In other words, you’d start with medium or md, and then have a smaller value represented with small or sm and a larger value represented with large or lg.

The T-shirt sizing scale is most frequently found describing space. In fact, I mention it as a direction within Gridless Design. While I have discovered a more semantic method of applying space since then, the T-shirt sizing approach remains popular and is appropriate for primitive token sets most certainly.

In seeing folks demonstrate their T-shirt sizing scale, one thing irks me. It’s about how people handle being “extra”.

Growing badly

Certainly, your scale will most likely exist to have more than 3 sizes, and when that occurs this extends into “extra” territory. In other words, you’ll begin to have values for xs and xl to go out from either direction of small and large. So far, so good. But if you extend one more step in either direction, you’ll begin to see and example like this: xxs.

Certainly, the expectation is that this is “extra extra small” or “double X S”. The problem is more apparent as you include more sizes, you’ll get xxxs and xxxxs; the representation becomes longer with each size.

The fix for this is very simple, use a number to indicate the number of X’s, so for xxxxs, you’d replace with 4xs. In this way, you aren’t repeating the character which increase the length of the representation. It is also more clear how many X’s in the name instead of needing to count at larger amounts. Of course, this goes for the xl direction too.

Considerations

So why aren’t people doing this? I’m going to make some assumptions.

Perhaps there is a constraint that the representation must start with an alpha character. For example, HTML id attributes should start with an alpha character, and Javascript variables also cannot start with a number.

If this is the case, then you can do one of two things. You could flip the X and number which would create x2l. This is most likely less clear what it is meant to convey but it does keep the number of characters low if that is beneficial in some way. The other option is to prefix with alpha characters like a namespace. size-2xl is more readable but longer if that is critical. I’d imagine the latter is more appropriate, as this also indicates what set this representation is meant to be included within.

Another possiblity is that the number suggests a relationship within the value. A person might perceive that 2xl is twice as large as xl which may not be the case. The relationship is more ambiguous when numbers aren’t included. I’m not confident this is the perception, as we don’t commonly assume that color-red-200 is “twice as red” than color-red-100. Though the mental model is wholly different in comparing color to size. Doubling color isn’t an exercise we normally consider, but doubling an amount of space would be.

And finally, the good ol’ Bandwagon Effect. Some team copied another system that looked good enough and wound up with a scale that could have been improved but, due to lack of resources, was never corrected. The team is now stuck smashing that X key until the correct value is set.

Is this nitpicky? Maybe. But I also think it’s an easy win to make a small part of the system more maintainable and easily referrable. If you’re considering T-shirt sizing in your system, then I highly recommend representing the extraness with numbers over excess Xs.

XOXO 😊

Ondark virus

Thu, 12 Jan 2023 00:00:00 GMT

The “ondark” virus is infecting token names in the design systems community everywhere. I’ve tried providing recommendations in token related posts and replies before. However, it seems this approach is becoming more wide-spread so I want to give it one final try to describe the problem with this naming scheme and provide some help with prevention.

This isn’t about what a token name should include, it’s about what it shouldn’t.

Prognosis

Imagine you have a UI which is primarily light colored. Perhaps a white background with nearly black text. There’s a section in this UI that you want to have a stark contrast with the rest of the page. In this section, you have some text lockup and a call-to-action button. The button has all the same properties that other buttons in the system have, except it’s located on this dark background.

Most folks might have a button prepared specifically for this scenario. We might even provide a configuration for when this happens in code. Under the hood, that might reference different tokens which point to specific ondark values sent to the page.

See the Pen ondark by Donnie D’Amato (@fauxserious) on CodePen.

This works fine for this section which covers just the background, text, and button.

Soon after, a request comes in to show a comparison table in this area; showcasing the benefits of the product of feature. In the current system, you’d need tokens to describe all of the borders of the table. Maybe you have something generic that targets borders in this area. But unfortunately, you might see a problem begin to appear.

The problem is that for every UI element that might appear in this section in the future, you’d need to define an entirely new set of tokens to describe the color for that UI. This is especially exhausting since you’ve already defined tokens semantically for all of these things in the “default” environment. To fully cover the dark area, you’d need to double the amount of token names to include the additional “ondark” (or “inverse”, “reverse”, “contrast”) infix.

No bueno.

Remedy

Semantic tokens

The first step is fully investing in semantic tokens. I’ve called them “intents” in the past to further enforce the expectation that the name describes purpose over value. We’re talking about token names like --button-background or --input-focused-critical-border-color which give information about the component or pattern and the property being influenced. In no way does it give any information about what the value of this color is. The more you avoid encoding the value in the name, the more flexible your system will be with the opportunity for that color to change in the future.

This extends to any token; describe the purpose and avoid the value when naming.

Scoped themes

A theme is the collection of values assigned to semantic tokens. The semantic tokens are a contract that should have permanence and meet expectations of folks building UI over time. These are the tokens that appear on the left-side of a theme. The values that would appear on the right-side can and should have a separate stakeholder, most likely one that represents a brand. I recommend avoiding managing both sides if possible to not introduce subjective bias or confusion in token naming.

I cannot stress enough, how values are assigned on the right-side does not matter. Values can be referenced, hard-coded, computed, or otherwise because they should never be used directly within the UI. A color palette is influenced by the brand and determines what --brand-blue-500 means. Here, the brand is responsible for curating the right-side values and how they are finally assigned to the left-side.

The design system team is responsible for maintaining consistency on the left-side; that’s it. They should only focus on the semantic token names for those values to be assigned and how they might support describing the experience at scale.

Now for the key insight — instead of the dark area and the light colored page needing to be informed by a single theme, think of the dark area as an entirely separate theme. In this way, the values that represent --button-background can change depending on scope.

See the Pen ondark by Donnie D’Amato (@fauxserious) on CodePen.

No additional configuration at the component level. You don’t need to remember or even know that this button is on a “dark” surface.
No additional token names. Self explanatory, naming is hard and scaling those names is even harder.

Now the only name you need is the one describing the theme; “dark”.

Prescription

This still requires the design token values to be curated to account for a dark UI. If you worried about defining an entire new theme worth of tokens, start small. Only define the ones you need at first; maybe background, text and button. At some point you might have the resources to define it all and then you’ll have an entire new theme to try.

I’ve considered going farther, specifically with surfaces that expect to demonstrate feedback (eg., warning banner). You might imagine this banner similar to the dark section above with a text lockup and action to take. I say if you have the resources to prepare this as a theme, go for it! You’ll be better prepared for when code samples might appear within the notification. Otherwise, you’ll need to be highly restrictive to the kinds of content that appear within various colored surfaces. And we all know how much designers love restrictions. 😉

It’s possible to over compensate. As an example I wouldn’t recommend creating a separate theme for inline feedback elements. Badges, notification dots, and error text can and should also be handled semantically inside a normal theme. Just think of a newsletter signup in a dark section; it should have an error message if the input isn’t valid. If you think in surfaces, like a sub-artboard, then you’ll better identify when a scoped theme would help.

This new recommendation also requires that the system delivering themes be flexible enough to request more than one. I think there’s an opportunity for some optimization here as well; where we statically analyze the page for tokens used within scopes and only serve what’s needed. However, to start you could just import the theme when a scope is added. The benefit of this is if the scoped theme hasn’t been included or the scope hasn’t been applied, it’ll fallback to the base theme values instead.

<body>
    <button>This button has a black background</button>
    <section data-theme="dark">
        <!-- Missing definition for the dark theme, 
        everything here inherits from the light theme -->
        <button>This button has a black background</button>
    </section>
</body>

Recovery

If you’re already using the “ondark” naming convention, it’ll be hard to move to this new system. That goes for any semantic token that was expected for public use. Deprecating tokens at the semantic tier is very difficult because they could be used anywhere across the platform.

Luckily there’s a path forward:

First, you can setup the scopes and apply within the UI in the appropriate locations, making note of the UI elements that exist in those locations.
Then define the values for those themes, perhaps reading from the “ondark” values.
Start serving those themes to the pages, which will be inert at first because no UI elements should reference the tokens.
Finally, either remove the component configuration that applies the dark theme or remove the “ondark” token assignments for the more generic tokens.
You can now safely remove the “ondark” token virus from your system.

I wish you best of luck in your path toward recovery.

EDIT (2023-01-12): Dave posted a great question as a follow-up and it deserves addressing.

I’m curious how you would accommodate session-level Dark Mode? Does the hero theme stay dark, or maybe sub-themes like data-theme='inverted'

— Dave DeSandro

My reply was half-joking but in seriousness, the answer is to continue leaning into semantic naming at the scope level. For the purposes of this demonstration, it was more helpful to use the word “dark” to further cement what was happening within the scope. In practice, the scope should be described with some meaning or purpose for the change in scope over expected appearance. For the examples above, the “light” theme could instead be the “base” theme as it is meant to be the default. The “dark” theme could be “feature” theme as it is meant to highlight features (in our examples).

<body data-theme="base">
    <button>Login</button>
    <section data-theme="feature">
        <button>Click here</button>
    </section>
</body>

This way user preferences could be read to determine what values are applied to which scope.

/* no-preference */
[data-theme="base"] {
  /* light colored assignments */
}

[data-theme="feature"] {
  /* dark colored assignments */
}


@media (prefers-color-scheme: light) {
  [data-theme="base"] {
    /* light colored assignments */
  }

  [data-theme="feature"] {
    /* slight contrast to light assignments as needed */
  }
}

@media (prefers-color-scheme: dark) {
  [data-theme="base"] {
    /* dark colored assignments */
  }

  [data-theme="feature"] {
    /* slight contrast to dark assignments as needed */
  }
}

If you want to be more efficient, only serve the user-preference when it is set.

<!-- first stylesheet is no-preference -->
<link href="default.css" rel="stylesheet" />
<link href="light.css" rel="stylesheet" media="(prefers-color-scheme: light)" />
<link href="dark.css" rel="stylesheet" media="(prefers-color-scheme: dark)" />

As you can see, things get complicated when you are including user preference alongside the scoped themes but “ondark” is definitely not solving this. For scoped themes, it’s complex but not impossible. During the first pass, I recommend leaving user preference out to keep the execution simple but plan for it in a future implementation.

If it was only as easy as body { filter: invert(1); }!

Out of order

Wed, 16 Apr 2025 00:00:00 GMT

As someone who like to think he deeply understands the CSS I’m writing, I do everything I can to avoid using CSS that can cause unintended side effects. As an example, for my new personal website, I use z-index once to handle the page tearing animation. Trying to manipulate the order of things using CSS can seem reasonable at first but often has hidden problems that you might not notice. I’d like to outline some of those problems here.

Who’s on first?

Let’s say we have a dropdown component which produces some sort of flyout experience. We believe that setting some high z-index value will ensure that it is always on top of the content:

.dropdown {
    z-index: 100;
}

Then, when we create the modal component, we set it as a higher z-index because it is meant to be disruptive and on top of everything:

.modal {
    z-index: 200;
}

The question here is, what happens when the dropdown component is meant to be part of the modal composition? For example, perhaps you need to select from a large list of options within the modal. In the current setup, the flyout could appear underneath the modal because the z-index value for the dropdown is lower than the modal.

Now, when many folks find this problem, they start adding exceptions. Ok when this specific dropdown appears, we’re going to increase the z-index:

.dropdown.but-only-this-one {
    z-index: 300;
}

Sure, this could work. But then when large teams are trying to use these components it turns into a priority war. With more things that are meant to appear on top of each other, it becomes less clear which items are more important at which times. Everyone thinks their use is the exception to the rule and then no system truly exists.

Some design systems took Material’s guidelines for elevation and turned them into design tokens for z-index. Unfortunately, based on my example above, this doesn’t work. It’s possible that your tooltip is meant to appear in a modal, causing its z-index number to increase.

So what’s the solution? Avoid using z-index altogether.

When you start working with the position property, and then try reordering the elements, you should notice a certain quality. Having nothing else set, the order that the elements appear matches the DOM order. In other words, later elements will appear on top of elements that come before. In the following example, try rearranging the HTML elements without touching the CSS.

See the Pen Positioning by Donnie D’Amato (@fauxserious) on CodePen.

Notice that whatever box is rendered last, is the box that appears on top of the others. This means if we want things to appear on top of other things, we should be rendering them last in the DOM order.

In fact, this is exactly how the new top-layer works in the DOM. The top-layer is exactly what it sounds like, it is a layer that exists on top of everything else in the page. That means even trying to set z-index: Infinity will not work here. Speaking of z-index, that doesn’t work on elements in this layer either. The only way to affect the order of elements here is by DOM order. The last rendered element in the layer is the element that appears on top. If you want something to be on top of that, you’ll need to append it to the layer.

Inset fill

But, let’s say you don’t need to do any flyouts or disruptions (good!). You want to do something more simple like have an element fill a container without itself contributing to the size of the container. Traditionally, we’d use the inset fill technique to do this.

.parent {
    position: relative;
}

.child {
    position: absolute;
    inset: 0; /* same as setting top, left, bottom, right all to 0 */
}

This was very common when we needed maintain the aspect ratio for media by using the padding hack. While we don’t need that specific hack any longer, there’s still use-cases for making an element fill a parent container. In those cases, I still recommend avoiding the use of z-index by making the element to appear on top last in the DOM order. But I’d also recommend avoiding the position property altogether.

Josh Comeau has a great post about stacking contexts that you should absolutely read. But the tl;dr is that using position creates a stacking context. This is good for when you want to use z-index but bad when other stacking contexts are created elsewhere and conflict in some way. Most people don’t know the properties that create stacking contexts, but these are usually the culprits to when you think you need to start introducing z-index into your CSS. Here’s a few important points:

If you create a container (for container queries) with inline-size or size, that creates a new stacking context.
If you set opacity on something to anything less than 1, that creates a new stacking context.
Nearly anything related to transforms, filters, masks, and blend modes will create a new stacking context.

This illustrates one of the things that makes people upset about CSS. There are properties that can affect other things in the composition in ways you don’t expect. You’d think that simply setting opacity: .5; is just making the element translucent, but there’s other side effects associated with it that could be unintended. Unfortunately, the only way to really know these is with experience. The more you avoid learning this, the more you’ll wonder what is happening every moment you begrudgingly write CSS.

Getting back to the inset fill technique. Instead of using position, I recommend trying to use display: grid; instead:

.parent {
    display: grid; /** or inline-grid */
}

.child {
    grid-area: 1 / 1 / -1 / -1;
}

The grid-area set in the child says to make sure this item touches all of the edges of the parent grid, filling the space. This forces the element to appear on top of any other children that may be within the grid.

Reading flow

Ordering things in the third dimension isn’t the only way we can affect elements using CSS. We’ve had the order property since the introduction of Flexbox. This has the ability to visually rearrange the elements in a composition without changing their order in the DOM.

.flex-child {
    order: 2;
}

There’s other properties that can change the visual order, such as flex-direction and even grid-areas. However, my recommendation is to avoid doing this, and if you must change the order to update the DOM order instead.

Now I know what you’re probably thinking, using JavaScript to rearrange the DOM sounds expensive when CSS would be much more performant and that’s true. The problem comes down to accessibility. The page structure should match the visual order of elements. If it doesn’t, then folks who can’t see the visual rearrangement can be confused about the order of the elements.

Imagine that someone who uses an assistive technology has called a help line for assistance with their account. The person on the phone says, “click the first button”. If the DOM order doesn’t match the visual order, the first button could be different to these folks and cause confusion down the line.

I keep this in mind when designing, and consider the ways I could keep the order maintained when the layout needs to change based on the available size. Sometimes though, you get a design in your inbox that can’t have reordering avoided. That’s when as of right now I’d recommend using a ResizeObserver to reflow the elements instead of CSS for the reasons I’ve described above. Here’s an implementation for my design system playground.

Bring order

Good things are on the way! There’s a new CSS property being discussed called reading-flow which is designed to help the element order problems I’ve described above. If this property becomes available, then we could tell the browser what order the elements should be in if the visual order doesn’t match. Rachel Andrew has some examples and a presentation on this. This is relating directly to the Masonry discussions to help understand what the intended flow is meant to be for the user. Having this along with top-layer will make setting the order of elements more clear than ever before.

Bottom line is that when you are trying to update the order of elements using CSS, pause to think of the side-effects of these decisions and refer to some of the recommendations here to help keep a consistent structure.

People's Primitives

Tue, 03 Mar 2026 00:00:00 GMT

I tend to take a minimalist approach when it comes to design systems. One of the reasons for this is the empathy I have for maintainers of these systems. The responsibility of supporting a group of creatives while not being overwhelmed by the number of resources they need is a challenge. However, this doesn’t mean I don’t have empathy for the people looking to express themselves. It’s why I am so proud of the Mise en Mode approach; that it allows for infinite expressions in ways other systems would fail when pressed, and fail in different ways.

One major drawback to Mise en Mode is being new. Not just new in terms of being recent, but also in terms of thinking. It’s the same sort of paradigm shift that took responsive design years to change the way of working, and even more related to the need for semantic tokens to support both light and dark expressions. It’s just hard to think differently for many.

So when I say, you—collectively—need primitives but you—yourself—don’t need primitives, it’s just a different way of thinking.

Why you collectively need primitives

The definition of a primitive is:

A tier of token meant to have a permanent value assigned…

An example of this might be color-red-500 which a person should reasonably expect the color red to be represented as a value, perhaps in the middle of a set of reds. A clear benefit to primitive tokens is their ease of reference. In other words, it is much easier to say and remember “color red five hundred” than it is to reference the related color channels that represent this specific color of red. This is helpful to communicate the idea across people and teams. People need primitives.

The life of a token

Here’s a question that could split the room, when thinking about switching between light and dark expressions, should the value of color-red-200 change between these expressions?

In other words, do you expect something loosely like this:

[data-theme="light"] {
    --color-red-200: color-mix(in oklch, red, white 20%);
}

[data-theme="dark"] {
    --color-red-200: color-mix(in oklch, red, black 20%);
}

In the example above, the light theme has the 200 value represent a lighter red. While the dark theme has the same 200 value represent a darker red.

If you expect the value of color-red-200 to change in this way, this is fundamentally not a primitive by definition. Primitive tokens are meant to represent permanent values. They are meant to act like constants in the system, just like how you might store an API key and then use it later. The key’s value is too hard to recall, so storing it in something human readable is helpful.

Why we expect them to be permanent is to meet user expectations. Otherwise, the mental model of token color-red-200 needs to switch between the expression of light and dark. In one context 200 would need to mean lighter, and in another 200 would need to mean darker. It’s easy to get these confused when trying to select which one from the set you are supposed to use. Is color-red-700 the light one now, or is it color-red-200? This is the job for semantic tokens which don’t need to know if the value is light or dark. Semantic tokens don’t describe values, they describe intention and how we express those intentions can change. We can choose a different red from the set of reds. But we shouldn’t change what color-red-200 means. The agreement of how the primitives are prepared should be stable and meet expectations for the organization.

This is especially the case when a brand changes from blue to red, as was the case for AirBnB. Assigning color-blue-500 to the logo might have seemed reasonable at the time. But once the new expression was introduced, it certainly doesn’t make sense to now change the assignment to a red shade for color-blue-500. This would break expectations for the people using the system. A semantic token meant to describe where the brand color is shown would be more appropriate, and we can later reassign the value of that from blue to red or any other special expression in the future.

Why you yourself don’t need primitives

At the point I hope I’ve illustrated the reason why tokens like color-red-500 are meant to be permanent and why they can be helpful to us. But the system itself doesn’t need them, especially a truly semantic one.

Let’s compare the following two blocks of CSS:

:root {
    --error-text: #9e2000;
}

:root {
    --error-text: var(--color-red-700);
}

Other than one having a more human readable value, what is the difference between these approaches? Because the primitive is meant to be permanent, and the hard coded value is permanent, there isn’t much difference. You could argue that if we’re going to reuse the --color-red-700 in multiple places, then having a variable is helpful. But think about the act of reusing the variable. How would you reuse it? In a very basic sense, you would copy and paste the primitive in the places that it is meant to be reused. Well, you’d also do the same if you use the hexcode directly. You’d copy and paste it in the places it was meant to be reused.

“But that’s not how I assign these values,” you say. “I don’t select from a list of hexcodes, I select from a list of names.” Precisely! You use your meaty eyes to look for the name in a dropdown somewhere, but there’s nothing keeping that dropdown from being the set of values themselves other than those meaty eyes of yours. This could be a dropdown of binary numbers for color. The result would be the same, but because you can’t read the value, you are uneasy about using the value. It just feels better when it’s readable.

In fact, in a truly semantic system, the amount of times you’d be choosing a primitive should also be very small, maybe even once! This starts going into how to think of semantic naming and further using contextual expressions; a tangent to the current topic. But a good way to tell if some system could be more semantic is the number of times you use a single primitive. If you find yourself using it several times in a system, it’s possible that these assignments could be reduced to a more generic semantic token for them all. As always, my goal is having a small set of overall tokens, and removing the primitive tier completely is certainly less maintenance overall.

You might think this is only viable when you are maintaining a single theme. However, I’ll argue this really hits home when you are supporting multiple themes. When supporting multiple themes, you could have v1, v2, and v3 of these themes. You could have themes for different seasons, different promotions, and different reasons. So instead of revisiting the same file over and over again, you make a new theme as a new file. A new collection of assignments to semantic tokens. The semantic tokens stay the same, but the assignments change.

That’s what really changes. It’s not the tokens that change, it’s how you assign them. Semantic tokens are a proxy to the experience, but primitives should never be found there. Primitives should only exist in the exercise of assigning values, if at all! It is there in the act of curating that you might as well just use the raw code since you might never return to this theme. You might just create a whole new one from scratch for the next product need, with wholly new values to create that new expression.

For humans and human-like systems

The reality is that you most likely aren’t going to get rid of your primitive tier, especially in large organizations with lots of ideas being shared. People need to discuss design decisions and agreements between other humans. As system professionals, organization seems like the right thing to do and having these sets keeps our decisions organized. And as AI continues to copilot our work as if it was another human in the room, we need to meet its expectations too. We also need to verify that it’s doing the right thing with our meaty eyes.

But if it’s just a system for you, as many design systems nerds tend to tinker with, maybe consider reducing your tokens and you might wind up over the hill.

Pretext review

Mon, 30 Mar 2026 00:00:00 GMT

This weekend a project called pretext started making waves by Cheng Lou. Here’s a gif that has been blowing up social media:

There’s no doubt about how impressive this demo is. The speed in which the text moves out of the way of the dragon is pretty incredible. As expected, many people are saying this is the end of CSS. So, let’s talk about it and address the demos provided that showcase some of the features in the lens of user experience.

Accordion

The first demo is of an accordion showcasing how the sections open and close smoothly without CSS hacks or measuring the DOM. This has been true for many years, we’ve wanted to animate from an intrinsic height for a long time. Well, we can do that now with pure CSS, in a few different ways.

The first way was maybe a hack, which was to animate the grid row. This was discovered 5 years ago. The difficulty with this approach is that it doesn’t work well with the native <details> element.

The second way is to use interpolate-size: allow-keywords. This allows you to animate between a <length-percentage> value and an intrinsic size, fit-content, or max-content. This allows you to animate between 0 and auto for the height.

And finally, we have calc-size() which is a function I recently used on the new Mise en Mode website to get the auto size as a number that can be used in other functions, such as round(). This also calculates the intrinsic size of the content, so it can be used to animate from 0 to auto as well.

As you might see when reviewing the MDN pages of these new CSS features, they don’t all have baseline availability yet. But do you really need JavaScript in order to animate the accordion? I’d argue you don’t, if you’re willing to put in a little extra effort learning what CSS has, and not ship some extra JavaScript for the sake of this.

Bubbles

This is an interesting one. This is showcasing something called the “shrinkwrap” problem that is now more common than ever in a world of web chats. The problem is that CSS text wrapping isn’t efficient. The bubble that it leaves will have extra space not taken by text. What would be preferred is for the bubble to only be as big as the text needs to be. So without the shrinkwrap, each bubble is the same width. Meanwhile, with shrinkwrap, the bubbles match the size of the text leaving no extra space.

There is a CSS solution found by Roman Komarov to help with this problem which uses the new anchor positioning features. It also uses some pseudo element tricks to get the effect to behave. This is a pretty clever solution, but it is also pretty complex. It also doesn’t work in all browsers yet.

The question is, do you want to bring in a JavaScript library just to get your text bubbles to shrinkwrap? Is this going to improve the user experience or is it an attention to detail that is not worth the cost of the extra JavaScript? I would argue the latter. The shrinkwrap problem is a problem, but it’s not a problem that is worth the cost of bringing in a JavaScript library to solve it. It’s a nice to have, but it’s not a must have.

Dynamic Layout

This looks like a magazine or editorial layout which has some images that are effecting the placement of the text. When I first saw this, I immediately thought of the shape-outside property which allows you to wrap text around a shape. Honestly, I haven’t used this CSS property much but I do know it takes some setup in order for it to work. You’d need to have an alpha of the shape so that text can wrap around it. The object needs to be set as a float in order for the wrapping to occur. Placing that element could be a pain, requiring additional margins to be added, most likely with shape-margin.

What CSS won’t accomplish is the rotation of the images. For example, setting rotate: 45deg on the image doesn’t affect the text wrapping around it. In the pretext demo, rotating does affect the text. Ultimately, I imagine you could maybe animate a very complex polygon of points to follow on an interaction. But the reality here is that if you want this effect, JavaScript is the way to go.

But do you want this effect?

Even without the animation, when text doesn’t consistently start at the same place, it can become tiring to read. This is why we don’t typically center body text. Our eye wants to align to the left (or right in RTL languages) and when it can’t, it can be a bit of a strain. The additional rotation that can occur would make catching the word you were trying to read difficult since all the lines are recalculating their position on every frame. This is a fun effect, but it’s not something that I would add to an article because it’ll distract from the content and make it harder to read.

Variable Typographic ASCII

As you might imagine, this isn’t meant for you to read the text. This is instead a artistic effect that uses glyphs to create a visual piece of art. Since there isn’t anything here that is specifically UX related, I’ll refrain from commenting on it, past hoping that someone puts an aria-hidden="true" on it so that screen readers don’t try to read that unintelligible mess.

Editorial Engine

Similar to the dynamic layout, this is a layout that has some images that are effecting the placement of the text. The difficulty in reading the text is much more apparent here because the balls are constantly moving around making the location of every word change on every frame. As said earlier, not something I’d use for something I’d want someone to read.

Justification Comparison

I have to admit this has some practical use. The justification algorithm in CSS leaves a lot to be desired. It doesn’t do a good job of balancing the space between words and letters, which leads to large gaps appearing within the text called rivers. The pretext demos show a better way of balancing the text such that the rivers are reduced, even having tighter algorithms available.

Though, one thing you’ll need to be careful of is the introduction of hyphenation. CSS has a hyphens property that allows you to loosely control when words are hyphenated. If you have a better justification algorithm, you might find that you need to hyphenate more often in order to get the best results. This is something to keep in mind when considering this approach as I did when typesetting the book Mise en Mode and ultimately decided to avoid justifying the text because of the potential for rivers and the need for hyphenation. I wanted to avoid both of those things in order to provide the best reading experience possible. I kept the content as the primary focus in a way that was familiar without stressing over the details of justification. Curating every small hyphen is very tedious. I personally rather keep the words intact and not have full justification.

Rich Text

Again, I think this does have some practical use. I’ve recently written about the difficulty in wrapping inline code accurately in CSS. In this demo, the inline code does wrap in a reasonable way but I’ll also say there’s configurations that make the wrapping a bit too eager.

It might make some sense to add some <wbr> spaces into the code at the right places. This could be done in a preprocessing step instead of on the client where the pretext project needs to run.

Masonry

Ah yes, the layout everyone is waiting for. While display: grid-lanes isn’t the property value we might have been expecting, the industry has been asking for a masonry layout for a long time. The pretext demo shows how to achieve this layout with JavaScript.

While we’ve known that we’ve needed JavaScript to have dynamic masonry layouts for a long time, there’s something you need to consider when implementing them; reading order.

When you look at a masonry layout, what is the order of the boxes meant to be read in? Is it top to bottom, left to right? Or is it left to right, top to bottom? Maybe it changes due to one box being longer than another. If you inspect the demo you’ll see that some of the items are inserted in places that aren’t in any clear order. It is most likely using a dense packing algorithm to efficiently use the available space, but this isn’t necessarily how the items are meant to be consumed.

The new reading-flow property in CSS is meant to help suggest how these items are meant to be read. I’ll say with the amount of consideration the CSSWG has put into display: grid-lanes, I’d trust that they’ve thought more about how masonry layouts should be managed more than “whatever fits best”.

What is pretext for?

It’s for people who want more control over how text flows; either for artistic purposes or for typesetting designers who crave the tools traditional print design has had for a long time. Just remember the web is not print. Text has never animated on a magazine page, nor has that magazine page needed to download additional code in order for the layout to behave. These are different mediums even if we’ve made analogs to them over the years.

I’m certainly not saying to avoid using the library, I think it’s fun and does have some practical use cases. But you should first consider your users and whether the features of this library are worth the cost of the extra JavaScript and the potential decrease in user experience. If you do decide to use it, make sure to use it in a way that enhances the content and doesn’t distract from it.

This certainly isn’t the end of CSS, it’s showing what’s next.

Relearning line height

Thu, 13 Feb 2025 00:00:00 GMT

My wife and I were having an argument about line-height. It’s what happens when you live in a design systems house. She was working on updating some font properties and making a case for a larger line-height reflecting on the WCAG guidelines 1.4.12 (Text spacing). The guidelines were confusing so she also found another reference within the United States Web Design System (USWDS) with the following quote:

Longer texts require more line height. Headings and other content elements no longer than a line or two can have a line height between 1 (line-height 1) and 1.35 (line-height 3). Longer texts should have a line height of at least 1.5 (line-height 4).

I was shooketh. I’ve never seen any mention of having the length of the line affect the size of the line-height in the decades I’ve been working on the web. I’ve always seen it based on the font-size. It’s the reason why the popular recommendation has been to use a unitless value.

.some-text {
    /** 150% the font-size */
    line-height: 1.5;
}

So, I immediately set out to disambiguate this and I was shocked at what I found. Read on in the comments. Just kidding.

I found four sources that all mention that the line-height should be affected by the length of a line; also known as the “measure”.

Pimp My Type “Longer lines need more line height, shorter lines need less.”
Typographic Web Design “Depending on the amount of text, the line length, the font size, and the size of a font’s x-height, you may find that the line height needs to be tightened or loosened slightly to promote comfortable reading.”
Google Fonts Knowledge “There’s no secret formula for setting the “right” line height for type. It’ll depend on the font, the size it’s set at, the length of the line, and the overall reading context”
Typographic Design Patterns And Best Practices “Leading (or line height) will always depend on your chosen font size and measure (or line length).”

In fact, that last article published by Smashing Magazine has some data about the typography from popular blogs. Here’s a copy of the data:

line height (pixels) ÷ body copy font size (pixels) = 1.48
line length (pixels) ÷ line height (pixels) = 27.8
space between paragraphs (pixels) ÷ line height (pixels) = 0.754

This got my wheels turning. While I know one of the articles said there’s no perfect formula, could we make something that has a general approximation to have a variable line-height based on both font-size and measure? In the year 2025, let’s see what we can do.

Minimums and maximums

We’ll want to use a clamp() function for a rate of change and we’ll want to know what the minimum and maximum line-height values will be. If we consider that paragraphs are typically the longest lines and the recommendation is supposed to be 1.5, we’ll make that the maximum. Headlines are typically shorter in terms of line length and often have a line-height of between 1.1 and 1.2 so I’ll pick 1.15 for the minimum. We’ll set these as variables because we’ll need them later.

.text {
    --lh-min: 1.15;
    --lh-max: 1.5;
    line-height: clamp(var(--lh-min), var(--lh), var(--lh-max));
}

Where --lh computes our line-height depending on the width of the text container. Based on what we have so far, we’re looking to generate a value between 1.15 and 1.5.

Before we get into measuring the width, I also want to touch upon another rule of thumb. It’s usually a best practice for you to limit the number of characters for any line. This makes larger amounts of text easier to read because your eye doesn’t need to travel as far when scanning for the next line. The range of acceptable characters for this length is anywhere between 40 and 80, so I typically pick 60 characters as an average.

We’ll also want to pick a minimum number of characters. This is meant to denote the least amount of characters where the line-height stops decreasing if the lines are too short. For this, I’d like to determine what the longest common words are and count their characters. I don’t feel like accounting for “antidisestablishmentarianism” is realistic but accounting for “acknowledgements” is certainly reasonable. I couldn’t find a readily available list of these words since what common means is subjective. However, I did find a resource that lists long words of a certain number of syllables. I reviewed the lists and chose that 4 syllable words feel more common than 5 syllable words. The average number of characters from the words listed is roughly 18, so we’ll use that as our minimum.

Measuring measure

Admittedly, it won’t be feasible with CSS alone to determine the length of each line of text, but we can get the largest width of an entire containing element of text. I’d argue that we actually don’t want each individual line to affect the line-height for each line differently. That would make the vertical rhythm of a single paragraph very erratic. Getting the width of a container element is more reasonable and uniform.

At first, I thought a container query would be the right direction. After all, we are trying to query the width of the text. However, there’s two problems with this. First, we’d need to query for every change that happens to the container, that would be like making a container query for every pixel and that isn’t realistic. Second, you can’t affect the container within the container query. This means we’d need some wrapping element as the container first, and then we could affect the text component in some way. However, that isn’t helpful since we really want to know the text component size. So how might we do this?

Time for a hack

I found a post at Frontend Masters called “How to Get the Width/Height of Any Element in Only CSS” which is precisely what we need to do. It uses a uninituitive trick with scroll-driven animations to achieve the effect. I highly recommend reading through the post if you want to learn some serious CSS magic. The tl;dr as I understand it is that as you resize an element, the amount allowed to scroll changes. That change will affect the scroll timeline and we use the amount if affects the timeline to determine the width. I could be wrong on that, I was just excited to have a working concept.

For now, we want to grab the baseline of the effect with a few modifications. Let’s start with the @-rules

@property --_x {
  syntax: "<number>";
  inherits: true;
  initial-value: 0; 
}

@property --ch {
  syntax: "<integer>";
  inherits: true;
  initial-value: 0; 
}

@keyframes x { to { --_x: 1} }

This is mostly identical to what is in the post, however I’ve changed the --w variable to --ch. This will represent the number of characters or the width of the containing element in terms of ch. Now for the declaration block:

.text {
  --lh-min: 1.15;
  --lh-max: 1.5;
  --ch: calc(1/(1 - var(--_x)));
  display: inline-block;
  overflow: auto;
  timeline-scope: --cx;
  animation: x linear;
  animation-timeline: --cx;
  animation-range: entry 100% exit 100%;
  
  line-height: clamp(
    var(--lh-min),
    var(--lh),
    var(--lh-max)
  );
  
  &::before {
    content: '';
    width: 1ch;
    display: block;
    view-timeline: --cx inline;
  }
}

A few things are changed here, other than removing references to the y-axis. First, I’ve removed the position properties because that can create new stacking contexts and it doesn’t seem to change the final outcome. I’ve also set the .text to be inline-block. This is because block elements will just take up the width of their container. We want the amount of text to determine the size of the container. I’ve also updated ::before to have width: 1ch which allows us to measure in terms of characters instead of pixels.

Now we’re ready for the final part, math!

Equation of a line

Like my previous post that explored some advanced typographic tricks, we’re going to need to determine the rate of change here. We’re working linearly so we’ll need the same equations as before. First, the slope of the line.

$m=(y_2-y_1)/(x_2-x_1)$

We can represent this in CSS like this:

.text {
    --lh-min: 1.15;
    --lh-max: 1.5;
    --ch-min: 18;
    --ch-max: 60;
    --lh-delta: calc(var(--lh-max) - var(--lh-min));
    --ch-delta: calc(var(--ch-max) - var(--ch-min));
    --slope: calc(var(--ch-delta) / var(--lh-delta));
}

Where --slope is the result. Next, we need to solve for the “b” part of equation. This is what I’ll call the --offset.

$b=y_1 - (m \times x_1)$

That is represented in CSS like this:

.text {
    --lh-min: 1.15;
    --lh-max: 1.5;
    --ch-min: 18;
    --ch-max: 60;
    --lh-delta: calc(var(--lh-max) - var(--lh-min));
    --ch-delta: calc(var(--ch-max) - var(--ch-min));
    --slope: calc(var(--ch-delta) / var(--lh-delta));
    --offset: calc(var(--ch-min) - (var(--slope) * var(--lh-min)));
}

And finally, we’ll use our restructured line equation to determine what the line-height value should be based on the --ch value.

$x=(y-b)/m$

.text {
    --lh-min: 1.15;
    --lh-max: 1.5;
    --ch-min: 18;
    --ch-max: 60;
    --lh-delta: calc(var(--lh-max) - var(--lh-min));
    --ch-delta: calc(var(--ch-max) - var(--ch-min));
    --slope: calc(var(--ch-delta) / var(--lh-delta));
    --offset: calc(var(--ch-min) - (var(--slope) * var(--lh-min)));
    --lh: calc((var(--ch) - var(--offset)) / var(--slope));
}

Putting these variables together with the earlier CSS gives you the demo below.

See the Pen CSS-Only, super easy screensize numeric pixel value width/height vars by Donnie D’Amato (@fauxserious) on CodePen.

I’ve included a character counter at the end of the element so you can see the result of --ch. I’ve also made the element contenteditable so you can change the text right in the browser window. You should see the line height change with a ch value clamped between 18 and 60.

Screenreader only

Sat, 27 Apr 2024 00:00:00 GMT

I am a big proponent of component-driven development, and don’t agree with the utility class method of styling. In component-driven development, you offer blackbox abstractions of common implementations. Meanwhile, the utility class method allows for more customization. In a systematic approach, we want our experiences to be consistent and therefore follow the same patterns and conventions. Distributing these blackboxes that align with guidelines by default makes a consistent experience easy to create and manage. Whereas, trying to learn and follow guidelines from other resources to implement piecemeal comes with misintereptations and other inconsistencies.

However, in this work there has been one concept that I’ve stuggled to put into this component-driven ecosystem; screenreader only as it has traditionally existed as a class (eg., .sr-only) added to an otherwise benign element.

Amongst the library

The purpose of screenreader only is to mark a section of an interface that is meant specifically for assistive technologies to pick up within the experience; invisible to sighted users. Here’s a common example:

<button type="button">
    <svg
        focusable="false"
        aria-hidden="true"
        viewBox="0 0 24 24">
    <path
        d="M19 6.41L17.59 5 12 10.59 6.41 5 5
            6.41 10.59 12 5 17.59 6.41 19 12
            13.41 17.59 19 19 17.59 13.41 12z" />
    </svg>
    <span class="sr-only">Close</span>
</button>

In this example, sighted users will be able to see the path of the <svg/> in the shape of an ‘x’ with no other visual information. Non-sighted users who leverage assistive technology should receive “Close” from their tool and ignore the data set by the <svg/>. There’s more about this composition and words about screenreader only versus aria-label in this post by Chris Ferdinandi.

My gut reaction is that it would be odd to offer such a component that simply applies the styles required to make it hidden and for it to be offered as an exception to an otherwise utility-free ecosystem. However, I don’t like exceptions, I strive for consistent thoughtful systems.

My first thought is where a <ScreenreaderOnly/> would live amongst other components, if it is in fact a component itself. This is assuming that the library is vast and requires subsections that aim to direct visitors to the appropriate component through navigation. First I’d assume this might live with other “accessibility” components. However, this also assumes that folks are actively looking to include accessibility in their experiences; something that we can only dream of across an organization.

Further, we might consider accessibility as a quality of components, perhaps not a component itself. As I’m having difficulty thinking about other possible memebers of this family that would also be associated with the <ScreenreaderOnly/> component.

My next thought is that because it is a quality, perhaps it isn’t a component but a property on an existing component we set. Because we expect that the content of this conceptual <ScreenreaderOnly/> component to only ever be text, it might be safe to consider that it is a property of a text component.

<Text screenreaderOnly>To begin, start by...<Text/>

The <Text/> component will be widely more popular than the possible <ScreenreaderOnly/> component, which will cause more folks to potentially visit its API and learn about this helpful feature. This being an opportunity to educate when its use is appropriate.

When is it appropriate

I did quite a bit of reading and research before writing this post. As I’m an advocate for accessibility, I don’t consider myself an expert and definitely have areas of improvement in my practice. I wanted to know when the concept of screenreader only was appropriate if at all.

For this topic, I highly recommend reading Scott O’Hara’s post called Inclusively Hidden.

In Scott’s post, he describes some alternatives to screenreader only; specifically one loophole in particular.

By attaching an aria-describedby or aria-labelledby attribute to a focusable element, and setting the ARIA attribute’s value to the completely hidden element’s id, screen readers will announce the content of the completely hidden element.

Here’s his example:

<p class="visually-hidden" id="example_desc">
  Here are specific instructions for the type
  of information this form input is expecting to receive...
</p>

<label for="example">
  Example
</label>
<input type="text" id="example" aria-describedby="example_desc">

In this way, we still need to apply styles to the .visually-hidden element in order for it to disappear from view. But this also demonstrates how to connect that content to an interactive element for further context by using aria-describedby.

For completeness, here’s what Scott recommends as the styles for visually-hidden:

.visually-hidden:not(:focus):not(:active) {
  clip: rect(0 0 0 0); 
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap; 
  width: 1px;
}

I’m now imagining some sort of interface for when screenreaderOnly is used on the <Text/> component to ensure it is connected to something.

// Source
function Text({ screenreaderOnly, children }) {
    /**
     * We wouldn't want to always add an id to all text
     * instead we'd add conditionally for screenreaderOnly.
     * This is just for this example.
     */
    const id = React.useId();

    React.useEffect(() => {
        /**
         * Consider appending the id instead of replacing
         * `aria-describedby` can accept space separated ids
         */
        screenreaderOnly
            ?.current
            ?.setAttribute('aria-describedby', id);
    }, [screenreaderOnly, id]);

    /**
     * Assume additional logic to
     * bring-your-own HTML tag (BYOHTMLT)
     * and force text node children.
     */
    return (
        <div
            className={ screenreaderOnly && 'visually-hidden' }
            id={ id }>{ children }</div>
    );  
}

// Usage
function MyForm() {
    const ref = useRef();
    return (
        <Text screenreaderOnly={ ref }>
            Here are specific instructions for
            the type of information this form
            input is expecting to receive...
        </Text>

        <label for="example">
            Example
        </label>
        <input type="text" id="example" ref={ ref }>
    )
}

However you feel about using a useEffect to then use a DOM API to set an attribute that this component shouldn’t have control over is less important than the concept of connecting these two elements for accessibility purposes in an easy to use interface. It would be important to me that using <Text screenreaderOnly> requires the connection be maintained. It is too easy to accidentally rename ids in a vast composition of components causing accessibility wiring to break.

Also you can have your own naming convention to denote that the expected input is a ref to the element that you wish to describe.

It’s important to know that aria-label, aria-labelledby and aria-describedby are not valid on all elements. The general gist is that these are meant for interactive elements or landmark elements. This interface above could be enhanced to warn if the ref is attached to an element that is inappropriate but would need some more conditional logic to identify this.

Why `aria-describedby`

The benefits of using aria-describedby for screenreader only content is that first it doesn’t replace existing labeling (as aria-labelledby would); it is meant to accompany it. It also benefits by auto-translation technologies that may struggle finding aria-label content will more easily find aria-describedby content because it is written within a discoverable DOM node.

Certainly aria-describedby isn’t always going to be the correct solution. I believe if you’ve done due dilligence in crafting a well prepared experience, with semantic elements and appropriate attribute usage, this approach is probably going to help provide additional context to visually-impared users for complex interfaces.

Know that if the content would also help visual users, you should absolutely consider putting the content inline with the composition and forego additional configuration complexity.

And as always, reconsider the complexity of your experience overall, as you might be able to avoid cumbersome instructions for something simpler.

Spacing solved

Mon, 09 May 2022 00:00:00 GMT

Design tokens for color and typography are fairly common for design systems. In particular, color token naming has finally gotten some traction by thinking semantically. In other words, not naming the color based on the value but the intent to use. Typography is getting some traction here as well; where naming is done by use. This tends to be easier to understand since a type style is composed of many different properties.

Spacing, on the other hand, has been locked into the original token naming scheme where the name of the token relates to the value of space; not the use. Tokens are either named using T-shirt sizing or numbers with a scale of several to use.

The importance of using semantic tokens is to limit the decision making for the designer. The designer should focus on crafting the experience in a wireframe-like mindset. Color, typography, and other styles are noise that distracts from solving user problems. The design system should have the guidance to make clear decisions and reduce the noise.

So the question is, how do we give meaning to spacing tokens?

Relationships

The Gestalt principle of proximity describes that elements that are close to each other are meant to be considered more related to each other than elements more far away. This is the principle we as designers are implementing when we decide the amount space used between elements.

But how do we choose exactly how much space? Often times it’s looking at the whole page and picking what feels right with a few constraints (like using multiples of 8 for the values). However, the system cannot give guidance about feelings, it should have clear reasons as to why to choose an amount of space.

The way I’ve identified an amount of space is by social relationships. Degrees of separation describes the way that entities are social connected to each other. We can think of parent-children or siblings that live in the same house to be 1 degree of separation from each other, while next door neighbors might be 2 degrees.

Now, if we consider these entities as elements of an interface, the parent-child and sibling relationships translate. The parent <ul/> element and its children <li/> elements can have 1 degree of separation; meaning they are very closely related. While the <ul/> element and its <body/> ancestor element may not be as close.

Keep this in mind as we review the next topic; density contexts.

Density contexts

I spent a great deal of time gazing at the first image in Nathan Curtis’s post about Spacing in Design Systems. Here’s the image from the post:

If we were to use the mental model we’ve come up with above, the tags within each card are 1 degree of separation apart from each other; in this comp a value of 8. The paragraph above is different from the tags, or in the next house. That can be described as 2 degrees of separation between the paragraph and tags.

All of this works fairly well within the card, describing all the relationships of detail and space within. Where this is fuzzy is the cards themselves; each card is clearly an indentical sibling of the next and by our rules should have 1 degree of separation between. That was previously shown inside the card as 8, but here it is 32 and this feels correct, but how do we describe this?

The answer is density contexts.

Every time we dive deeper into the content of the page, it is an opportunity to reduce the density of the area. This would reduce the amount of space around and between elements but maintain the relationships we aim to describe.

Let’s say, we start at the <body/>. Lots of space between sections of the page because they are very unrelated. Maybe one section includes a card layout like the one above. We then shift the density down one notch and tighten the space between the children in this area. Going down into a card, we shift another notch down and tighten further showing that this content is most closely related.

So each new density context defines the way space is used within that context. If you want less space between items because you want to show a close relation; add a new density shift and all the space within will reduce. This allows for the space between each card and the space between each tag to both be 1 degree of separation but the resolved value to be different because we are in a new density context.

Now the designer chooses the density context for this particular experience but what about the actual token names? How do we give meaning to the locations where the values should be expressed?

Padding and gap

We can think of padding as the space around an element and the gap as space between elements. In the cards referenced within the image above, we can use these definitions to describe the spacing used in most of the elements.

Spacing between the tags is a gap.
Spacing between the headings (video and supernova) is a gap.
Spacing between the headings, paragraph, tags, and the button is a gap.
Spacing between each card is a gap.
All other spacing is padding.

Each time the value of the gap changes signifies a density shift downward. First we start at a density where the gap equals 32, then we shift down (within the card) to a gap that equals 16, and finally we shift once more (inside each part of the card) where the gap equals 8.

So do we just use token names that describe padding and gap? Almost.

Tying it together

Going back to degrees of separation, I realized that trying to define larger degrees of separation would be difficult, especially when naming them with meaning. However, after compleing the exploration and identifying that there are really only two places where we need to apply space (around and between), that means I could reduce the number of spacing tokens down to 2 for most usage. That resulted in the following two names.

--spacing--near: often used to describe the spacing between elements showing close relation.
--spacing--away: often used to describe the spacing around elements showing less relation.

I use near and away because there are areas where we want to use these values that aren’t confined to the guidance above. Buttons are the best example, where we want the space on the horizontal axis to be greater than the vertical. Setting button { padding: var(--spacing--near) var(--spacing--away) } doesn’t break the mental model as much as if we used the word “gap” within the padding values for the button.

And that’s it, you can create an interface in terms of relationships and density systematically with a very small number of design decisions with clear guidance. Below is a Codepen where I’ve recreated the card using this approach:

See the Pen Spacing context by Donnie D’Amato (@fauxserious) on CodePen.

How to make density contexts in CSS

The approach to actually create density contexts in CSS is done by nesting CSS selectors and changing a variable at each level and recalculating what the spacing tokens mean at each.

$attr-sel: "[data-density-shift]";
$levels: 4;

@function fib($n) {
  @return if($n <= 1, 1, fib($n - 1) + fib($n - 2));
}

@mixin vars($n) {
  --spacing--away: calc(
    #{fib($n + 1)} * var(--density, 0.5rem)
  );

  --spacing--near: calc(
    #{fib($n)} * var(--density, 0.5rem)
  );
}


@for $i from 1 through $levels {
  $nest-sel: if($i == 1, "body", selector-nest($nest-sel, $attr-sel));

  #{$nest-sel} {
    @include vars($levels - $i);
  }
}

I’m using the Fibonacci sequence for the steps since designers love that golden ratio in layout.

+ Typography

You can take this one step further by including typography. If you consider that each use of typography is included into a category, the type scale could ramp based on the density instead of in isolation. This allows for a clearer relationship between typography and space as many designers strive for through vertical rhythm and a grid system.

If you identify categories of typography with proper guidance for each you can connect the density to the category. Body text becomes larger in hero images and smaller in general areas. Perhaps even smaller for data-dense interfaces like tables. Each area uses the same type style but the density changes the size.

Real world examples

If you’re interested in how this all works in a real site or system, the damato.design family of sites all use the above approach to determine spacing + typography, including this site. I will admit determining where to add the density shift is the bigger challenge but what helps is to identify where the --spacing--near and --spacing--away values should go first, then determine if the density should shift as the second step.

One more note, in the DAMATO Design System, we do not have many typography categories; only display, heading, standard, and detail. This restricts the number of heading levels to only display and heading which loses content hierarchy unless shifting density. We could include more typography categories to describe a few additional levels (title, subtitle, etc) but opted to exclude for simplicity.

Spicy specifications

Fri, 23 Jun 2023 00:00:00 GMT

Figma’s design conference Config just ended and one of the biggest announcements is the introduction of Variables. The reaction from the community is a mix of emotions. While many people were expecting Design Tokens, some can see the clear benefits of Variables while others are skeptical about perceived defiance to existing specifications. We’ll explore the current state of specifications for Design Tokens across the community and how Variables come into play.

Token specifications today

These are a few popular or relevant specifications that aim to describe the shape of a Design Token. While I haven’t completed an exhaustive search through existing systems with their own formats, the following examples will be enough to illustrate the current state of affairs.

Design Tokens Community Group

The Design Tokens Community Group (DTCG) is a collection of Design Tokens stakeholders from around the community representing design and development tools along with experts with working knowledge and experience in maintaining token libraries. The group has made some strides in a specification but it is very far from complete. The expectation is that all tools should adhere to this specification so that our representation of Design Tokens can be shared across tools. If there are deviations, a tool may skip a definition or fail. Here’s a basic example of a Design Token meant to describe a token color-red-500.

{
    "colors": {
        "color-red-500": {
            "$type": "color",
            "$value": "#f00",
        }
    }
}

Reference

This is the core of the DTCG specification; a nested object with unique names. At the lowest nesting there should exist $type and $value keys; where the $ denotes a special key that is meaningful for tools to read. In the example, the tool should know that the #f00 is a color value and handle it accordingly. There are a few other keys and other more complex configurations, but this is the foundation that everyone is expected to follow.

Tokens Studio

Tokens Studio (built from a plugin project called Figma Tokens) has had a longer history of use (Jun 2020) than the first agreement provided by the DTCG (Apr 2021). This was to fill needs that were not solved within Figma at the time. Therefore, their specification is slightly different.

{
    "colors": {
        "color-red-500": {
            "type": "color",
            "value": "#f00"
        }
    }
}

Reference

Note that the above is for a multi-file storage configuration. There are special keys expected at the first nesting level when using single-file storage. Also, note the absence of $ from the type and value which is not to DTCG specification today. Mike Kamminga, Tokens Studio CEO, says:

We have been transitioning to fully support the DTCG proposal.

Importantly, to support more complex customer needs, Tokens Studio has included additional features that the DTGC specification has not yet provided. Continued from the previous quote:

…we do fill some gaps where the proposed spec doesn’t provide solutions yet.

An example of filling gaps comes in the form of token resolvers which aim to describe complex relationships and conditionals which compute token values. While this has been suggested within the DTCG discussions, there are no official recommendations.

Specify

Specify is a design token management tool that has been around before the DTCG and has had integrations with Sketch before Figma. A few weeks ago, they announced the Specify Design Token Format (SDTF). An excerpt from their example is below:

{
    "colors": {
        "color-red-500": {
            "$type": "color",
            "$value": {
                "default": {
                    "model": "hex",
                    "hex": "#f00",
                    "alpha": 1,
                }
            }
        }
    }
}

Reference

The standout part of the above is the $value which is more descriptive than the others, containing more information about the value than only the string. As of today, this does not follow the DTCG specification but perhaps that’s by design. Nicolas André, Specify Senior Software Engineer, says:

The SDTF is not a file. The SDTF is designed to be a transport format between APIs that would eventually being configured by humans. To interact with it, we’ll use dedicated APIs lowering the underlaying complexity.

So the expectation here is that there are additional external systems that exist between APIs that expect this format.

Why not Design Tokens?

Jacob Miller, Figma Product Manager, says:

Our reasons for naming it variables was primarily to align with development. Variables, much like css variables, is not just for design tokens, it’s also for conditional logic, string translations, etc.

The important takeaway here is that Variables can be used to describe our idea of Design Tokens but also to support additional needs which will most likely exist outside Design Token expectations. A clear example of this is content substitutions for localization. Design Tokens were not created to support this foundationally but Variables, uniquely defined by Figma, can.

For reference here is an example of a Figma Variable:

{
   "id": "<FIGMA_INTERNAL_VARIABLE_ID>",
   "name": "color-red-500",
   "resolvedType": "COLOR",
   "valuesByMode": {
    "<FIGMA_INTERNAL_MODE_ID>": "#f00"
   }
}

Reference

This is not a Design Token but Figma’s proprietary format meant for use within the Figma ecosystem. Based on the official plugin built to transform Variables into Design Tokens, the valuesByMode will store several values by a unique identifier that relates to a mode. The mode could be light, dark, dense, Spanish, or many others and the value for this Variable can differ depending on the mode.

A deliberate choice

Figma has intelligently chosen the word “Variable” to opt out of following the specification to support its product features but also offers the import/export of the DTCG specification where appropriate against its Variables. I believe this is the correct direction as the DTCG learns from existing patterns. This allows Figma to go far beyond the responsibility of the specification in ways Design Tokens were never meant to be used.

You could argue that Token Studio and Specify are also behaving in the same way. However, I fear their current offerings are confusing when compared with the DTCG. Again, Figma made a conscious decision to create a unique ecosystem to allow for new features to be built; Variables are not Design Tokens. This is a subtle but important distinction as the other products create their own variations on top of an incomplete specification using conflicting methodologies. In other words, one cannot use a fully featured Tokens Studio file within Specify due to the incompatibility between specifications.

I believe the root of the problem is using the name Design Token for experimental approaches while a group aims to define what it means to be a Design Token. These other formats do not follow the specification in small and large ways and are therefore not accurate in describing Design Tokens as we expect them to be used in the community universally. Rebranding these novel approaches as something else for future features (as Figma has done) would make the expectations and responsibilities of Design Tokens more understandable to the community moving forward.

I have empathy for the pioneers like Tokens Studio and Specify; existing before the specification makes this exceptionally challenging for them, borderline unfair. What Specify has done is a good start; creating a branded “flavor” of Design Tokens with the SDTF. I’d recommend Token Studio do something similar such as TSTF. In this way, it can be perceived that these approaches are Design Token adjacent instead of wholly accurate to the community specification.

Let me be clear, I support the advancements that all of these companies are providing for the Design Tokens community. They are heavily influencing the direction of the specification and we could not be where we are today without this work. I am being critical of what a Design Token is expected to be as it currently depends on where you get your tokens from. I have confidence that alignment will come, it’s simply a noisy time to get started.

Storefront & Warehouse

Thu, 02 Oct 2025 00:00:00 GMT

I was speaking with a colleague recently about design system marketing. One of the problems I’ve seen is a person coming into design system resources and being immediately overwhelmed by the options. Hick’s Law strikes again. I’m not just talking about looking at a code base. This is the case for popular public design systems too. As much as I admire Adobe’s work on Spectrum, it’s very easy to be intimidated by all of the stuff they have featured in their documentation.

To illustrate this, I like to use an analogy that I call Storefront & Warehouse.

Getting needy

Let’s say you are looking for a new vacuum cleaner. You aren’t picky, you just need something that can clean dirt and pet hair from wood floors on occassion. You walk into a store, find a vacuum that looks good enough, and take it home. It work fine, nothing to be excited about. You got what you paid for and everything is good.

Now, let’s say you do have some additional criteria for your vacuum. Maybe, you’d prefer that the vacuum was red to match the furnishings, so the appliance blends in better with the room it’ll be stored in. So you walk to the store, and you don’t see any red vacuums on the shelf. You find a stock person and ask if there’s any red vacuums in the back. He comes back and says that the company makes custom plates to change the color. All you need to do is order the plate and your vacuum will be red. So, you walk out with a regular vacuum and change it to be red afterward. You got what you were expecting, even though it took a little bit of extra work and everything is good.

Now, let’s say you have a very specific desire. You want a vacuum in the shape of a standing lamp, so it really disappears when not in use, or better it can be used as a lamp while standing in the dock. You go to the store and look but there’s no vacuum like that on the shelf. You ask a stock person, if they have any in the back. This stock person loves the idea but knows that there’s no such vacuum in the warehouse. However, the warehouse does have all of the parts to make it. So, the stock person graciously gives you access to the warehouse so that you could build your own. It takes you a while to find all the pieces and figure out how to put them all together. In the end, you finally have precisely the vacuum you’ve been looking for and everything is good.

Struggling at the store

Instead of picturing something walking into a store and looking for a vacuum cleaner, think about it as a peer navigating to your design system resources looking for something they need. In some cases, it’s right there on the shelf. Some times it’s not quite what they need, but with a little configuration, it would be acceptable. And other times, a person would need to scour across different pages to collect the information needed to make exactly what they have in mind.

There’s increasing struggles in these cases when we think about how we publish about documentation. For example, some documentation sites make you feel like walking directly into the warehouse. You see all the vacuum cleaner pieces but the ones that work off-the-shelf are mixed in with all the parts. It’s not immediately clear where to go for the thing you are supposed to work with. There’s no storefront. I’d argue many large public design systems are guilty of this problem. With so many options, it’s hard to choose which is the best option as said earlier.

For folks who find the resource that looks close, sometimes the options aren’t clear. It’s like going to the store and never finding help to let you know that you can customize your vacuum cleaner. Instead, you leave the store and go try another one, or get a vacuum from the shelf and paint it red. In either case, it would have been better if you were informed about the customizability right there on the unit when you first saw it. No need for a stock person to find, the options are clear.

And finally, for folks that are immediately disappointed because they visit and don’t find anything that they need, this is the hardest to support. And unfortunately, this is something that I believe happens most often. With the rapid iterations of product design, no design system could possibly keep up with specific features. So, it is very common for people visiting resources to not have the time or experience to search for pages of documentation, tinker with some of parts, and craft something that aligns with the system. Often times, people believe it is faster to just make it without using the parts. I think with poorly documented design systems, this might very well be the case.

Think about it. If the resources in the design system don’t align well with the visitor’s mental model. It’ll take time for that person to read the documentation, get an understanding of the approach and patterns, build something with the parts, and finally integrate with their application. On the other hand, if the person builds it without adopting a new mental model, they still need to build the feature, it just might be with more individual parts. Importantly, these are parts they are familiar with. It’s that familiarity which equates to the speed of building and meeting the need of the product more quickly.

That’s why so many resources often align with a person’s mental model instead of more unique presentations, even if that unique presentation is better in any way. It’s why early GUIs speak about a desktop and folders instead of a terminal and directories for the public. It aligns with existing mental models of working in the physical world. This means that introducing something better but novel will be most successful when alongside an existing mental model.

In other words, if we’re going to offer a way to build the lamp-vacuum, when a person walks into the warehouse it should be immediately clear which parts they’ll need without being totally lost amongst all of the other unncessary parts.

Search first

Years ago, we had to walk through a store to find the place where they kept the vacuums. If I’ve been to the store before, maybe I remember where they’ve been kept. Hopefully, the store didn’t go through a redesign moving the items around, because my mental model of where the items are stored will make it faster for me to get to the thing I need.

Now, some larger stores like Home Depot have their inventory locations available through their mobile site. You pick the location you are visiting, search for the item at that location, and the website will tell you where that item is in the store by aisle and bin. This way, you can go directly to the item you need without walking through the whole store, learning the layout, and hopefully landing on the thing you needed. This also avoids the possibility of you missing the item through the vast amount of aisles and products. You have confidence what you need is there and where it should be.

This is why I find the exercise of creating navigation for a documentation site largely useless and potentially even harmful. Finding the thing you want is rarely useful in a wandering scenario. It is more helpful to zero-in on the resource you are looking for by aligning with your mental model. If you are from the UK and you look under “H” for hoover, you wouldn’t find any vacuums because the are listed under “V”. That would make the visitor assume that you have no vacuums because the information architecture doesn’t match their mental model, and they’ll leave empty handed because of your IA. IA that was intended to help makes people leave disappointed.

Meanwhile, a robust search experience could make the connection internally. Searching for hoover could alias to vacuums and produces the appropriate results. That way, searching could return results from the storefront first and warehouse after.

This sort of search experience is common for icons, where a person looking for the “close” icon should return for the same result for “x”, “dismiss”, etc.. There are other systems that even let a person draw the icon to provide results. We could imagine this expanding to components in our documentation sites.

The hot take here, drop the exercise of figuring out the IA of your documentation site, and invest time in a robust search. In the world of artificial intelligence, leverage that to match mental models instead of deliberate aliasing. It would be best to meet people where they are, without causing them to visit external sites and learn opinionated IA. But if you don’t have the resources for AI, make search site-wide and fuzzy af. That gives your visitors access to the whole storefront and warehouse, but raises the most appropriate resources for their needs.

Storybook iframe tango

Fri, 01 Nov 2024 00:00:00 GMT

Storybook is an essential part of design system development. It is considered an industry standard for creating components in isolation before they appear in production experiences. I’ve been working with the tool for nearly 8 years now and the team has really done a great job supporting the needs of our industry.

That said, we got a problem.

Leaky styles

I lean heavily into Storybook as a documentation platform. The product also went in that direction when introducing the ability to write stories as MDX. They’ve since walked back that approach in more recent iterations but, it is clear there is still a desire for writing documentation in the Storybook ecosystem.

When stories appear within documentation pages, the styles used to customize the documentation have a tendency to leak into the stories. As an example, if you are relying on the default body color to cascade down in your component, the styles of the documentation will also loosely target some of these things. In cases where your stories are shown in a different mode from the storybook, this can have an unintended presentation.

There’s a setting in Storybook that you can use which will create a barrier between the documentation styles and the stories.

export const preview: Preview = {
  parameters: {
    docs: {
      story: { inline: false }
    }
  }
}

That configuration solves a problem, but introduces another one.

Out of the frying pan

The above setting renders each story in an <iframe/> which is great for encapsulation, but awful for presentation. Specifically, the element does not know how big its content will be. Usually, this is a quick fix since the content of the frame is also the same domain as the page. We could just query inside the contentWindow for the body.scrollHeight and apply that amount to the <iframe/>; problem solved!

To do that, we first need to grab a reference to all the <iframe/> elements. Normally, this is document.getElementsByTagName('iframe') except Storybook renders on the client-side. That is, these <iframe/> elements don’t appear until later in the application lifecycle. So we have to wait until the page has these elements. Unfortunately, DOMContentLoaded doesn’t work because that fires before the hydration, same goes for the defer keyword on the <script/> tag. So how are we supposed to get these <iframe/> elements?

Enter my old friend, the Node Insertion hack. I first found this approach when working with registering web components. In fact, I speak about it within my very first post in the blog. We can use the same approach to wait for <iframe/> elements to appear and grab their reference. First, add the following CSS to the manager-head.html file:

iframe {
    visibility: hidden;
    animation: appear 0s linear forwards;
}

@keyframes appear {
    to { visibility: visible }
}

Next, add a <script/> tag in the same file with the following:


window.addEventListener('animationend', onAnimationEnd);

function onAnimationEnd(ev) {
    if (ev.animationName === 'appear') {
        handleIframe(ev.target);
    }
}

function handleIframe($iframe) {
    console.log($iframe);
}

This is not the element you are looking for

When you run storybook, you should get a log in the console that identifies an <iframe/> element. When you dig a bit deeper, you’ll recognize that the element it returned is the preview <iframe/>, not the one used for stories on a docs page. To get those <iframe/> elements, you’ll need to listen inside the preview also! Luckily, we can do this with a small change; update the preview-head.html to include the same CSS that we added to the manager-head.html. Let’s also update our handleIframe() function:

function handleIframe($iframe) {
    if ($iframe.id === 'storybook-preview-iframe') {
        $iframe.addEventListener('load', onLoad);
        onLoad.call($iframe);
    } else {
        adjustHeight($iframe);
    }
}

function onLoad() {
    this.contentWindow.addEventListener('animationend', onAnimationEnd);
}

function adjustHeight($iframe) {
    console.log($iframe);
}

Now, after you restart Storybook, the console should identify each individual Story <iframe/>. The next part is what we’ve been waiting to do. We want to get the height of the internal <body/> element and make the <iframe/> respect the size of the content. Storybook applies the height to the parent of the <iframe/> so we’ll need to get that in the process.

function adjustHeight($iframe) {
    const $body = $iframe.contentWindow.document.body;
    const $parent = $iframe.parentElement;
    const currentHeight = $parent.style.height;

    if (currentHeight === '400px') {
        $parent.style.height = $body.scrollHeight + 'px';
    }
}

In this function, we’re checking if the <iframe/> is the default set by Storybook (400px). If it is, we update the height based on the contents of the <body/>. This allows you to set the iframeHeight as a parameter is specific stories that should be a fixed height. This is helpful for stories that have content shifts, such as loading images.

Shadow DOM when?

At this point, I’m pretty sure that all of this could be avoided if the stories were rendered within a Shadow DOM. Maybe once I get truly bored I could start looking to see how I might do that. But in the meantime, check out the new version of the DAMATO Design System where I expect to publish real working examples of my approaches. It’s already been a big help in my regular discourse. More to come there over time.

UX Engineer, a terminal career

Mon, 26 Dec 2022 00:00:00 GMT

In my teens, I was involved in many extra-curricular activities in high school. I was president of the art club for all 4 years and lead for the school’s robotics team. While I wasn’t officially part of the class counsel, due to my volunteer work especially with the homecoming floats, I was given a new title by my peers over 20 years ago; Design Engineer.

I didn’t think much of it then but after being fully immersed in both design and engineering, I resonate with that title. Not only do I consider how an experience could be constructed; I actually construct it. That’s something that’s always been important to me. Just having the idea wasn’t good enough, I needed to show people the concept and it wouldn’t be complete unless it was the real deal.

Getting paid

It’s one thing to find your passion, it’s another thing for that passion to put bread on the table. My passion didn’t start doing that until after graduating college. My first engineering job was officially as the sole frontend engineer for a finacial tech company but they also didn’t have a designer. My co-workers saw how quickly I could prototype a design in CodePen and made it easy to collaborate, so they gave me the responsibility for the design of the platform too. That’s where I took on both roles but also had both titles; Product Designer & Frontend Engineer.

After that role, I was hired at a real estate startup as a Frontend Engineer. The codebase was massive, they were using a framework I’ve never seen, and my onboarding buddy was assigned to a totally different team working on the launch of what would become the most successful product on the platform. It was a sea of anxiety and I had a metric ton of imposter syndrome. However, as timing would have it, they also hired a new Director of UX and we were in many of the same onboarding groups. I raised the idea of joining their team to help with prototyping and better integration of design into code and after some formalities, that’s how I became their first UX Engineer.

I felt really relieved. Design was straightforward for me and I could ease my way into the codebase with small changes instead of feeling responsibility for the entire repository of code at once. Like many places, onboarding is not often crafted well because it’s done once and the business has other higher priorities. More on that later.

Rainbows & roses

Most of my first responsibilities were to prototype experiences to hand off for research studies. I quickly found that I was reusing the same assets over and over so I started making my own little library of components in CodePen. I could import files across pens by appending the file type to the end of the url. While there was an existing component library; these designs were often new and experimental. I needed my own collection of components that I could iterate on in isolation for these prototypes.

Eventually, I became more comfortable with the codebase and found areas of improvement; especially when it came to CSS. I found out then that most engineers have difficulty with CSS. For me, CSS came naturally and I was able to do things that didn’t seem possible for others. As one example, there was an ask from design to pin the footer to the bottom of our listing results. The listing results component was using a collection of CSS overrides on AG Grid, and the architecture of those overrides were outlined in a multi-page document. It was a big deal to even look at the project, let alone change it. The lead engineer for the frontend team told management a change like this would take 6 weeks.

I made the changes over 6 days.

Eventually, I was responsible for all CSS found on the platform. While I wasn’t looking at every PR, I was always called into the room for large projects or complex experiences. The listing details page was one of my last large influences; which was one of the first places where I was able to use display: grid; and position: sticky; on a production site. I became responsible for the component library, as it eventually matured into a design system. By the end of my time, I was putting together the Design System team and looking into how we could support all the various frameworks being used with a singular source of truth.

Managing expectations

While I loved all the work I was involved in, there was one thing that made me leave; lack of recognition. Many people were promoted during my tenure; I’ve seen some people promoted 3 times during my 2+ years there. I was promoted only once and it was title change with a cost of living pay increase. A few months later we’d have a new CTO and start new tech hubs around the world. What happened? Why was I left in the cold when everyone else was shining?

When I first became a UX Engineer, I was reporting under the design organization. The trouble here was that our Director of UX didn’t have experience managing an engineer before. While this autonomy felt good to me, there was no career ladder. It wasn’t clear what steps I needed to take to be promoted. After the director left, I was reporting to the principle designer who really didn’t want to manage people.

It was around this time the most senior frontend engineers were convincing me to come back into the engineering organization; right on the heels of the AG Grid work mentioned earlier. With some help from a new engineering manager willing to take me on, I moved back into the engineering organization. That manager was a huge help for my career because he understood my skills and influence and was able to be my voice in rooms I couldn’t be in. He was the person who fought for my promotion, just before he was pushed out by management.

I was reporting under a new manager then; someone who previously identified as a backend engineer. It felt like I was reporting under the design team again. For our mandatory 1:1, he’d ask how I was doing and I’d just telling what I was working on. He really couldn’t give me much feedback because he didn’t know my world. It wasn’t really his fault; we were just paired poorly.

When the new CTO came, we had a large restructuring which included new VPs of Engineering and other managers. After stating a case that I was a leader in the engineering organization, instead of receiving a promotion, I was restructured to report under one of the new VPs of Engineering. He really didn’t have any time for me; trying to get up to speed on larger problems that were happening with hyper growth. After having 6 managers and the company removing the only one that really helped me; I decided if I was going to grow, it couldn’t be here.

Picking a side

After I left, I joined the company I currently work for. Here, the management understands my value and every person I’ve reported to can hold in-depth conversations about my areas of interest and provides meaningful feedback. It’s really what I’ve been looking for all along. There’s only one problem:

My role is Software Engineer.

What’s the difference? As a Software Engineer, you’re expected to just live in the code. You rarely get a glimpse into the experience design side of feature development and instead need to be responsible for lots of different engineered systems; databasing, CI/CD, bundling configurations, along with feature development. All the problems you solve have to do with getting the computer to do what you want with commands. As a UX Engineer, you are responsible for the user experience. The problems you are solving are user needs and (in my opinion) much more interesting and impactful.

I don’t associate with being a Software Engineer. I associate with being a UX Engineer. However, because UX Engineering doesn’t have the career support that Software Engineering does; I need to masquerade as something I’m not just to succeed in a field and have a possibility of promotion.

This isn’t only where I work. The industry has a clear problem supporting UX Engineering. Often a company has a UX Engineering role but reports under either design or engineering. This will often lead to the problems I’ve personally experienced shown above; lack of understanding about the role for existing management. On the other hand, folks picking a side can struggle because they don’t have all the knowledge or experience as other folks with roles aligned to the larger organization. In other words, a designer probably knows all the hidden gems in Figma; while a UX Engineer might only know some intermediate techniques. Without clear responsibilities; the UX Engineer will look subpar to the Designer. In my case, I’m not able to effortlessly debug workflow problems for CI/CD and unfortunately that sounds like something a Software Engineer should do.

This is all assuming you were hired. The interview process can be especially disappointing for a UX Engineer. We’re often met with teams of Full Stack engineers who gang up on us to determine how much we don’t know about the stack. What good does knowing how to use Auto Layout in Figma do if you can’t even query a database?

Outlook

As an industry we should provide more support in UX Engineering. Even if there aren’t defined management positions leading UX Engineering in an organization; existing leadership should recognize this role and help define a path with folks that have these specialized skills; highlighting their abilities. These are the folks who translate design into code without looking at the inspect panel. If you don’t see the benefit of that; I’m afraid you really don’t know how the web works.

For my fellow UX Engineers out there, my heart goes out to you. I hope you’re being recognized for the work you’re doing; either by compensation, role, or fulfilling work. I wish I knew how to take the mask off. If you find out, please let me know.

Testing is hard

Fri, 19 Jul 2024 00:00:00 GMT

In my day job I code React components. React is a good solution to allow large teams to make significant applications fast and under a standardized set of rules. Without a library like React, the Javascript ecosystem would allow for many different ways of achieving a result. This makes it challenging for teams to gain traction.

However, it doesn’t make it great for doing very specific things. Even things that you might think should be easy. This is often my frustration with testing library components, along with using a library to test that library. Yo dawg, I heard you like libraries.

I’m using Cypress for testing as it has a solid API and makes assertions in a true browser environment. I’m also using Chai’s expect API to help with the assertion.

Asserting ref placement

One of the biggest annoyances of learning React is not manipulating the DOM like I used to in the jQuery days. The DOM is very powerful, and we’ve got lots of awesome APIs in the browser that do all sorts of things. But React doesn’t want you to use any of those. One of my biggest pain points was getting an element to programmatically focus. To do that in React, you may have seen something like this:

function MyInputWithButton(props) {
    const inputRef = React.useRef(null);

    function handleClick() {
        inputRef.current.focus();
    }

    return (
        <>
            <input { ...props } ref={ inputRef }/>
            <button onClick={ handleClick }>Focus the input</button>
        </>
    );
}

However, someone may want to supply their own ref. That’s where React.forwardRef() comes in. When we include this, things get more complicated.

const MyInputWithButton = React.forwardRef((props, ref) => {
    const inputRef = React.useRef(null);
    React.useImperativeHandle(ref, () => inputRef.current);

    function handleClick() {
        inputRef.current.focus();
    }

    return (
        <>
            <input { ...props } ref={ inputRef } />
            <button onClick={ handleClick }>
                Focus the input
            </button>
        </>
    );
});

We’ll need to merge the ref that we made, with the one that is potentially incoming from outside. There’s other ways of merging refs but the point is that you’ll need to support this possibility if you allow the user to supply a ref.

That’s all well and good. Now that we have this component in a library, how do we test it? Specifically, how can we be sure that the ref is assigned to the <input/> and not the <button/>?

This is exactly the problem I came across recently. A regression came in that caused that ref to be assigned to more than one element by accident. So we want to be sure that wherever the ref is meant to be assigned, it stays there.

If you’re familiar with testing suites, you may think that this would a test that works:

describe('ref assignment', function () {
    it('should assign ref to <input/>', function () {
        const ref = React.createRef();
        mount(<MyInputWithButton ref={ ref } />);
        expect(ref.current.tagName).to.equal('INPUT'); // FAILURE
    });
});

Unfortunately, ref.current is null when written this way. In all my searching online, I couldn’t find any examples of folks testing if a ref is assigned to the proper element. Luckily, ChatGPT saved the day with the following test that will do what we want.

describe('ref assignment', function () {
    it('should assign ref to <input/>', function () {
        const ref = React.createRef();
        mount(<MyInputWithButton ref={ ref } />);
        cy.get('input').then(([$input]) => expect(ref.current).to.equal($input)); // SUCCESS
    });
});

It seems that the secret is to first select the DOM element within the environment and after selection to assert that value against the ref.current. Hopefully, this helps anyone else trying to assure that refs are assigned properly. I’m going to be adding similar tests in places where we expose the ref.

Hover styles

If you thought that was fun, you’re going to love this next one. How might we test that styles appear on hover?

You might think it’s just a matter of triggering a mouseover on the element. However, that only works if we’re triggering some Javascript execution. If we’re trying to test that styles are applied on :hover using pure CSS, it’s not straightforward. There’s a plugin for Cypress called cypress-real-events that tries to help get closer to true events. This is done by hooking into the Chrome DevTools Protocol to trigger events, but even this isn’t helpful enough for what we want. From the project’s README.md:

Unfortunately, neither visual regression services like Happo and Percy nor plain cy.screenshot do not allow to test the hovering state. The hovering state is very different from any kind of js and css so it is not possible to capture it using dom snapshotting (like visual regression services do) and the screenshooting as well because cypress core itself is preventing hovering state in the screenshots.

The root cause of this problem is because hover is called a “Trusted Event”. This means no technology can directly trigger a native CSS :hover. The following is an excerpt from another post Simulating hovers in Cypress:

Events that are generated by the user agent, either as a result of user interaction, or as a direct result of changes to the DOM, are trusted by the user agent with privileges that are not afforded to events generated by script through the createEvent() method, modified using the initEvent() method, or dispatched via the dispatchEvent() method. The isTrusted attribute of trusted events has a value of true, while untrusted events have an isTrusted attribute value of false.

Most untrusted events will not trigger default actions, with the exception of the click event. This event always triggers the default action, even if the isTrusted attribute is false (this behavior is retained for backward-compatibility). All other untrusted events behave as if the preventDefault() method had been called on that event.”

The post has some workarounds, but none of them truly solve the problem as everything is still Javascript-centric. What we really need is to get that CSS style tied to :hover to show visually and be included in visual regression testing.

In my search for a solution, I came across a project for Storybook called Storybook Pseudo States and it claims to “force” your components to display pseudo states like hover. While I am currently using Storybook for local development, it’s not part of the testing suite. So I wanted to know what they technique was under the hood.

The file that is doing the magic is fairly overwhelming but there’s a simple way to think of what they are doing. You can even take a good guess at the file name (rewriteStyleSheet.ts). Here’s the basic steps:

Get a reference to the element we want to assert hover on.
Find the CSS that currently matches that element.
Rewrite the :hover selector to a non-pseudo selector.
Apply the non-psuedo selector to the element.
Profit.

There’s a lot that this addon is trying to cover past those steps. Seems like half the file is managing the :host selector found in Shadow DOM contexts. This may also depend on how you have styles applied to your components. For my environment, the styles are written into <style/> tags and there’s no Shadow DOM to worry about. This is what I did in my Cypress test:

function forceHoverSnapshot($target, ...screenshotArgs) {
    const HOVER_ATTRIBUTE_SELECTOR = '__data-cypress-hover__';

    // If our replacement stylesheet doesn't exist
    if (!document.getElementById(HOVER_ATTRIBUTE_SELECTOR)) {
        // Find the stylesheets that associate with the target
        const sheets = [...document.styleSheets].filter(({ cssRules }) => 
            [...cssRules].some({ selectorText }) => $target.matches(selectorText));
        
        // Concat all the cssText from associated styles
        const cssText = sheets.reduce((css, { ownerNode }) => css + (ownerNode?.textContent || ''), '');

        // Create and append new sheet
        const $sheet = document.createElement('style');
        $sheet.id = HOVER_ATTRIBUTE_SELECTOR;
        sheets.at(-1).ownerNode.after($sheet);

        // Append to replace instances of `:hover` with attribute
        $sheet.textContent = cssText.replaceAll(':hover', `[${HOVER_ATTRIBUTE_SELECTOR}]`);
    }

    // Add the attribute to the target element
    $target.setAttribute(HOVER_ATTRIBUTE_SELECTOR, '');

    // Screenshot
    screenshotArgs.length && cy.screenshot(...screenshotArgs);
}

I imagine this would be helpful as a plugin in the future if it hasn’t been done yet. Knowing this, you could opt to simply include a [data-hover] selector to the same declaration as :hover so it can be manually triggered. In fact, it might even make sense if you wish to present a “visually focused” state, typically used when keyboard navigating. For me, I don’t want to include code meant exclusively for testing in my production environment (👀 on data-cy on public sites) so the extraneous selector is out of the question.

So, that’s been the trouble with testing components recently. I know there’s been so many attempts at making testing our components easier over the years but sometimes it is an uphill battle for what seems like the smallest ideas that should have been tackled many times before. If I come across others, I’ll update this post. Good luck testing out there, it’s a battlefield!

Thanking you

Wed, 02 Aug 2023 00:00:00 GMT

The Clarity 2023 event site was just launched and folks visiting may notice that I’ve been chosen to speak at the event. In the following thoughts I’ll attempt to describe why I believe this to be one of my most important achievements in my lifetime and express my deepest thanks for the upcoming opportunity.

Community

I’ve been a part of large, worldwide, internet-based communities in the past. The Dance Dance Revolution (DDR) community found at DDRFreak was said to be one of the top ten largest phpbb forums at its peak. During my time there I was one of the most frequent users with over 14,000 responses across the forums. Eventually the moderators took notice of my helpfulness in the DDR Simulators forum; which aligned with my interest in custom charts at the time and made me a moderator of that forum; and later the New York forum. I introduced a “contributor” status which helped users add content to the site after moderator review. I was also heavily involved in planning DDR tournaments in the New York area; including the DigitalLife event held at the Jacob Javits Center in New York City for 4 years.

I mention this because I become obsessed with the community that I’m included within, and it shows. I love sharing ideas which improve our collective interests. I love helping people find the answers they need in areas where we’ve struggled previously. Talking to people without having to ramp them up with additional context gets to the root of the concept more quickly, and answers are more considerate when topical.

With the decline of arcades, the DDR community has since transformed into something different that my old body simply cannot keep up with. I still play for fun and exercise and highly recommend it if you’ve never tried. I thank the moderators and DDR community at large for the opportunity to play such a significant role in leading discussions and events over those years giving me the experience to lead future communities.

Lightbulb

I returned to college in 2012, after dropping out ten years earlier. One of the courses I was taking was meant to emulate a production studio. One of the facets of the course was to spread the word about the shows we were producing. I had experience building websites, so I took it upon myself to design and code the first version. One of the adjunct professors who was brought in was the founder of a media company and suggested that more people are watching on their smartphones. This meant that the site would need to be redesigned with this in mind.

This was my lightbulb and set me on my career path. The challenge that came with figuring out how to make content accessible to as many people as possible was engaging for me. I’ve always loved complex problems and attempting to create a solution which was as aesthetically pleasing as it was usable kept me deeply occupied in the practice.

I thank George Weiner who introduced me to responsive design.

Thinking in systems

I’ve written about my time as a UX Engineer before but, this is where I found the practice of designing systematically. In previous roles, I was in complete control of the look of the website. This was the first time where the experience of the product is separated by its features and in order to maintain a consistent appearance for users; a system of reusable design would emerge. I went on to learn more about the practice of the design systems here; soaking in all the information I could and learning from the folks who came before.

It was at this time that I attended my first Clarity conference in 2018. It was an incredible event with all of these folks facing the same challenges that I was. I knew these were my people. There’s truly too many people to thank here, and I continue to learn from this community everyday.

I thank Joe Schmitt for the original concept of Intents (semantic tokens) as well as Maëlle Gavet and Jenifer Stewart for accepting me as the first UX Engineer at Compass.

Speaking

Since being involved in the community I’ve been exploring solutions for systematic design strategies; how might designers communicate intention in ways past semantic tokens. This has taken me to write works such as Gridless Design and Complementary Space which aim to understand the reason why we make design decisions and how to break traditions for the sake of scalable, inclusive needs.

In 2022, UXDX asked me to speak on design systems at their annual UXDX conference in New York. This was the first time I was recognized outside my community as an expert in design systems. I thank their team for the opportunity and I highly recommend their conference.

Since then I’ve been on a few podcasts: the Design System Social Club, UX Untamed, the Design Systems Podcast, the Design Systems Field Guide, and Fuego UX. All of these have been engaging discussions about design systems in real time and I thank all of these folks for inviting me on their shows.

I’m looking forward to my first synchronous presentation about design systems at DSW Day online. I thank Maria Eguiluz for inviting me, for hosting DSW events for the past few years online and for an absolutely stunning post highlighting some of my achievements.

As mentioned at the top of this entry, I’m more than excited to be on stage at Clarity this year and want to thank Jina for the opportunity. It is at this point I feel like a true expert in this field that I devote so much effort to, able to sit at the table with folks I’ve looked to years ago.

Family

I most certainly need to thank my family for giving me the runway to have an art-adjacent career. Dropping out of college can be a concerning decision for parents but ultimately a path that put me where I needed to be. They still don’t understand what I do but that’s ok. They see the passion and that I’m living well on the results.

Finally, I thank my wife Jen for her support; the first to hear my convoluted design theories before they are fully-baked. While some folks don’t want to take their work home with them; I’m so incredibly lucky to be living in a design systems house.

The Daily Vibe

Fri, 10 Apr 2026 00:00:00 GMT

I vibe design/coded a design system in a few hours!

I see a post like this everyday on LinkedIn. In a world where AI is taking the industry by storm, it’s meant to show how powerful these tools are. But it also shows how little the industry understands about the work that goes into design systems.

Design systems are for people

This is a quote by Jina Anne and the word “people” is important. First, a design system is not for a single person. It’s the reason why none of the sites I create have a design system. They have reusable resources, but not a system. The reason why they don’t have a system is because many of my personal projects are built by a single person; me. I don’t need to communicate the do’s and don’ts with anyone else. Do I have pieces of design systems like variables and components? Yes, but these things do not immediately make a design system. What I’m missing is what I find to be the defining quality of a system: agreement.

To get agreement, you need to have people. People who have different opinions on design, the way things should work, the way we represent ourselves. This is where the role of a design system maintainer comes in. Are we experts in tokens and components? Yes, but the hidden role that we discuss as a practice is that of a diplomat. We need to be able to communicate with different teams, different stakeholders, and different people. We need to be able to understand their needs and their perspectives, and synthesize that into a system that works for everyone. This is not something that can be done in a few hours, or even a few days. It takes time to build trust, to build relationships, and to build a system that people will actually use. I could have the perfect typography ramp in my eyes, but what good is it if it isn’t adopted? At best it’s a proof of concept or something for my personal work, but getting people to agree on it and use it, that’s the hard part. That’s the beginnings of a design system.

So, if you made a styleguide for yourself in a few hours and that helps you visualize the plan for your project, that’s great! But I’d argue it isn’t a system unless you have stakeholders. People who can affect the decisions of the system, and people who can be affected by the decisions of the system. If you don’t have those people, then you don’t have a system. You have a styleguide, or a pattern library, or a component library, but you don’t have what I’d call a design system.

How to vibe a design system

Let’s say you want to really crack this nut. What does vibe creating a design system actually look like?

From my perspective, the goal is to get the agreement of the stakeholders and make that available as a reusable resource. What this means is you need some way of collecting the decisions of the organization into a central location which is later used to inform design and development work over product lifecycles.

One of the pieces to this puzzle is most likely some hosted MCP server. This allows your AI tool to connect to a central location where it can look up resources of the design system in order to make informed decisions. This is the new “docs site” so to speak, except it’s not meant for humans to read, it’s meant for machines to read. This is where the agreement of the organization lives and how AI tools would reference what the agreements are for the organization. The challenge from here only becomes getting the organization to connect to the MCP using their tool of choice. This is no different from what we do today, promoting use of the system.

The question is what does that agreement look like? Right now, there’s lots of talk about the DESIGN.md file popularized by Google’s Stitch project. This is a markdown file that is a hyped-up styleguide. It’s not a design system for the reasons we mentioned above. But it could be. If that DESIGN.md file was created by collecting the decisions of the organization, then that’s when it becomes a representation of a design system.

The final piece to the puzzle is what getting agreement looks like. I’ve always said that a design system is a reflection of the people who use it. This means that if the organization wants purple gradient buttons, then it gets purple gradient buttons. However, other organizations have design systems teams that operate with stone tablets, carrying down the agreements from high atop a mountain of design wisdom. They might have gathered feedback from the organization, but the final decisions are curated by the design system team.

In some of these cases, this is a good thing. This is the team responsible for making sure the resources provided by the system are of high quality and are consistent with the organization’s brand. In other cases, this can be a not-so-good thing. This can lead to a disconnect between the design system and the organization, where the design system is not actually serving the needs of the organization. This is where people outside of this team start going rogue, and where other decisions start making their way into the product without aligning to what was bestowed upon them. Stakeholders begin to take notice and might choose a side, defunding the design system because they are moving faster without it or because they vibed one up themselves. What’s so hard about making some color variables and a few components, especially now that generating them takes seconds? This isn’t agreement any longer, it’s just another vibe project gaining some temporary traction.

The way to vibe a system is to capture what the organization is doing and making that available as a resource. This is the modern button audit. Traditionally, a design system blossoms from roaming around the product, gathering the decisions that have been made organically, and then making sense of those decisions as a collection of resources for the organization to use. This is that reflection idea from earlier. In areas where we find things in conflict, we get to the bottom of it. We ask stakeholders, complete research, and come to some conclusion on what the path forward is so that we’re all on the same page. Generally speaking, the design system team are moderators of that debate. We typically have very little stake in the outcome, as long as the final decision is beneficial to users. This is where we find out if the organization wants purple gradient buttons or not.

So, what if the process of capturing the system was not a manual walk-around but a swarm of agents traversing the landscape of the product on a regular basis? As new decisions were made, they would be captured and considered a new design decision. This doesn’t necessarily mean that every small change is immediately a shared agreement, instead it provides a small amount of influence to how the design system evolves. As more people view other people’s decisions, they will themselves decide if that change they saw elsewhere is appropriate for them too. Now there’s two places where that decision was made, gaining more influence on the design decisions. More people see this new direction and start adopting it, further influencing the decisions. Before long, the design system is truly reflecting what we’ve all individually decided to do. A self-fulfilling design system that is truly a reflection of the organization, growing organically through the work that people are doing daily. This is the vibe design system, and it’s not something you can do in a few hours, but it is something that can be done with the right tools and the right approach.

Admittedly, I don’t know what that looks like from a technical perspective. What does the infrastructure look at, how does it capture the decisions, and how do you fine tune the amount of influence each morsel of information has on the design system? What does the process of a rebrand look like? Do you turn the influence up to 11 for a specific file? I know some products are claiming that they take your existing system into account when vibing, but currently they are looking at existing resources. I don’t think any system is looking at the product as a reflection of the system. But that’s exactly what they should be doing. It’s what the design system team has been doing, or at least trying to do.

So, if you want to make a vibe design system, get it to look at the existing product and make the DESIGN.md from that. That’s where the people are and their design decisions. Keep that up-to-date with how the people are working and the growth of the product. And the thing that you generated in a few minutes that you call a design system, it’s not. However, with a few people and some smarter infrastructure, it could become one.

The end

Wed, 10 Jan 2024 00:00:00 GMT

One of the concepts that bothers me about our practice is the amount of effort we put into tweaking designs. Where we only have a handful of designers visiting our products, we have thousands (if not more) of non-designers just looking to get something done. They aren’t thinking about how the button looks, they are hoping that it’s the last button click they need to finish a task.

After so many years and billions of websites, we should have a very accurate understanding of how people expect the web to behave. So it would make sense to have components that are the canonical standard for a certain experience. We have some of these already on the web, such as the native HTML <select/>. However, we often insist on knowing better. So we create custom versions of these with varying success. Maybe, we have too many items within that list and want to allow the user to more easily find options. There’s no native HTML element that handles this completely, so we’re invited to solve it for ourselves.

Global Design System

As mentioned in a talk and formally announced this week, Brad Frost is calling for a Global Design System. For folks who have managed design systems resources and reinvented wheels for several years, this seems like the obvious next move. An ultimate headless component library that only needs some values to present new expressions. The idea is taking what the Open UI Group is doing and truly standardizing it so we barely need to build interactive functionality from scratch again. The main work would then be mapping our brand expression (along with other design choices) to these existing resources.

Many of the skeptics of this idea are worried that the implementation of this system wouldn’t match their current ideas. From my perspective, I’m counting on that.

There are countless examples of poor UX. These are often reshared as good because some larger company has done it. I’ve spoken about this problem before. This is where we get <div role="button"/> and other highly questionable decisions. We often believe that our exception is justified when in reality we’re biased to our own beliefs about how an experience should behave. If we all agreed that a button should look like a button, act like a button, and legitimately be a <button/>, the skeptics have no platform. In fact, we’d probably already have a Global Design System because we would all agree.

But we don’t all agree and I think that’s because the folks that don’t also don’t have accurate data. Think of it like Flat Earth. Data is available that says <button/> is the best way, but folks who don’t know the data challenge that notion and veer in a new direction looking for a new truth that they claim works just as well.

So it would seem I’m a proponent of a Global Design System and I’d certainly be one. But I honestly think it’s too late.

A new kind of interface

I submitted a talk for Config last year which was about AI. At the time, AI was just emerging as the newest disruption in tech. While I certainly had plans to touch upon its upcoming impact in our daily work, I also wanted to touch upon the possibility of how we might consider the effects for the larger population outside of design. Remember, we design products for people; all people at best. So I wanted to explore what AI might mean for folks in their normal day-to-day. As you might know, I wasn’t accepted to present that exploration but as always actions speak louder than words.

There’s been some buzz at this year’s CES about AI, and much about a new company called Rabbit. I recommend that you watch the Keynote on their website, especially if you are a design systems practitioner. If you’re like me, you should have some strong opinions about what is next for us within the first few minutes.

The idea is that this technology has introduced the concept of a LAM (Large Action Model), which is meant to understand how user interfaces work and can execute tasks on them in the same way a person might. This means that there’s no need for a service to have an API to hook into, and no need to connect services together for chained commands. In this voice-activated experience, the end-user doesn’t even see the interfaces that are being worked on. They just need to confirm that the results were expected.

If you don’t understand what this means for us, I’ll make it clear. The introduction of LAMs could be the end of our practice as we know it. If the public only needs to interface using their voice to complete a task on your product, what the GUI looks like is meaningless. There is no value to the look if the user never sees it.

What do we do now?

This is the question we need to ask. Not, what’s the best design token naming convention? Or, how to support perfect nested rounding on corners? As a design systems expert, what expertise can I offer in the field of non-graphical interfaces? Personally, I don’t have an answer for this yet but, you can be sure I’m thinking about it.

Importantly, I also don’t believe this is a change that will happen very soon. VUIs are still in their infancy in comparison to GUIs. Interpreting natural language requires much more computational work than having a user choose to click a button. That process of identifying a user’s intention and translating it to an action on a customized interface that our brain would normally handle is now being handled by a LAM. This would mean that people would need access to that computing power and is not wholly accessible worldwide. The human brain currently requires fewer resources and has a better means of understanding, so it remains the primary actor in the field of user experience.

Another way to think about it is offloading the complexities of user experience onto systems, reducing the user experience to nearly zero. But what about those moments of delight, you say? Now experiences are lifeless! This is where art has been confused with design. The user experiences being targeted are task-based and tasks are commonly not fun. We’ve added moments of delight to make them feel like they aren’t tasks. Your product has been a necessary hindrance that you’ve made slightly more fun through small moments. However, this concept considers removing the tasks entirely. So the delight that the user is looking for is accurately not your product, but some hobby or IRL experience instead; like seeing art for fun. Imagine the amount of time saved planning a trip when you don’t get lost in the number of tabs you have open, doing cross-site comparisons, and trying to navigate the same data displayed in different ways because of branding or some other design bias. Time to spend doing things that are actually fun.

So, take a moment from color shades to think about the future. Our users will thank us for it.

Thinking Full Stack

Mon, 16 Mar 2026 00:00:00 GMT

A large part of the role for design system maintainers is to make things for your peers. This comes with having empathy for your organization and the people who compose it. Many organizations are composed of engineers that are jacks-of-all-trades. The idea of having a developer that can manage the front and the back-end seems very appealing to organizations. Especially since CSS is so easy, we don’t even need to test for it! 🫠

Enter the full-stack engineer. Where you work probably has a lot of them, some companies might even highlight “we’re all full-stack here” with varying degrees of prowess. As design system maintainers we are often adjusting our strategies to fill in the gaps of full-stack knowledge. The CSS skill that wasn’t assessed in the interview? Don’t worry, we have a design system for that.

In this post, I want to explain something to full-stack engineers that is often confusing: why can’t I just declare that the button is blue?

The button is blue

You get a mockup from your designer for a shiny new button. You look at the carefully crafted specifications and start coding. It’s just a button, so no worries about complex structure. But you know there’s probably a lot of states, so you’ll definitely be writing some CSS. If you’re lucky, your team is leveraging Tailwind which makes it easy to declare all of the styles right there in the structure. You don’t need to think of a container name for the styles, you can just say className='bg-blue-500' and the button is now blue. Perfect!

Some time passes and changes happen in the design. The button isn’t performing well so we need to change it. You get a new design and see it is just some color changes. You get back into those Tailwind classes and start making adjustments. Toggling states in Storybook, updating visual regression tests, and anything else that was affected by the update. It’s not as time consuming as when you first created the button, but it’s not a simple find and replace. You create the PR, get the sign off from your other team members and get the change in the deploy pipeline. Back to your regularly scheduled tickets.

Some more time passes and the head of marketing pings your team about a special promotion that we need to run for 2 weeks, which is cobranded with another partner. We need a few new pages made that have buttons but they need to look different than the other ones because they need to show this new cobranded presentation. It takes too much time to make a wholly new button, so you want to make some quick overrides to the original one for this special purpose. Again, you go through the motions of updating classnames, maybe even making a special “promo” variant because this isn’t the first time you gotten this kind of request. Now the button’s variants are getting numerous: primary, secondary, critical, info, highlight, promo. Each of them has slight differences, some of which we don’t even know if they are still being used. You get the change in the pipeline, and it’s ready for use in the promotional pages. The promotion was a huge success, and now we have to tear it down. It doesn’t make sense to go into the button and remove the code, I have more important things to take care of. We’ll write a ticket and put it in the backlog.

A new designer comes on board and is in charge of a fresh new look but they aren’t familiar with the current state of affairs. They’re exploring things in their design tool, and aren’t organized yet. They want to see how changes they make would look in real applications. You know we don’t really have a good way of doing that. Each design change has to be coded, tested, reviewed, and deployed. The process takes a while so it’s really hard to iterate on how a design decision could affect the current experience. All you could recommend is to try things in design and then you’ll make changes in the code to match. Luckily, you have some auto deployed Storybook that can give an idea of what things might look like, but we’ll never really be sure until it’s out in the wild. Even then, we might find oversights that we’ll require a rollback and re-release. All of it taking time away from more important infrastructure work that you were actually assessed on in your original interview.

Wouldn’t it be better if the person who wanted to make these little design changes could just do it themselves?

In the code

Let’s say you have the following JSX code:

function Button({ variant, ...props }) {
    return <button { ...props } className={ clsx({
        'bg-blue-500': variant === 'primary'
    }) }>
}

And you might say, toggling classes with clsx is old news, we use cva now. Ok, here’s the same thing with cva:

const button = cva({ variants: {
    variant: { primary: ['bg-blue-500'] }
} });

Under the hood, providing the concept of primary is still applying a declarative class that directly represents the blue background for the button.

But maybe you have a more sophisticated system. Maybe you have a global palette that’s type-safe and ensures only the colors that are meant to be applied can be used. Here’s how this might look using Panda CSS:

function Button({ variant, ...props }) {
    return (
        <button { ...props}
            className={ css({ bg: 'blue.500' }) } />
    )
}

In all of these cases, the person coding the button is ultimately in charge of the way it is presented. Sure, someone else told them to use bg-blue-500, but that will never make it to production and get in front of users without the developer interpreting that change in code. Even though they aren’t the person who made the decision about what color this should be, it is the developer’s responsibility to maintain the application of this color to the element. Every little decision that a designer, marketer, or other stakeholder might want is gated behind the developer.

In my view, the full-stack developer is not a stakeholder in the final presentation of the button. So it doesn’t make sense that they should have the responsibility of maintaining how it looks. Instead, we should provide some proxy that allows the decision from a stakeholder to be made by the stakeholder. Delegating the responsibility about the color of the button to the people who actually care what the button looks like. That leaves the developer open to tackle the engineering tasks that they were trained to do.

So, how could we let a stakeholder apply the color they want to these buttons? We’d need some way of allowing their decision to be restricted to only design properties, and ensure nothing else is affected. We can’t just make this another prop. Props are used by developers so other non-developers won’t use them. We need a list of all the design decisions that we expect stakeholders want to change, and allow them to assign values to those in some curation exercise. Then our components could look up the values they assigned and apply those assigned values to the associated properties.

New naming

Ok cool, so let’s try using what we have to make this. First we set up some list that people can use to change the values that are assigned. Let’s assume we have some UI that allows stakeholders to make updates to it. It could be a simple spreadsheet or a more robust interface:

{
    "blue": {
        "500": "#006be6"
    },
    "orange": {
        "500": "#f97316"
    }
}

Since our components are already using this, we don’t need to change anything there. Sounds good! Except until the button needs to be orange. Since the button has blue.500 assigned, we’d need to go back into the button to change it to orange.500. That’s not what we want because going back into the button’s code is a task for the engineer, and only the engineer. We need some way of having the decision to change from blue to orange for the button to be represented here.

Why not have the system describe the element and property being affected? Something like button.primary.bg and button.primary.text. That way the person who is trying to update the color knows what it’ll affect, and the person assigning that variable knows where to place it. They don’t even need a design mockup to figure out where this goes. The place where it goes is right in the name. It makes it clear to everyone on the team what this thing is meant to represent. Let’s update our things:

{
    "button": {
        "primary": {
            "bg": "#006be6",
            "text": "#fefefe"
        }
    }
}

This can be represented in some UI that makes it clear these are the colors for the primary button’s background and text so that a stakeholder can change it whenever they like. Now, the developer just needs to read from these new values:

function Button({ variant, ...props }) {
    return (
        <button { ...props} 
            className={ css({ bg: 'button.primary.bg' }) } />
    )
}

What we’ve begun to introduce is called a “semantic” naming strategy. Using this, we describe what is going to be affected so that someone else can provide the value in the pipeline. This relieves the engineer from looking up or maintaining the presentation of the button and make it an exercise for folks that are more responsible for those decisions.

Those visual regression tests? Now those tests happen before the list is published. We can know how the colors are meant to be used before they hit the components. We can check for contrast, create an alpha set for testing in real parts of the application. Separating the concerns balances the responsibility of the team.

Trust the process

When a full-stack engineer first starts using a semantic naming strategy, they might be uncomfortable because the decision about what color the button is no longer belongs to them. It is delegated outside to another person. What if they choose the wrong color? Why does the button suddenly look weird? People are going to think it’s my fault and I did something wrong. These are all valid thoughts to have when encountering a new paradigm. New ways of approaching something that has been the same way over years is concerning.

You must be thinking, why doesn’t Tailwind’s default approach lean on semantic naming? The answer is because the scenarios I’ve described above don’t happen often, but when they do the pain is felt. When you first put bg-blue-500 in your code, you don’t think about the future. Of course not, you are thinking about pushing this code right now. Changing this code is your future self’s problem. Tailwind isn’t preparing you for the future, it’s preparing you to ship right now and that’s often what matters. However, the reality is that without a semantic layer, it can’t easily account for iterations, experimentation, and stakeholder requests. Maybe you don’t have these, so you’ll never need to revisit the button.

But when you do receive that ticket to change the button’s background color, the answer isn’t to dig back into the code. It’s to make sure the right person can make that decision without ever needing to ping you. That’s empowering your team to express their creativity while you get back to your own expertise.

Tiny toggle

Tue, 05 May 2026 00:00:00 GMT

Over at the Design Systems House website, I made a small toggle for light and dark mode. While there’s an abundance of posts describing this, I didn’t find any that made it into a compact script of a few lines. Here’s how I did it, and some additional considerations to keep in mind.

The script

This is all the JavaScript that makes the toggle work:

const LOCALSTORAGE_KEY = 'dark';
const $toggle = document.getElementById('toggle');

const { matches } = window.matchMedia('(prefers-color-scheme: dark)');
const stored = window.localStorage.getItem(LOCALSTORAGE_KEY);
$toggle.checked = stored !== null ? stored === 'true' : matches;

$toggle?.addEventListener('change', (ev) => {
    window.localStorage.setItem(LOCALSTORAGE_KEY, String(ev.target.checked));
});

This assumes that there is a <input type="checkbox" id="toggle"> element in the HTML. Let’s go over the lines:

We define a constant for the localStorage key.
We get the toggle element from the DOM.
We check if the user has a preference for dark mode using matchMedia.
We check if there’s a stored value in localStorage
We set the toggle’s checked state based on the stored value or the user’s preference.
We add an event listener to the toggle.
When the toggle changes, we store the boolean value as a string in localStorage.

Importantly, we assume that the initial presentation is “light” and explicitly look for if there’s any setting for “dark”. The first thing we look at is if it was set as “dark” for this site using the toggle from a previous session. If not, we check what the OS preference is. This is setting the initial state of the toggle element, being checked if “dark” is picked up from either of those conditions. Then we listen for changes to the toggle and only update the localStorage value when the toggle is changed. This overrides the OS user preference when set.

The styles

Now with the baseline :has() selector, getting this to behave is pretty easy with a single selector to introduce a new expression:

body:has(#toggle:checked) {
    /* dark mode styles */
}

This is a very simple way to apply styles based on the state of the toggle. The :has() selector allows us to check if the toggle is checked and apply styles accordingly. This way, we don’t need to add any additional classes or attributes to the body element to indicate the current mode. We can just rely on the state of the toggle itself.

About system settings

When I initially made this kind of toggle for light/dark, I thought about it differently. Instead of light/dark, I wanted to toggle between “system” and “opposite of system”. In other words, if the OS was set as “dark”, the toggle would then either align to what was set in the system or be the opposite when toggled. Visually in terms of presentation, there would be no difference. If your system was set to “dark”, then by default the site would be dark. If your system was “dark” and you wanted this site to be “light”, you would switch to the “opposite of system” option.

This helps avoid the problem of setting a specific flag on the site once set. In the implementation above and at ds.house, once we store the state expected by the user for the website, there’s no way of resetting it back to the state of not being set. It’s either “light” or “dark” (or false/true in the code). With the “system” and “opposite of system” approach, you can always reset to “system” to align with the OS preference. In this way, setting false is the same as not setting anything. This is a nice way to allow users to easily reset their preference without needing to clear localStorage or have a separate “reset” button.

There’s a few problems with this, one of them being that I could never figure out a good way to explain this setting. “System” as the default is fairly straightforward, but “opposite of system” is a bit more difficult to understand. The other problem is that it doesn’t really align with the mental model of how users think about light/dark mode. They think in terms of light and dark, not “system” and “opposite of system”. So I went with the more straightforward approach of just toggling between light and dark.

If you’d rather use a <select> instead of a <input type="checkbox">, you can modify the script to accommodate that by referencing .selected instead of .checked in the appropriate places. Just make sure your HTML has matching values for localStorage and the options in your <select>. You might want this if you want to expose “system”, “light”, and “dark” as options. Kilian Valkhof recommends having all three and Bramus Van Damme explains the different possible levels of setting this information.

Knowing your audience

If you’re wondering why I opted to not expose the “light”, “dark”, and “system” options at ds.house, it’s because no person is spending a signficant amount of time on that website. Enough that they’ll visit everyday to be productive. Setting whether or not “light” or “dark” is right for this person is most likely a one-time thing specifically for a single visit. It is unlikely that a user will want the presentation of this site to change over the course of a day, unlike productivity applications like email clients where you’ll visit multiple times a day. Those experiences will expect smarter customization options.

For a small website that gets a visit every once in a while, keeping it simple might be the better approach. But it’s important to know the tradeoffs. And if you ever come up with a good word for “opposite of system”, do let me know.

Title goes here

Wed, 20 Dec 2023 00:00:00 GMT

Naming is clearly something I think a lot about. So when I saw this tweet from Nathan Curtis about the way Shaun Bent and his team at Spotify handle component composition has named slots, I was triggered. Hot takes activate, here’s the image from the tweet:

Pretweet

There are several words in here that suggest position. For this exploration, I’ll focus on the title area, specifically the areas above and below the title slot. The team has chosen the words pretitle and subtitle for these areas, respectively. Seeing this, I went through the following stream of thought:

Initially, I’d expect that the concepts should match. In other words, choose either pre/post or super/sub. There’s awkwardness in both choices. Choosing the former pair will result in a double-t (posttitle) while the latter pair will result in a suggested size of the title from the name (supertitle).

I’ve recently adopted the concept of “overline” from Material Design for the area above headlines. While it might work using the word title (eg., “overtitle”, “undertitle”) it wouldn’t for other typographic terms as we may end up with a very confusing “underline”.

Which is where I decided I couldn’t just reply to the tweet. I’m now conflicted about what I would name these areas so that they are clear to their purpose and relate to the title component appropriately. We need to go deeper.

A Page from Page Layout

The parts we’re identifying here are from the anatomy of page layout; the arrangement of visual elements on a page. There’s a handful of parts that we should first address that could help us here:

Headline

This is meant to be the most important element in the layout. As such, we expect this to have the largest font size and/or most ornate font style to capture the reader, along with its compelling content to continue traveling down the path it introduces.

Deck / Kicker / Intro / Stand-first / Lead / Lede

This often summarizes the article and appears directly after the headline. It is meant to further engage the reader to move forward in the reading experience. In terms of treatment, we expect this to be smaller than the headline, but larger than the body copy. Due to the nature of there being multiple words to describe this idea; there are also many variations of expectation for this in terms of length and content.

Subhead

There’s some disagreement in the research I’ve done that identifies this element. In some examples, this is a synonym for deck but for others, it is specifically meant to break up large chunks of text.

Drop cap

This is often the first letter of a chunk of text but can sometimes be longer than this. It is stylized to be larger than the rest of the body copy it is associated with. We have ways of achieving this using CSS pseudo elements such as ::first-letter and ::first-line.

Byline

This is specifically the line of text that identifies who wrote the piece. It is used mostly for authors writing articles and begins with the word “by”.

Dateline

As you might expect, this is meant to present the date that the piece was reported however, according to Wikipedia, it also describes where and when the story was written or filed, though the date is often omitted.

Caption

This is text used to describe accompanying media such as images, photos, or illustrations. We will also see captions in media outside of page layout such as video in the form of closed captions. While we expect this text to be smaller than most body copy, it must be still legible. Importantly, captions are also subtitles that include a written description of other elements in the media.

Folio

This is meant as metadata about the piece, often including the publisher’s name, page number, or year of publishing. This is often in the corners of printed pages in a smaller and less distracting typographic treatment.

Running head

This is meant to connect a story over multiple printed pages. On the web, this is less apparent as we have ways of allowing the headline to remain on an infinitely scrolling page.

Pull quote / Call out / Billboard

This is meant to highlight a particular topic or mention from the existing body copy. It is often displayed inline within the layout with a more engaging treatment, either by size or style.

Disambiguation

Many of these are often used interchangeably and have more meaning. For example, the difference between a headline and a title. From the English Language Learners Stack Exchange:

“Headline” is normally used when an article appears as one of a collection of articles, such as a newspaper. If the article is reprinted separately, the headline becomes the “title”.

Another description of this difference is by the Content Authority, providing this table of examples:

Headline	Title
How to Improve Your Writing Skills	10 Tips for Better Writing
Why You Should Drink More Water	The Benefits of Staying Hydrated
Breaking News: Earthquake Hits California	7.1 Magnitude Earthquake Rocks Southern California

In HTML web pages, the title is a metatag meant for the <head/> of the webpage and is displayed outside of the content area of the webpage; either in the browser window or tab area. Meanwhile, the idea of a subtitle could be confused for the use within captions.

Purpose not position

You may have noticed that much of the descriptions above do not suggest the element’s position in the layout, but rather its purpose. This is the reason why the original tweet was so triggering for me. When we provide an API that is driven by placement, it allows different variations of lockups to emerge because the person supplying the content is less likely to truly understand why they want this treatment. It becomes much harder to have a consistent presentation of these elements.

That is why when we create a component like this, we should be preparing it by purpose. This will ensure that what the designer decides is done by intention. Where it is finally displayed is a separate layout exercise. As an example, in magazine layout, an article’s author does not have authority over the folio position. Less artistic articles may also have more restrictions on other elements such as the style of headline, deck, and body copy. This keeps the presentation consistent across the publication and readers become more familiar with the presentation; making it easier to read.

Going back to the original example at the beginning of this article, I’d now recommend the following based on the above:

Headline slot
Lead slot
Media slot
Caption slot
Body slot
Folio slot
Callout slot

I’ve omitted the leading and trailing areas specifically because the names do not suggest purpose, only position. In other words, what is supposed to appear in these spots? If the answer is “anything you want”, that’s not systematic. One person could decide that the icon is meant to appear on the left while another expects that same icon on the right.

As a practical example, the button component I’ve designed allows for an icon prop which only appears before the button’s label. The only way to have an icon appear after the label is for special purposes. For example, showing a caret when the button is meant to host a disclosure pattern.

<Button icon={ <Star/> } as='disclosure' />

With this API naming scheme, we can create several kinds of lockups. We could have a <ListRow/>, <MediaCard/>, <Hero/>, or any other component which expects a hierarchy of content. We could also have different layout options specific to each once each of these is well-defined. Ones that allow the folio to appear above the headline as an example. The exercise of determining where each one of these elements goes should be separate from the exercise of curating the kinds of elements that need to appear and their content. In fact, designers often aren’t curating the content here. The decision about which kind of lockup to use might be the only decision required in some cases; such as widgets of a CMS.

The opinion about where these elements should appear or how many variations exist should be influenced by the designers interested in these layouts but ultimately consolidated by design system governance to align on a common shared language by intention. Designers must articulate their needs past ego and identify how their choice is targeting a user’s need. That then informs this new API.

Overall, I continue to recommend naming things with purpose.

Token operations

Wed, 31 May 2023 00:00:00 GMT

I have been revisiting the infrastructure which supports themes at my day job where the number of tokens has exploded into the hundreds; thousands if you count the possibilities of defining custom ones for special needs. This makes the token curation process unwieldly when theming because assigning values to over 500 semantic tokens is very tedious.

The trouble is that while a certain brand or theme might have a few base values which give it personality, the final collection of tokens to define a theme will require slight variations of these base values for a properly curated presentation.

What if we could instead allow for a few values to be set in a theme to inform the rest of the values in some specified way?

Operations

First suggested within the Design Tokens Community Group by Jerome Farnum we could consider a special key on the specification that expects an order of operations to be performed (example from James Nash):

{
  "some-token": {
    "$value": "#ff0000",
    "$type": "color",
    "$operations": [
       { "hue": -20 },
       { "alpha": 0.3 } 
    ]
  }
}

This is a good start but I saw two major flaws with this approach:

Freeform naming

The words hue and alpha are meant to reference some external function that must exist in the token processing in order to transform to a final value. The algorithms used to determine the final output might be different or not exist at all. Each vendor must implement their own hue and alpha functions in order for these to be useful. This would require the specification to outline every kind of possible transform a theme author might want to use.

Custom functions

Furthermore, theme curators could be interested in creating their own custom functions which would need to be executed in vendors’ processes. In this format, there’s no clear way to define this. We can’t even support multiple arguments in the current suggestion.

Step-by-step

The solution I have for this is to implement a low-level language that can be built upon to make more complex functions. Here’s an example of what a token file could look like with a new take on $operations:

{
  "primary-color-overlay": {
    "$type": "color",
    "$value": "#fffc00",
    "$operations": [
      0.5,
      ["String.match", "$value", "#([0-9A-Fa-f]{2})"],
      ["String.match", "$value", "#(?:[0-9A-Fa-f]{2})([0-9A-Fa-f]{2})"],
      ["String.match", "$value", "#(?:[0-9A-Fa-f]{4})([0-9A-Fa-f]{2})"],
      ["Math.parseInt", "$1", 16],
      ["Math.parseInt", "$2", 16],
      ["Math.parseInt", "$3", 16],
      ["String.concat", ",", "$4", "$5", "$6", "$0"],
      ["String.concat", "", "rgba(", "$7", ")"]
    ]
  }
}

See minimal prototype in action.

The $operations key is still an array which is necessary to ensure we can have a sequential step. The first concept is that each item (except for the first in this example) is an operation. It has the following signature:

["OperationReference", "argument1", "argument2", "argument3",...]

The first item in each operation array references some well-known function that can be implemented across token processing tools and vendors. For this to work, I believe we’ll need at least String and Math with a few additional methods to support standard operations (eg., Math.add). This is something that can be included in the tokens specification if agreeable.

The result of each operation is stored in a special variable reference related to its index in the operations array. In the example above, the first operation (defined at index 1) result is stored at "$1". This result is used as an argument in the fifth operation (the first to use Math.parseInt above). Primitive values in the operations array are simply stored as results to the index. Here’s the example again, with comments marking how results are stored:

{
  "primary-color-overlay": {
    "$type": "color",
    "$value": "#fffc00",
    "$operations": [
      0.5, // 0.5 stored at $0
      ["String.match", "$value", "#([0-9A-Fa-f]{2})"], // 'ff' stored at $1
      ["String.match", "$value", "#(?:[0-9A-Fa-f]{2})([0-9A-Fa-f]{2})"], // 'fc' stored at $2
      ["String.match", "$value", "#(?:[0-9A-Fa-f]{4})([0-9A-Fa-f]{2})"], // '00' stored at $3
      ["Math.parseInt", "$1", 16], // 255 stored at $4
      ["Math.parseInt", "$2", 16], // 252 stored at $5
      ["Math.parseInt", "$3", 16], // 0 stored at $6
      ["String.concat", ",", "$4", "$5", "$6", "$0"], // 255,252,0,0.5 stored at $7
      ["String.concat", "", "rgba(", "$7", ")"] // rgba(255,252,0,0.5) stored at $8
    ]
  }
}

This would also include a special $value which refers to the original token value.

One of the larger benefits to this approach is that the low-level set of operations don’t receive a name, which avoids contention about naming of operations from within the specification (ie., should it be opacity or alpha). Names would only be needed when sharing sets of operations between token authors.

Reusing common operations

Clearly, we would not want to write all of these operations in order to apply opacity to a given token each time. We’ll need a way to reference a set of operations. This could be supported by allowing an import syntax within the specification. I’ve suggested this idea before in the community group. It could look like this for operations:

{
  "primary-color-overlay": {
    "$type": "color",
    "$value": "#fffc00",
    "$operations": [ 
      // All items after the import are used as arguments for the nested operation in order
      // 0.5 stored at $0 for @token-operations/hex-opacity operations
      ["@token-operations/hex-opacity", 0.5 ]
    ]
  }
}

In the above example @token-operations/hex-opacity is completely arbitrary and could be any package registry or url that has an array as the export. The expectation here is that folks might write projects that abstract low-level collections of operations into more user-friendly exports. This is similar to the purpose of the Lit framework for component authoring; to make web component development more accessible with a level of abstraction.

The special sauce would be within the operations parser. Since the first argument in an operation is meant to be a reference to a function (eg., String.concat), we could also check for a potential file to import here or have some other special syntax. The result would be to inject the operations array related to this reference in place as a nested operation with its own scoped step indicies. The trailing arguments of the import are then placed in the beginning of the imported operation set since each curated operation has an expected signature.

{
  "primary-color-overlay": {
    "$type": "color",
    "$value": "#fffc00",
    "$operations": [
      // First level of operations
      [
        // Second level of operations (nested), final output returns to parent operation result in place
        0.5, // First argument after import operation, placed at $0 in nested operation
        ["String.match", "$value", "#([0-9A-Fa-f]{2})"],
        ["String.match", "$value", "#(?:[0-9A-Fa-f]{2})([0-9A-Fa-f]{2})"],
        ["String.match", "$value", "#(?:[0-9A-Fa-f]{4})([0-9A-Fa-f]{2})"],
        ["Math.parseInt", "$1", 16],
        ["Math.parseInt", "$2", 16],
        ["Math.parseInt", "$3", 16],
        ["String.concat", ",", "$4", "$5", "$6", "$0"],
        ["String.concat", "", "rgba(", "$7", ")"]
      ]
    ]
  }
}

The purpose of this is so imported operations can be chained while maintaining the positional references for each step. In other words, we want to maintain the meaning of $0 related to the rest of the steps in place.

In this way, as long as token processors include the low-level operational functions and the standardized way to execute them, you can define any kind of transform you need right within the token file.

Tokens as intents

Thu, 12 May 2022 00:00:00 GMT

There are tons of definitions of design tokens on the web. Enough that I won’t link to them here and you can find your favorite one with a web search. Many of the examples of design tokens show a relationship that looks something like this:

color-blue-500 ⬅ #0000ff

Here, there’s a name that represents the value. The naming in this example indicates a few things like the category (color) then a family within the category (blue) and finally a way of showing a relation between similar tokens of the same depth (500). This was well advertised through the material design color palettes.

The immediate problem

Now let’s say we design a button, and we want to give it an accent color from our palette. Maybe this is also our brand color and used for a few other marketing items as well.

.btn {
  background-color: var(--color-blue-500);
  color: var(--color-white);
}

Seems harmless. That is until you get a message from marketing and the brand colors are changing. What do you do? You might think a quick fix would be to do this:

color-blue-500 ⬅ orange

Because color-blue-500 is the brand color, it’ll update in all of the spots. Clearly this isn’t a good approach because the name no longer matches the value.

Instead you’d have to update all of the places where the brand color was used.

.btn {
  background-color: var(--color-orange-500);
  color: var(--color-white);
}

Oh wait, is that white accessible on the orange? That might need to be updated too!

.btn {
  background-color: var(--color-orange-500);
  color: var(--color-black);
}

As you can see, you’d be combing through existing assets; looking for areas that need to be updated and never being sure you’ve gotten everything. We need a better system and you can probably give a recommendation already. Let’s change the mapping to the following:

color-primary ⬅ orange

Now, I can use that name without worrying about the value.

.btn {
  background-color: var(--color-primary);
}

It doesn’t yet solve the relational colors (ie., the text color) but we’ll get there.

Provide intention

The concept that I’m describing is not new. It is a token naming approach that attempts to loosen the description of the value by providing more meaning. Nathan Curtis lands on this idea through an exploration of other systems’ naming conventions without explicitly calling them more than design tokens.

What Nathan calls concepts in his post is the basis behind the naming convention that I’ve been calling intents since 2017 which is a term coined by Joe Schmitt. The idea is that the token name should describe an intention, not the value.

As a designer, I want to place a button inside of a card. What kind of button should go into that card? I don’t mean what color or font size, I mean what kind of button. When we design an interface we are making decisions about the kind of thing to use that is expected to help the user move forward. We decide to use a primary button because we want to draw the user’s attention here first before any other action. The kind of button is primary due to its priority and the decision I’m making is an intent. We can separate the intent from the styles we associate with that intent.

Another example would be an alert banner. Which banner should I use to show your credit card is about to expire? I’m not looking for the orange banner, I’m looking for the warning banner. I intend to describe to the user that this message is a warning. If you think in this way, the style of the warning is not important. It’s the decision about how we expect to convey this message that is important.

If you fully adopt this approach, this helps by teaching the user similarly styled things have the same behavior. It’ll be easy for a user to identify all primary actions or warning statuses because they have the same treatment (or have the same intent) across uses.

To be clear intents are tokens. They just have a special purpose in the ecosystem.

A new system of naming

If we use the intent based naming system, the mapping might have an assignment like these:

feedback-warning-surface-color ⬅ color-orange-500
feedback-warning-onsurface-color ⬅ #fff

Notice that the right-hand side can be a raw value or some other variable. It might help for these to be reusable variables like color-orange-500 because you might reuse this value is other places. What matters is that the intent name (the left-hand side) does not change.

Those intent names are describing parts of the experience where we intend to show a warning by using a background color and a foreground color. When you set an intent as a component property value, this is effectively a marriage. It should never change.

Now we can use the feedback-warning-surface-color in places of the experience where we intend to show a warning. These areas will not change their intent! We will always show a warning here, even if we style it differently later.

.alert-warning {
  background-color: var(--feedback-warning-surface-color);
  color: var(--feedback-warning-onsurface-color);
}

With this system, you are able to support any variation of theming; light & dark mode, brand changes, private labeling, etc.. All you need to do is store different mappings of values to intents (aka. theme). Maybe in one theme, warnings need to be shown in red. In that theme change the mapping for warning backgrounds to red.

feedback-warning-surface-color ⬅ color-red-300

You’ll never need to go into the components to make a change as long as we use intents to describe the styles. Just make a new theme and give the experience a new look.

Recommendations

I’ve have a few years of experience with this approach and want to document some of the pitfalls to avoid when implementing.

Avoid the words light and dark. You might consider trying this for buttons that appear on inverted backgrounds. Instead, I recommend setting an inverted theme within that container so it can cover all of the possible treatments within. Remember, it’s probably not just the button that needs to be inverted, there’s probably text or input fields that might need coverage too. If you really need to show a relationship use the word “contrast” instead.

Make naming relative to the page styles. I recommend a very generic category called “box” which in its simplest form describes the <body/> styles.

box-background-color: The <body/> background color.
box-foreground-color: The <body/> text / icon color related to the background.
box-border-color: The most common border color for boxes which will share the <body/> background color.

In my experience there might be another kind of container that is meant to show a visual difference from the body background. I tend to name this boxLowContrast because it is still relational to the <body/>. If you have more variations that this, you’ll have to get creative with your naming here. Remember, this is for generic non-interactive containers. You can have additional categories for more meaningful containers.

Doing this allows you to keep in the mindset of a theme when completing the mapping.

// "light theme"
{
  "box-background-color": "#fff", // white
  "box-foreground-color": "#000", // black
}

// "dark theme"
{
  "box-background-color": "#000", // black
  "box-foreground-color": "#fff", // white
}

Start with generic categories. A component is not necessarily an intent. You can consider a tab to be a part of an actionable category. Perhaps dive a step deeper into a navigational category. However, I would not recommend making a “tab” category.

action-background-color: Generic, describes all interactive element backgrounds.
navigation-background-color: More specific, describes all interactive element backgrounds which are meant for navigation.
tab-background-color: Very specific, only describes the tab background color.

Here are some categories that have worked well in the past:

box: Describes generic non-interactive containers, eg. <body/>.
action: Describes interactive containers, eg. <button/>.
navigation: Describes interactive containers for the purpose of navigation, eg. <a/> (link).
control: Describes interactive containers for the purpose of inputting information, eg. <input/>.
feedback: Describes non-interactive containers for the purpose of indicating a system state to the user, eg. banners, badges, notifications.
figure: Describes the use of color meant to segregate entities, eg. data-visualizations, illustrations, default avatar colors.
text: Describes all use of typography, more on this later.

The feedback and figure colors are unlike the others. For the feedback category I recommend the following set of properties.

feedback-[type]-surface-color: Describes when the background is used to indicate the status through color. This is meant for banners that use the background as the color accent.
feedback-[type]-onsurface-color: Describes the color to use for elements that appear on the feedback-[type]-surface-color such as text and icons.
feedback-[type]-foreground-color: Describes when the text is used to indicate the status through color. An example of this might be error text underneath an input field. This color is related to the box-background-color in terms of contrast and application.

A caveat here is that if you attempt to put more complicated experiences within a container which has feedback-[type]-surface-color, the related feedback-[type]-onsurface-color will have difficulty applying coverage to the elements within. The recommendation here is to keep the feedback to text and icons only.

The figure category is the least well understood. The best way to curate this is to order the colors by expected popularity within coloring illustrations. This is also a good area to consider having more specific categories if necessary. For example, if the colors used for illustrations are different from those being used within data-visualizations. Otherwise I just number these to indicate popularity.

figure-color-1: The most used color within illustrations (other than box colors).
figure-color-2: The next most used color within illustrations.
figure-color-3: …and so on.

I’ve avoided trying to describe intents for the purposes of marketing because decisions of color there are often based on associated with given photography. In these areas you might opt to actual hard code the color because of the close association with the surrounding material and not necessarily with the overall page. Another recommendation might be to just have the following intents to only be used in places where the brand should be highlighted and not for areas with better intents.

feedback-brand-surface-color
feedback-brand-onsurface-color
feedback-brand-foreground-color

Create additional variations to each category as necessary or potentially extend variations to others. For example we can imagine that all interactive categories will require a “hover” variation. Which would mean the following intents may exist:

actionHovered-foreground-color
navigationHovered-foreground-color
controlHovered-foreground-color

Remember to cover all of the possible states that your interaction might have.

One more note, if you are using focus rings, I recommend associating the ring with the box category because the ring visually appears on the box, not on the interactive element. As you might expect, having the same focus treatment across all interactive elements will be best and having it associated with the box category makes this easy to maintain. This would also go for shadows, although shadows have much more to do with light cast rather than a theme and could be avoided altogether.

Typography

I’ve mentioned in the recommendation that there should be an entire intent category dedicated to text. This is meant to have the same approach where each kind of text is identified based on purpose. Here are the variations that seem to work best.

Heading: Meant for large titles.
Title: Meant for small titles.
Action: Meant for text within interactive elements.
Input: Meant for text within text fields.
Caption: Meant for text providing additional detail, like help & error messages.

This isn’t including the default category. So you’d see the following in a theme:

// default theme
{
  "text-font-weight": 400, // body font weight
  "textHeading-font-weight": 700,
  "textTitle-font-weight": 600,
  ...
}

Clearly, this method doesn’t support different levels of content hierarchy with just this collection of tokens alone. To do that you could either base the type scale on density (as is done here in the damato.design family of sites.) or use the given font size as a base to compute additional font sizes using a set scale. That’s an explanation for another post.

And beyond

From here you can include additional properties to each category or even add categories as your organization needs. Here within the damato.design system we have identified border-size, border-curve, and density-size as additions to the box category to describe those features.

Truly Semantic

Tue, 07 Nov 2023 00:00:00 GMT

Off the heels of my talk at Clarity this year I omitted a few concepts that could have been included but may have detracted from the focus of the talk. One of these was the qualities that make a token truly semantic. I’ve had many arguments in the community regarding tokens that are or are not semantic. So the purpose of this article is to be clear about which tokens are best used directly in the experience from other tokens that can be used for organizational purposes.

Semantic tokens do not suggest values

This is an image from the Mise en Mode talk, which begins to introduce why space is not semantic in most systems.

The semantic token button-bgcolor does not give any indication of the color that is meant for this token. While a token color-blue-500 suggests that the color meant for this token is a blue, perhaps in the middle of other blues within a scale. This is an important distinction because we want the ability for these tokens to change based on outside factors; a common example being light mode and dark mode. However, we are not just limited to these user preferences. The color can change based on branding, localization, or expressiveness. It would be inappropriate to change the value of color-blue-500 to an orange, which is why we instead use and change button-bgcolor because it does not suggest the value.

I suggest that we ultimately do not need tokens that aren’t semantic functionally in our ecosystems. However, the reason why a token like color-blue-500 exists seems to be for human discourse. It is easier for people to speak about a color in a human-readable way than a color code. It also restricts the number of possible colors to use so slight variations of the same value do not appear accidentally.

Semantic tokens are generic component tokens

This was one of the images that didn’t make it into the Mise en Mode talk:

When you are in the process of identifying what semantic tokens to include, you should aim to keep the number of tokens low. This helps with token management but also ensures that ideas are consistent across the experience. As an example, I believe that items that you can click should be given similar treatments so a user learns these are the clickable areas. If we were to provide different treatments to these components, the user may miss options because the treatment is unique.

In this way, I like to create categories of components. For example, all components where we expect a user to provide input to the system could be called “control” components which would suggest a family of tokens that are meant to style controls similarly. From here, we would get semantic tokens such as control-borderColor which might describe the <input/> border.

While you could become more specific, this tends to cause treatments to be more unique. As an example, would you expect textInput-borderColor to be different from checkbox-borderColor? Probably not. So the exercise of identifying similar atomic components is important to determining your semantic token set. These similar components are grouped into generic categories (eg., non-interactive surfaces, actions, controls, etc.) which form the foundation for your tokens.

A good exercise to determine what your semantic tokens could be is by reviewing low-fidelity wireframes of your experience. Because these are meant to describe the pure functionality of the experience, without any additional noise of possible expressions, we can identify the most critical parts of the experience. Then we put those elements into categories based on their purpose in the experience. That purpose is the intention; the semantic meaning for why they exist here.

Semantic tokens are not dependent on each other

This is the “smedium” problem. A semantic token can be added or removed from the ecosystem without having to rethink other tokens within the same category. On the other hand, if you have a token called space-sm and another called space-md, you’ll be unable to introduce another token between them without introducing something unexpected and not systematic. So a good rule of thumb is that semantic tokens do not include a scale. The scale suggests that there are other tokens above and below that could require tokens to be inserted between these over time.

A caveat is the ordinal system (primary, secondary, etc) which is meant to suggest priority and hierarchy within the experience, which should not change between token values. As an example, the primary button is the action that we expect the user should take in relation to all other actions on the page. This is regardless of the treatment provided to the button. The primary action should also be apparent in low-fidelity wireframes. Because of this, a specialized purpose of hierarchy within the experience regardless of expression, the token buttonPrimary-bgcolor is appropriate. In contrast, the token space-md cannot be given a purpose in the same way. We cannot accurately determine what a space-md would be in a low-fidelity wireframe nor does it truly matter to the end-user to achieve their goals.

What can be semantic?

Color and typography can be described as semantic tokens. Space can also be semantic if you reprogram the way you think about space. What semantic tokens have in common is that they have a simple, yet consistent, construction:

[purpose]-[priority]-[property]

Priority is optional and introduced if the content described must have an order of importance for the user. Describing space in importance is not necessary. Also, I am omitting interactive alternatives like hover and chosen for simplicity but they may also be included in the construction.

This would suggest that elevation can also be semantic as we use this to describe importance; elements closer to the user should be perceived as more important. So we’d expect tokens such as surface-primary-shadow. Notice that we aren’t introducing surface-highest-shadow as we aren’t attempting to suggest how it looks but again the purpose. modal-shadow could also be appropriately semantic; only a more specific semantic token better known as a component token.

Using the ordinal system helps out in other ways. It ensures that an element is not introduced that attempts to represent “more-than-primary” (something many marketers would love to try). It also suggests that priorities lower than tertiary are cumbersome and therefore avoided. I’d also include that having more than 3 levels is useless for user interpretation within the experience in the same way we often omit heading levels less than h3 from most experiences.

Expanding outside of tokens

In the exploration of Mise en Mode, I also considered suggesting a naming convention for modes. However, I quickly realized that this too required additional context. I mentioned at the end of Ondark Virus that we should consider semantic naming at the scope level. This suggests that the words “light” and “dark” are also inappropriate and considers a possibility where the curation of values is for a semantic purpose. In other words, why do we need this new collection of values? What are we trying to express?

The result of this question should be a research study to uncover why people are asking for “dark mode” because perhaps they are really asking for improved battery performance when browsing or perhaps more contrast for readability. In this way, we encode the purpose for the new collection of values as a semantically named mode which allows the purpose to be understood.

Importantly, I do not suggest that the words “light” and “dark” be reimagined for user preference. I do not believe that users truly understand why they select light or dark without introspective questions or explicit instruction; it often becomes a matter of unconscious preference. However, I believe it is our responsibility in design to understand our users’ needs better than they do so that we provide solutions they didn’t fully realize. In this way, I would recommend renaming “dark mode” internally to align with its semantic purpose, while continuing to expose “dark mode” as a user preference externally. From here, determine why the user selects a mode and provide the appropriate values to reflect this choice based on understood user needs. I will admit, that some users will simply suggest that a mode looks better, but this might be an indication of stylistic preference and suggest they would rather have the ability to customize their experience.

#naming-is-hard because understanding why is hard.

Two Typographic Tricks

Thu, 19 Dec 2024 00:00:00 GMT

I’ve been writing CSS for a long time and it’s really exciting to see the fast improvements to the language that we’ve received over that time. In this post, I’ll demonstrate two ideas that I always wanted to do natively with CSS alone.

First, a warm-up before we get to the wild stuff.

Grid centered line-height

I know of plenty of designers who want to maintain a vertical rhythm for all content on the page. They’ll painstakingly adjust border widths and line-heights to ensure all of the little elements on the page align to some vertical grid such that there’s a rhythm to reading downward.

As the person who wrote Gridless Design, you can imagine how I feel about this. In my opinion, the time spent trying to get this alignment would be more worthwhile on other things; say… improving the user experience as an example. However, now that we have some new CSS in browsers, getting the vertical rhythm to align with your grid can happen at any font size very easily.

We’re going to need a bit of math for this. Let’s say that you have an 8px grid. This means elements on your composition should be sized in multiples of 8px. Let’s also say that your line-height for paragraphs should be 1.4, meaning the resulting height of each line should be 1.4 times the size of the font so the space between lines helps readability. If your paragraph font is 18px, this means the paragraph line-height would result in each line of text being 25.2px high.

$18*1.4=25.2$

Clearly, this doesn’t align to our 8px grid. Historically, we’d curate the line-height each time we introduce a new font-size. In this case, we have to hardcode the line-height knowing the font-size such that it remains on the 8px grid.

.paragraph {
    font-size: 18px;
    line-height: var(--paragraph-lineheight);
}

Rounding to the nearest grid

In order to determine the correct number here, we’ll need to round 25.2 to the nearest 8. Doing this in JavaScript would look like this, assuming the numbers are entered without units:

function lineHeight(fontSize = 18, lhTarget = 1.4, gridUnit = 8) {
    return Math.ceil((fontSize * lhTarget) / gridUnit) * gridUnit;
}

The messy part is rounding to the nearest grid unit. We have to divide 25.2 by 8, then round that to the nearest integer and then multiply by 8 to get 32. This means that the --paragraph-lineheight should be set as 32px when the font size is 18px and the target line height is 1.4.

As you can see, this is very cumbersome. We’d need to know the exact font-size value, the grid unit, and the target line-height for this kind of element to determine the final result.

Luckily, the new round() CSS function can really help us out.

.paragraph {
    line-height: round(up, 1.4em, var(--grid-unit, 8px));
}

This is effectively the same calculation that was demonstrated earlier in JavaScript. The round() function is fairly well supported and can take three arguments:

The first can determine the rounding strategy, in this case we want to round up in the same way we used Math.ceil() before.
The next argument is the number we’re going to be rounding. This will represent the target line-height; basically the minimum line-height allowed. Unfortunately, we can’t use the unitless line-height here but we can use the em version instead which would result in the same final pixel amount.
Finally, the amount to round by. This part of the function is awesome. It avoids all of the weird division and multiplication to round by an amount in the JavaScript. Here, we want to round to the nearest grid unit. In this example, I simply set the default as 8px in the second argument of the var(), and then it can accept any update in the page and fallback to 8px. You can also use any value with units here instead.

You’ll also notice I’m not explicitly setting the font-size here. This is because this line-height value will respect whatever font-size this element is because it’s referencing em units, even if it is inherited from a parent! If your target line-height is meant to be tighter, as is normally the case for headings, you can adjust the target to be smaller like 1.2em.

.heading {
    line-height: round(up, 1.2em, var(--grid-unit, 8px));
}

Here is a codepen demonstrating the technique. The gray lines behind the text represent the grid unit intervals and the red background on the text shows how much space the text takes up. You’ll see that the gray lines will never be cut-off at the bottom of the container because the line-height for this element is always on grid. The span is not important to the CSS, it’s there just to visualize the height of the text.

See the Pen Line Height on grid by Donnie D’Amato (@fauxserious) on CodePen.

Ok, that was a good warm-up. Now it’s time to get wild!

Dynamic letter-spacing

Like line-height, I always felt that tweaking the letter-spacing was a waste of time. Especially as more custom fonts become normal, I felt setting the letter-spacing should be embedded in the font file itself. However, I saw a post by Mathieu Badimon, formerly leading efforts for the design system at Adobe, sharing a way to do this dynamically. The gist is that he’s developed a scale where the letter-spacing of the text will get tighter as the font-size increases. Immediately, I wanted to try to do this in CSS alone. This took much longer than I hoped.

The easy parts

The first thing is that there is an upper and lower limit. This is pretty easy in CSS today using the clamp() function. So we’ll start with that using the values he recommends in the post; Sizes 25px and below should be 0 and -4% for sizes above about 145px. Since, letter-spacing doesn’t accept % units, we’ll use em instead which can be thought of as a percent of the font-size. Remember that the lowest value goes first, that’s why -0.04em is first and 0em is last.

.paragraph {
    letter-spacing: clamp(
        -0.04em,
        var(--ems) * 1em,
        0em
    );
}

Ok, so far so good. Now all we need is the rate of change. You’ll see that there’s a graph included in his post, but he mentions that the graph is actually inaccurate. That’s fine, we’re going to use the numbers he provided later in a comment.

What we want is the rate of change between to points, this can be thought of as finding the slope of a line between points. If we think of the font-size as the y and the resulting percent as x, we can find the slope (m) in the following way:

$m=(y_2-y_1)/(x_2-x_1)$

Plugging in some numbers from the chart, we get the following:

$m=(28-25)/(-.1-0)=-30$

This shouldn’t be a surprise from Mathieu’s post:

The -30 is related to the 30px every 1% decrease. The next thing we need is the formula that produces all of the x values based on a given y. You might remember this formula from school:

$y=mx+b$

However, we want to solve for x, so we need to rearrange the terms:

$x=(y-b)/m$

In this formula, y is our font-size, and m is the slope we got earlier of -30. So what does b represent? It’s where the slope crosses the x-axis. We could find this by moving terms around again, but Mathieu has already provided this number; 25 (for 25px where this calculation starts). Our formula now looks like this:

$percent=(fontsize-25)/-30$

This doesn’t look too intimidating yet, but here’s where it get challenging. We need to turn this into CSS. Let’s try just making some variables for this first:

.paragraph {
    --b: 25px; /** starting size */
    --m: -30; /** rate of change */
    --x: calc(1em - var(--b)) / var(--m)); /** percent? */
    letter-spacing: clamp(
        -0.04em,
        var(--ems) * 1em,
        0em
    );
}

Ok, so far all of this should work. We’re still missing the --ems assignment but we can subtract unit values from each other, and we can divide a unit number by an unitless number. When we subtract units like this, the result is resolved into a pixel amount. This’ll be important later.

The hard parts

The first problem is that --x isn’t a unitless value, it’s a pixel amount. Setting this as the --ems isn’t correct because in Mathieu’s formula, we want a percent of the 1em. So we want --x to have the pixel units removed.

There’s a recent trick made popular by Jane Ori which demonstrates how we might hack CSS to give us unitless values using atan2(). We’ll need to add a few things:

@property --x {
  syntax: "<length>";
  initial-value: 0px;
  inherits: false;
}

.paragraph {
    --b: 25px; /** starting size */
    --m: -30; /** rate of change */
    --x: calc(1em - var(--b)) / var(--m)); /** percent? */
    letter-spacing: clamp(
        -0.04em,
        var(--ems) * 1em,
        0em
    );
}

The first thing we need is to effectively force the --x to give us a pixel amount. It might seem weird that we need to do this since we know it’s resolving as a pixel, but it’ll be important so we can use atan2().

@property --x {
  syntax: "<length>";
  initial-value: 0px;
  inherits: false;
}

.paragraph {
    --b: 25px; /** starting size */
    --m: -30; /** rate of change */
    --x: calc(1em - var(--b)) / var(--m)); /** percent? */
    --ems: tan(atan2(var(--x), 16px); /** percent! */
    letter-spacing: clamp(
        -0.04em,
        var(--ems) * 1em,
        0em
    );
}

You’ll see I’ve added the --ems variable by using the approach in the blog post. You can essentially look at this as returning --x in terms of 16px and return the unitless result. What we have will work, but there’s one small problem. I’ve explicitly set 16px here which is assuming base font size as a fixed pixel amount. Entering 1rem in here doesn’t work (and admittedly I’m not entirely sure why even when updating the @property defaults).

What we’ll need is 1rem in terms of pixels. Luckily, Jane has that example in her post. We’ll use another atan2() to get the unitless number of pixels per rem (16) and expect to replace the 16px with this result. This actually needs a number with a pixel unit so we can do that quickly by multiplying the unitless result of the new atan2() by 1px to finally resolve to 16px. Here’s the whole working declaration, followed by the codepen:

@property --x {
  syntax: "<length>";
  initial-value: 0px;
  inherits: false;
}

@property --rem {
  syntax: "<length>";
  initial-value: 0px;
  inherits: false;
}

.paragraph {
    --rem: 1rem;
    --b: 25px; /** starting size */
    --m: -30; /** rate of change */
    --x: calc(1em - var(--b)) / var(--m)); /** percent? */
    --ems: tan(atan2(
        var(--x),
        calc(tan(atan2(var(--rem), 1px))) * 1px)
    ); /** percent! */
    letter-spacing: clamp(
        -0.04em,
        var(--ems) * 1em,
        0em
    );
}

See the Pen Dynamic letter spacing test by Donnie D’Amato (@fauxserious) on CodePen.

I do wonder if there’s a setup that allows us to remove the second atan2() usage and insert the 1rem directly here but I haven’t found it yet.

Whew, what a ride! Maybe one day, we’ll get a supported way of dividing values with units to return a unitless value. But for now, we can wish upon this proof-of-concept. Thanks to Mathieu and Jane for their resources!

Unicorns on the web

Fri, 19 Apr 2024 00:00:00 GMT

This post is going to be a little different than others, as I expect to update it over time with resources I find about design engineering.

designengineer.xyz

This is one of the first websites I found dedicated to the recent hype. Launched by Karl Koch, it also seems to be one of the most fully covered with design engineering materials and resources such as related posts and jobs.

designengineer.io

Launched very recently by Moe Amaya. This seems to be specifically a job board and it has a sleek design with many visual doodads. It’s interesting that the bottom of the page says “Job board for design engineers…cause there isn’t one” when there’s one right at the top of this list!

designengineer.ing

Launched by Dr. Mehmet Aydın Baytaş. At the time of this writing this only shows an email waitlist. His feed suggests merch will be coming as well.

At this point we should just check for designengineer.[TLD]! designengineer.wtf is currently ~~available~~ taken and I imagine would be a great landing for disambiguating our practice.

designerscancode.com

Launched by Lee Nelson. It markets itself as for designers interested in coding; so maybe not precisely what we might describe as a design engineer, but similarly aligned for sure. This also includes a waitlist but seems to have a bit more polish and content than the other waitlist. It also discloses a few more features expected to launch, such as news and learning materials.

designtechnologist.club

This site by Konstantin Fe which includes a slack community. He has also written a handbook available on the site.

design.engineer

This site is shared by Rick Waalders. At the time of this writing this only shows an email waitlist.

uxe.lab

Created by Mike Posso, it seems to be planned to have frequent challenges and mentorship opportunities to level up peers in the field.

designsystems.engineer

Recent launch by Garth Braithwaite which is currently a newsletter signup. This is meant to be a bit more niche than the others; focusing on design system engineering.

ux.engineering

There’s nothing at this domain, but I’ll call it out because I own it! Is the space saturated? Is there something that these sites miss? Do I need another project to potentially maintain. All very good questions. What should I do?

Wireframe, Backstage

Tue, 26 Mar 2024 00:00:00 GMT

I’ve been an AV nerd for a long time. In one of the first iterations of my personal website, I had something called “Audio Phrekwenci” (pronounced “frequency”), which was an audio blog of sporadic release. I’d record my ramblings to a microphone, edit in some free software, and publish it on my personal server. I had some friends listen to it ever so often and it was fun to talk about.

Since then, I’ve always had the itch to do it again. But one thing was always holding me back; editing. Traditional editing is painful and time-consuming. Now, that technology has come a long way and text-based editing has appeared, it’s finally time to give it a go in a new show called Wireframe.

Concept

The idea was to create a workflow so that once I see an idea or opinion on the internet, I can have the potential to create an episode within 2 hours. Whether or not that happens regularly is not yet determined, but I wanted the ability to respond quickly if appropriate.

To do this, I needed a tight framework of applications to work together that output all of the resources I’d like to provide. Here’s a list of requirements that I had:

Recording equipment, microphone and other devices.
Text-based editing, otherwise this just isn’t happening.
Cloud-based editing, with the option to edit on my tablet.
.mp3 export, seems obvious but needs to be enumerated.
.srt export, the transcript so contents are eventually searchable.
Shownotes editor, a way to include shownotes into the episode page.
Inexpensive/Free audio hosting, not trying to pay for more than I need.

Recording

As an AV nerd, I have a prosumer setup for recording and streaming audio and video. Below is an image from when I was recording my talk for UXDX a few years ago.

I’ve updated the cart a little bit since then. Nearly all of the devices on the desktop have been replaced with a single Roland SR-20HD.

My original plan was to record the media directly to YouTube as unlisted. YouTube provides practically unlimited media storage so I thought this would be a good start. Unfortunately, there’s a few reasons why this didn’t work out.

First, the result was low quality. It was more apparent when choosing to record as a webcam, but using the encoder was also not great either. It would seem I was subject to data packet loss and I’d need to find another way to record. I also tried to use the MediaRecorder API but that also had a quality issue. Certainly, the web isn’t meant to be handling this sort of data.

Second, has to do with the next step of editing. I was very interested in using Streamlabs Podcast Editor as the next part of my workflow. One of its features is the ability to start a project by providing a YouTube link. This means that I wouldn’t need to download the file just to upload it to another platform. The products should be able to talk to each other. This worked in practice with an existing link I had. However, when I tried recording and immediately editing that recording, the download was not available. In fact, it was not available for several hours. This was unacceptable as a primary workflow.

Because of this recording to YouTube was removed as part of the workflow. I still plan to use the platform for the potential of live events.

In the end, I record the footage to an SD card and transfer it to a computer for the next step. Not so futuristic, but maybe there’s more to explore here.

Editing

Certainly, text-based editing was critical in this process. Streamlabs also offers this and my initial tests were very good. The pricing was also excellent, offering 40 hours of transcription; the most out of any web-based editing service I found. While I looked into Descript at the time, the price was more expensive for less hours. Streamlabs also seemed to have everything I wanted in my flow and nothing more; making a much simpler editing experience.

I also happen to have a subscription to Adobe, and have Adobe Premiere Pro which recently released text-based editing as well. The workflow is a little bit convoluted but I got some good results once I figured out there’s a difference between the source transcript and the timeline transcript. However, this is desktop only. So I wouldn’t be able to edit on my tablet. But this would be a good backup solution, except for one problem.

My recording equipment outputs a file where Adobe Premiere can’t render audio. I don’t know why this is, as when I play the file anywhere else the audio exists. The only thing I’ve noticed so far is that the audio sampling rate from the equipment is 48000Hz, while all of the other files I have are 44100Hz. Not sure if that’s the issue but, seems like Adobe is just not going to work here.

When it came time to produce the pilot, I did all of the editing within Streamlabs. Then I went to export the file as an mp3. The process of doing this was not expected. While I understand I need to have the file encoded, I wasn’t expecting an email with the result. Additionally, that email didn’t have the file within it. It was a link back to the project, which was a page of different links; none of which were mp3 files. The file I was able to download was a .mp4 which was unplayable. I’ve reached out to their support on this and they claim that the mp3 export is possible but it’s not clear.

Realizing that less and less of my expectations were being met with Streamlabs, I got an account with Descript and re-edited the footage there. The experience was more inline with my expectations; able to receive an .mp3 file and an .srt file for the episode. It also seems I can record to the platform here as well. I might revisit my workflow to record to the cloud instead of SD card transfer if the quality behaves.

Hosting

This was one of the easiest choices but it took some time to find. I decided to use Acast to host the episodes as I didn’t want to host audio files on Netlify. The platform has unlimited hosting and downloads of episodes. It also can add an intro & outro to every episode; no need to edit it into the file beforehand. It provides a nicely styled RSS feed.

One thing that I want to mention: do not play with the feed redirect settings. I made the mistake of testing this out and it took several days for customer service to revert this since you’re unable to go back yourself once you do it. The messaging is misleading in that setting; saying “you can easily reverse the redirection if needed”. Easy means contact customer service, so don’t do that. It’s only needed if you no longer want to use Acast.

Website

I was heavily inspired by Syntax. I truly appreciate those folks providing the site as source code so I can get some ideas on how to provide content about the show.

While I don’t have all of their bells & whistles, one thing I knew that I wanted was to have the transcript and shownotes combined into a single Markdown file. I had the idea of using Markdown footnote syntax to pepper the transcript with footnote marks. Then the Astro Markdown renderer would automatically create a shownotes section using that syntax.

This was also the first time I used the new subgrid syntax for the episodes to get the content alignment between the cards. You won’t notice this until there are more episodes. Setting grid-row: span 2 on the children of the parent grid was the key to making this work.

Another thing that I created was a page to help create an episode entry for the website from the Acast feed. Once I publish an episode, I can visit a special page on the website that fetches the feed and allows me to add the transcript and tags to create a new .md file for the website. The submit button creates a PR in Github, and there I can add the shownote markings before publishing. Github has a nice web editor for markdown files where you can preview the result.

One thing that I needed to consider was that the intro added in Acast would cause all of the transcripts offset to be inaccurate. This means that I’d need to offset the transcript times by the intro seconds. I had made a small function that would update all of the transcript times. That looks like this:


// Convert a string time into seconds
function timecodeToSeconds(t) {
  return t.split(':').reduce((acc,time) => (60 * acc) + +time);
}

// Convert seconds into string time
function secondsToTime(seconds) {
    return [
        parseInt(seconds / 60 / 60),
        parseInt(seconds / 60 % 60),
        parseInt(seconds % 60)
    ]
        .join(":")
        .replace(/\b(\d)\b/g, "0$1")
}

// Find timecodes, update with the seconds offset
function timescriptTimeOffset(srt, offset) {
    return srt.replace(/((?:\d+:)+\d+,\d+)/gm, function (m) {
        const [code, ms] = m.split(',');
        const time = timecodeToSeconds(code) + Number(offset);
        return [secondsToTime(time), ms].join(',');
    });
}

So, for now the workflow is: record to SD card, edit in Descript, publish on Acast, and finalize through Github.

Stop, collaborate, and listen

And that’s it! The pilot is out, and I plan to have a new episode at least once a week for the next few months. You can also follow @wireframefm on Twitter. I expect to add syndications in the next week or so to your favorite platforms.

Your first component

Fri, 10 Jan 2025 00:00:00 GMT

Cory LaViska of Shoelace fame posted this a few days ago:

when building a component library, what component do you build first and why is it always button?

— Cory LaViska

It’s a similar question that starts Dan Mall’s talk he first performed at Clarity 2022. Dan argues that the button doesn’t provide impact to teams; buttons are easy and obvious. It would be more useful to determine what component would be the most impactful and then contribute that to the business. In Dan’s talk, he uses the example of a map component for Uber which is essential to the experience and wildly complex. I disagree that the map is a good choice for the design systems team to tackle, but I agree with the sentiment of prioritizing impact.

However, for folks that are dipping their toes into design systems, Cory’s question is interesting. Why is the button the first thing most folks build?

Popularity

I was having a dinner conversation with Adekunle Oduye one evening where I was asking him a similar question; how do we choose what components belong in a design system? For many folks, we’d look at existing systems and inventory what the most popular components are. Looking at component.gallery, Button is the most popular component with 141 examples at the time of this writing. It would make sense that because it is the most popular component, it probably belongs in your system too.

But this should introduce a new question. When the first design systems were starting, how did they know they needed these components? The answer is doing their own inventory local to their companies’ needs. In fact, that’s ultimately what Dan is suggesting in his talk. The design system should be a reflection of the people it is made for. So what components you maintain should be determined by an internal inventory of usage.

It is easy to tie impact to how often something is needed. The more it is needed, the more it impacts the final result. Therefore, because the button tends to be the most popular, we tend to want to build it first.

Necessity

Since we want interactive websites, we expect that we will need a button at the very least, even if that button operates as a link. Without interactivity, a website is a one-sided conversation. There’s no navigation, no feedback. It might as well be a piece of paper to be read once and maybe bookmarked for later. To begin turning a web page into something a little more, that interactivity is needed.

Importantly, I don’t believe small sites need design systems. In fact, most of the personal websites I’ve created don’t have a design system; just some reusable styles. Larger sites beget interactivity to traverse between the homepage, dashboard, products, checkout, and beyond. Each one of those pages is expecting a user to achieve some goal. To do that, the user needs to make choices, and those choices are coded as moments of interactivity within buttons, among other controls.

Complexity

So far, I’ve been making a case for why you’ll probably need a button in your system. I haven’t yet touched upon why it’s most likely first.

The button component is deviously complex in the number of states and priorities it could be meant to convey. When we alter a single presentational attribute, it could convey a whole new meaning to the user. This is especially apparent by the way we’ve landed on our common naming system for buttons. In other words, the button is the only interactive control that can convey priority. There is no such thing as a “primary” text field. As an example, the primary button is meant to guide the user to the most likely direction they should take.

Getting all the visual treatments right such that they convey the correct information can be a daunting exercise for folks unfamilar with the permutations. However, this is also the only hard part about the button. There’s really only one thing the button can do, accept a click. So we can focus our attention on the visual treatment alone. Which leads to the next reason.

Containment

The button is mostly often considerd an “atomic” component, meaning it is commonly not broken down to further elements. Many other components are composed of other pieces and with each additional piece added to a component, more complexity is added. So not only would a person need to make decisions on the visual treatment of each part, you’d also need to make decisions on how these pieces work between themselves and in some cases within the larger composition they’ll be set within.

Since the button is self-contained and has no real complexity past the various visual treatments, we tend to tackle this low-hanging fruit first as a quick win.

Tokens

The final note to mention is that we often spend a great deal of time curating tokens, either by choosing names or their values. In order to test our architectures, it would be most helpful to assign these tokens to something that can show coverage easily. The button having lots of potential in visual complexity and customization, while being a small self-contained component, makes it a excellent “test” component to build where you can curate your token architectures and check the visual result in something you have confidence will appear on any page.

So all of these things contribute to the reason why I believe the button tends to be first in our libraries. In my system playground, it was probably the first “non-primitive” component.