DEV Community: Grant Forrest

CSS-only auto spatial hierarchy with container style queries

Grant Forrest — Wed, 16 Jul 2025 13:34:17 +0000

I wasn't particularly interested in the new CSS container style queries at first -- I mean, we already have inheritance and attribute queries, right?

But then in the shower this morning the pieces started to fall together for how this feature could finally catch one of my CSS white whales: proportional nesting values!

The law of spatial hierarchy

If you've ever worked with a designer or studied visual design at all, you know about hierarchy. One of the common rules of spatial hierarchy is that related elements should be closer to one another, and unrelated ones should be further away.

In the above wireframe, I've highlighted the spatial hierarchy principle in action: form labels and grouped buttons are much closer to one another than the fields are.

For this reason, designs will often use progressively smaller spacing values as container nesting increases. For example, the fields in a form may be spaced with --space-md, while the label and input are spaced with --space-sm, visually "grouping" them together.

It's generally up to developers to pay attention to spacing sizes and implement them appropriately. But this manual effort can only go so far. One of the problems with flattening systematic rules into coded values is you lose 'contextuality.' Understanding of context is moved from the system to the implementer (designer / developer), so the computer (which is good at consistent logic) cannot help us remain consistent and logical anymore.

I'll follow this up with a more in-depth thoughts later on, but first let's dive into what didn't work before @container style and what works now.

Using conditionals to power proportional nested values

So, fundamentally, what we want to do is this:

If a box is nested within another box, its spacing values (gap, padding) should be proportional to the parent

What didn't work before

Like I said, this has been a white whale for a bit. I've attempted this kind of thing before, but it never worked due to circular property references. Consider the following CSS:

.box {
    --spacing: calc(var(--spacing) / 2);
}

Theoretically this expresses our rule, and in an imperative programming language this would work.

let spacing = 1;
spacing = spacing / 2; // just fine!

But in CSS this doesn't work, because this is a property declaration, not an assignment. The value of calc(var(--spacing)... used to "assign" --spacing isn't referencing the parent scope; it's referencing our --spacing: a circular reference. If you try this and open your inspector, you will see that the end result is --spacing is not defined at all.

And for a long time, that was a dead end. No amount of clever tricks I could think of (e.g. having two different variables) would violate this circular logic. It seemed mathematically impossible with the way CSS is designed.

What works now

Leveraging @container style(), we can indeed get this working with a clever trick.

Let's jump right to the demo, and then I'll explain.

Don't just look at the result -- notice the markup that accomplished it. That's the cool part!

How it works

To start off, I'm establishing a system of custom properties to "smuggle" an inherited value past the circular reference problem:

--ctx-mode: A generic 1/2 state value which tells us which "mode" the current nested element is in. Keep reading.
--ctx-nest-1: "Mode 1" nesting variable. To avoid circular referencing, this computes itself from --ctx-nest-2.
--ctx-nest-2: "Mode 2" nesting variable. To avoid circular referencing, this computes itself from --ctx-nest-1.

Now, I'd tried something like this before, but the problem is that to make this work fully automatically with no other JS or markup required, you'd have to apply CSS like so:

.box {
  --ctx-nest-1: calc(var(--ctx-nest-2) / 2);
  --ctx-nest-2: calc(var(--ctx-nest-1) / 2);
}

... thus arriving at a circular reference again. Why? Because if we refuse to force developers to treat nested elements any differently (like, applying a mode-1 or mode-2 class), both of these properties need to be defined on every element, and we had no way of saying "alternate nesting elements" to only apply one at a time. Normal CSS nesting selectors like .box .box { also wouldn't work, because the same rules will be applied to every nesting element, not every other alternating nested element.

This is all recursive stuff and kind of hard to think about, so don't worry too much if my explanations aren't sufficient... It does work.

Breaking it down

We can use @container style(--ctx-mode: ...) to solve this problem by creating two style queries which do the alternation for us. They are mirror images of each other, so I'll just break down the first one.

@container style(--ctx-mode: 1) {

For parents with mode: 1

  .box {

Targeting a child box class

    --ctx-mode: 2;

Flip mode to 2 (we are nesting now)

    --ctx-nest-2: calc(var(--ctx-nest-1) / 2);

Compute the new nesting multiplier from our parent's (who is mode 1, since we are mode 2).

    --ctx-nest: var(--ctx-nest-2);

Assign our common-use property from the active mode's value.

Then we add the inverse CSS for style(--ctx-mode: 2).

Now nested boxes will have alternating --ctx-nest and values which gradually get smaller! Behind the scenes, this is what it looks like.

Box 1: --ctx-nest: 1, --ctx-nest-1: 1; (default value, no @container style query matches)
- Box 2: --ctx-nest: 0.5, --ctx-nest-2: 0.5;, --ctx-nest-1: 1; (inherited)
  - Box 3: --ctx-nest: 0.25, --ctx-nest-1: 0.25;, --ctx-nest-2: 0.5; (inherited)
  - ...

At each level, we alternately subdivide either --ctx-nest-1 or --ctx-nest-2 depending on the flip-flop mode, then apply the subdivided value to a common --ctx-nest property that can be safely used by the element's styling without worrying about the rest of the logic.

How to use it

My example above demonstrates the principle, but how you apply it may depend on what you want to use proportional nesting for, and in particular, how you want to modify the value as it nests. Usage also gets more convenient if you utilize encapsulated components, either via a framework or Custom Elements, since you can move the main nesting logic into its own class applied within the component instead of having to apply it to every nested element.

Anyways, the core concept can be captured in the following CSS:

.nesting {
    /* Initial defaults, applied to highest first matching element */
    --ctx-mode: 1;
    --ctx-nest-1: 1;
    /*
        NOTE: you do not want to define --ctx-nest-2 here. The trick relies on
        it not being defined for every other element
    */
    --ctx-nest: 1;
}

@container style(--ctx-mode: 1) {
    .nesting {
        --ctx-mode: 2;
        --ctx-nest-2: calc(var(--ctx-nest-1) / 2);
        --ctx-nest: var(--ctx-nest-2);
    }
}
@container style(--ctx-mode: 2) {
    .nesting {
        --ctx-mode: 1;
        --ctx-nest-1: calc(var(--ctx-nest-2) / 2);
        --ctx-nest: var(--ctx-nest-1);
    }
}

If you apply the nesting class to your nestable elements, they will compute the correct nested value (1, 0.5, 0.25, ...) according to the hierarchy and provide it on --ctx-nest for you to use in any calculations you choose.

Further ideas

With the basics settled, some improvements come to mind:

Resetting nesting context

You don't always want to treat nested containers as spatial hierarchy. It's convenient to have it as the rule, but when you want to make an exception, you could have a class like this:

.nesting-reset {
    --ctx-mode: 1;
    --ctx-nest-1: 1;
    --ctx-nest: var(--ctx-nest-1);
}

Semantically it might make sense to reset the nesting context for elements which are visually separate from the flow of the page already, like bordered cards. It's also important if you're using popovers or other surfaces which have their own visual hierarchy context.

You could use the same principle to override the nesting value starting point of a subtree by setting --ctx-nest-1: 0.5 or whatever, if you want to hardcode a particular section to start out with tighter spacing than the global default.

Variable nesting factor

Instead of hardcoding / 2 as the nesting division factor, we could make it a custom property.

Now you could either configure this globally (like a design system token) or override it on-demand at a particular element.

This also lets you be a little more flexible with how you adjust the nesting factor instead of enforcing the same division everywhere. One can imagine utility classes like .nesting-tight or .nesting-loose, for example, which adjust the --ctx-nest-factor property used to compute nested values and increase or reduce the subdivision factor.

You can decide whether to configure this property to be inheritable or not -- I'm not sure which behavior is preferable at the moment, but I'm inclined to make it non-inheritable, personally. This would mean you can selectively tighten the nesting up for one element and any further children will resume the normal pattern. But again, not sure yet, inheritance could be good too.

Safeguards

The best systems are resilient, and I can think of at least one way this spatial hierarchy could fail: too much nesting! Pretty quickly, you'll probably start hitting sub-1-pixel gaps, especially if you use a larger division factor like 1/4.

It would probably be a good idea to use max() to ensure a minimum value for --ctx-nest before assigning it. After a certain level of nesting, this would make the hierarchy simply 'turn off' and create uniform spacing. While not "systematic" this is perfectly reasonable behavior as you reach 1-2px. Having some gap is important. Of course, you may want to evaluate why such deep nesting is occurring and whether the system needs to accommodate that more explicitly, or if the nesting itself is wrong.

Separate, namespaced nesting contexts

If you want to have multiple independently tracked nesting values, you could namespace your properties and copy the same structure, i.e. --ctx-foo-nest-mode/--ctx-foo-nest-1/.nesting-foo etc. This would let you repeat this nesting proportional value pattern for different semantic uses without overlapping.

For example, if you wanted to do a nesting color gradient with one context, while having nested spacing be independent from it and on a different multiplier scale.

A more concrete demo, and more "why"

The UI expressed in the demo above is not particularly exciting (or pretty), but what I really find compelling is the markup. Especially if you imagine component encapsulation which automatically applies the nesting class for you.

The point here is: as a developer, I no longer have to personally manage spacing sizes. I am free from the tyranny of gap-sm, gap-md, gap-lg, and so on. I can simply say: gap, and let the system decide how much to apply based on my hierarchy.

This also means if I encapsulate a portion of the UI, such as the signup form, into a reusable component, that component will adapt its spacing hierarchy to its container wherever it is used. You won't ever have the problem of the gap between label and input accidentally being the same as the gap between the form and its sibling, for example, even if you drop it in somewhere the original designers didn't anticipate. Hierarchy is encoded into the system.

As a designer, maybe (just maybe) this lets you encode good design rules into the product without relying on every frontend developer fully understanding their usage and implementing them faithfully. Again... maybe! Reality will probably be more tricky.

This is all a bit arbitrary right now, but I believe this could potentially be a very powerful tool if refined into a coherent design system. But in the end, perhaps design is not as predictable and systematic as one hopes. Either way, I'm glad to finally have realized this CSS dream.

A comprehensive guide to making your web app feel native

Grant Forrest — Tue, 15 Aug 2023 04:00:00 +0000

When it comes to apps, the web always feels a little second-class.

Sure, we’ve had some advancements in the web platform which make it more capable of powering app-like experiences. Greater device access, “install” options on phones, share targets, and the like have all made web apps feel more native. But these advances on their own won’t convince a user that your web-based product is on par with a native app. More work goes into thoughtfully designing that experience before the lines start to blur. That’s what I’ll be covering here.

But first, for the native elitists… yeah, I know a single-threaded browser view has some hard limits in terms of raw ability to compete with an optimized, native app. But for relatively simple apps on most phones, with a little effort it can be hard for most users to tell the difference. Real-world experience is what matters here, not theoretical technical differences.

Also, this isn’t the kind of post where I’m going to give you a bunch of code to copy and try. Most of this stuff is highly dependent on how your app works. What I’m going over here are principles, the implementation is up to you.

It starts with a PWA

This almost goes without saying, but you need a PWA (Portable Web App) to get things started. That means you need two things: a service worker, and a manifest.

The Service Worker

The service worker doesn’t have to be particularly fancy to get started, but in order to really nail the native feeling, we’re going to go the extra mile and precache our application for offline use. All HTML, JS, and (optionally) media assets can be downloaded once, then loaded from disk instead of network for future launches. That’ll make loads much faster for repeated use, and even (if your application supports it… more later) let the user use your app while their data connection is spotty.

Precaching client files and offline support

I’ll note that you can have a service worker which just has an “offline” page that shows up whenever the user isn’t able to connect, but this is an article about making your app feel native, and native apps don’t do that. So we can’t stop there.

Luckily, there are plenty of great tools like Workbox which help us deal with service worker precaching without having to be an expert on service workers. And there are even integrations with builders like Webpack or Vite that will automatically detect our app assets and generate a “precache manifest” for us! I highly recommend this. In fact, I use these exclusively, so I can’t even really explain to you how to do it at a lower level. A little lazy of me as an author, I know, but my goal is to make functional apps, not know all the minute inner workings for their own sake. Tools like Workbox or vite-plugin-pwa haven’t let me down.

The important thing to know at a high level is that we need to gather up a list of every URL that our app needs to request (whether it be an HTML, JS, CSS, or asset file) that we want to be available offline, and register those in our service worker.

When those change, which always happens when you change your app code or swap out an image, we re-generate that list. This changes the actual code of our service worker, because it’s using that list (often just an inline array of strings) within its own code. The browser notices the service worker code is different, and from there we can pre-fetch those new assets, cache them, and prepare to update the app.

App updates

This is a big one that folks getting started in PWAs underestimate. Probably because this is one of the biggest ways PWAs differ from a traditional web-based experience. Instead of the user always loading the latest version of your client files after you push an update, they’ll still be on the older version the next time they launch the app, since we’ve precached those files.

It’s only after the app loads up on the old, precached version, that it will fetch the new version in the background. This often takes a second or more. Then, you have a chance to manually initiate an update of the app in your code. That looks like this, usually:

// In your service worker file:

// This allows the web app to trigger skipWaiting via
// registration.waiting.postMessage({type: 'SKIP_WAITING'})
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'SKIP_WAITING') {
    self.skipWaiting();
  }
});

We add an event handler in the service worker file to listen for messages from the main client. If the client sends a SKIP_WAITING message, that means “don’t wait for the right time to update the app code; let’s update it now!” If you don’t do this, even refreshing will still stick with the old, precached version of your app.

On the client, we do this when we’re ready to update:

// tell the service worker to install immediately so we're ready with the new app
// on next page load
function updateApp() {
  navigator.serviceWorker.controller?.postMessage({ type: 'SKIP_WAITING' });
}

// listen for the install, reload the page when ready
let refreshing = false;
navigator.serviceWorker.addEventListener('controllerchange', () => {
  if (refreshing) return;
  refreshing = true;
  window.location.reload();
});

What this means for you, practically, is that you have to decide how to get the user on your new app version, and how urgent that is. There are a few common strategies, but for all of them I’ll be using this helper function to listen for incoming updates:

function onUpdateReady(callback) {
  navigator.serviceWorker
    .register('/service-worker.js')
    .then((registration) => {
      registration.addEventListener('updatefound', () => {
        registration.installing.onstatechange = function () {
          // No arrow function because 'this' is needed.
          if (this.state == 'installed') {
            if (!navigator.serviceWorker.controller) {
              console.log('First install for this service worker.');
            } else {
              callback();
            }
          }
        };
      });
    });
}

If you’re using a service worker helper library like Workbox (which I highly recommend doing), there may be versions of these helpers already available to you. Read the docs!

Update strategies

Update immediately when available. This refreshes the page without user input. It might be seamless enough if your app is very small, but as the download size becomes larger, the delay from launch to unexpected refresh gets long enough to become actively disruptive. I don’t recommend it.

onUpdateReady(updateApp);

Show an update prompt when the update is available. This might be the most common approach, and you’ll see it often in more mature web apps. Usually takes the form of a small, dismissible popup in the corner with a call to action to update and refresh.

onUpdateReady(() => {
  showInstallPrompt();
});

onInstallPromptClick(updateApp);

Wait for navigation and update. I don’t actually know if many people besides me do this, but basically I wait for the user to click a link, and if an update is ready to install, I interrupt the normal navigation and do an update and reload. In my app, a navigation event is a reasonable time to briefly interrupt the user which won’t be frustrating or disorienting.

let updateAvailable = false;

onUpdateReady(() => {
  updateAvailable = true;
});

// in each link you want to trigger updates...
link.addEventListener('click', (ev) => {
  if (updateAvailable) {
    ev.preventDefault();
    updateApp();
  }
});

Wait for next launch to update. If there’s really no rush to update, you can always wait until the user closes the app completely. The browser will automatically launch the latest version when they come back. No code needed for this one, but keep in mind that it’s up to the browser how it will decide when the app is ‘closed’ and ready to update; it may keep tabs in memory long after the browser app has been backgrounded.

Be careful with server-side features

One big reason you may want the user to update sooner rather than later is if your app relies on server-side APIs or realtime features. You might push a change to how these features work which is incompatible with older client versions. With PWA, even though the new version is downloaded and ready to install, the user won’t know there’s an update until you tell them. If you don’t tell them, but the client starts breaking due to server-side incompatibility, the user will assume your app is broken.

If your app relies on server-side features which could be incompatible during a version change, I’d recommend one or both of these strategies:

Always support backwards-compatibility for a certain time period. Give your users some time to update the app via the methods above. Keep in mind that users who don’t update in this time period may still experience problems.
Decide on an error code which indicates an update is required. You can standardize some error code in your API payloads which your client will see and recognize that it needs to prompt the user to update ASAP. This can trigger a mandatory modal which initiates the update process, or just reload the page outright.

Can I just say, for a moment, before we move on—despite how much harder this update process is for a beginner to grok, I think it’s really cool that we get this much control over how our apps update on the web. We don’t even have to wait until the user closes the app to load in new code! While often PWA update implementations are clunky, with a bit of work I think you can create a great experience.

The Manifest

The manifest gives us nice integration features with the host OS and browser. We can specify a color for the browser chrome (theme_color) and add nice icons for different occasions.

Icons

Different sizes of icons are important to look good in a variety of contexts. Not much to say about these, and if you’ve ever followed a PWA tutorial you already know about them. I recommend using a tool to generate these from a source icon rather than making them manually.

Maskable icon

It’s important to add a maskable icon if you want your app’s homescreen icon to look good, especially on Android. Normal icons will get shoved inside a white circle in Android’s launcher, which makes it really obvious which apps are PWAs, and generally looks bad. But the maskable icon doesn’t!

Your maskable icon should have ample space around the outside so that it can adapt to different icon shapes. It must also have a solid background.

For more specifics, you should definitely check out the documentation.

Install screenshots

Here’s a hidden gem for PWAs (well, Android PWAs… opened in Chrome…): you can set up fancy, App-Store-like screenshot previews of your app that show up right in the PWA install prompt! Although the use case is very platform-limited, Chrome users will get a really slick install experience if you add some screenshots to your manifest.

screenshots: [
    {
        src: 'images/screenshots/list.png',
        type: 'image/png',
        sizes: '1170x2532',
    },
    {
        src: 'images/screenshots/recipe_overview.png',
        type: 'image/png',
        sizes: '1170x2532',
    },
    {
        src: 'images/screenshots/cooking.png',
        type: 'image/png',
        sizes: '1170x2532',
    },
]

System color scheme

Users expect native apps to integrate well with the OS, and one way to fulfill that on the web is to inherit your light/dark mode configuration from the device.

What that means in practice is utilizing the @media(prefers-colors-scheme: dark) and @media(prefers-color-scheme: light) media queries when defining your theme styles. Beyond that it will depend on how you’re implementing dark/light themes.

For my apps I utilize CSS vars for my theme, so what I actually end up doing is creating one block for each of those queries and defining all of the theme color vars. Then, to let users override the system theme in app settings, I also define a second set of blocks which define the opposite theme colors when the .override-dark or .override-light class is applied to the html element. This makes theme overriding as simple as storing user config in localStorage (or a cookie to use server-side rendering) and setting an .override-dark or .override-light class on html if the user has indicated a preference.

/**
 * Default light theme (if you default dark, use a media query)
 * here and remove the one on the dark theme in the next block
 */
html {
  --color-paper: white;
  --color-ink: black;
  /** etc */
}

/** Default dark theme */
@media (prefers-color-scheme: dark) {
  html {
    --color-paper: black;
    --color-ink: white;
  }
}

/** User override: prefers dark, but system is light */
@media (prefers-color-scheme: light) {
  html.override-dark {
    --color-paper: black;
    --color-ink: white;
  }
}

/** User override: prefers light, but system is dark */
@media (prefers-color-scheme: dark) {
  html.override-light {
    --color-paper: white;
    --color-ink: black;
  }
}

You might be clever enough to make this more succinct, but I just created some processor functions to do this for me, which works fine for my ends.

Smart loading

All apps need to load data. But native apps often are loading it from the local filesystem, not a server somewhere else. One of the subtle indications to a user that they’re using a browser is how things get loaded: blank white screens for page transitions, and a multitude of spinners in single-page apps. How can web apps compete in loading UX?

Start using local data

This will heavily depend on your use case, but it is possible to load your data from the local device in a web app. Even if the source of truth is on your server!

There are two main ways to store local device data on the web - the Storage APIs, and IndexedDB.

You may be familiar with the Storage APIs from using localStorage . There’s also its less permanent cousin, sessionStorage. People do use these tools to store complex data (like using JSON.stringify), but they’re really meant as simple key-value stores. I think mostly folks use them for complicated data because IndexedDB is so intimidating to get started with. I get it, but eventually serializing and deserializing data out of localStorage is going to be too much overhead.

I’d honestly recommend reading the docs for IndexedDB. If you’re comfortable with how callbacks work, I find it’s not so much effort to get the boilerplate out of the way and wrap it up in a custom API which conforms to your personal needs.

That said, there are some great ways to wrap IndexedDB to make it easier to work with. Since I’m writing this article I’ll toss in my local-first framework Verdant, which can be used without the sync features as a standalone IndexedDB-powered database with a type-safe schema and deployable data migrations. For a lighter-weight approach, maybe check out Dexie.

However, you don’t have to rely only on local data to use these solutions. If your app data all lives in the cloud, you can still cache that data (or a relevant subset) locally on-device using web storage tools, so it’s ready instantly (and offline!) whenever the user opens the app. Many existing app state management systems, like Redux and Zustand, have plug-in systems to “persist” data for you easily. They’ll load data from disk to resume the last state, and then if network is available, they’ll repopulate it once the fetching is complete.

Side note: how about local-first?

Something web developers take for granted is the idea that there's a server out there with a database, and that's where user data lives. But servers cost money to keep running, which incentivises you as an app provider to try to monetize your users with stuff like ads.

And while there's definitely no shortage of ad-funded apps on mobile marketplaces, they can actually be more sustainable business-wise because they don't assume data needs to live on a server. For a simple app that's only managing a user's personal data, like a grocery list, why not exclusively use IndexedDB?

This is a growing area of focus in some web communities, and it's called local-first. Verdant is a full local-first framework, including upgrading to multi-device sync and multiplayer with a server when you're ready. I wrote a bit on it elsewhere, and there's an emerging community around local-first more broadly. Check it out!

Delay transitions until data is loaded

It’s not all about load times, though, in practice. It matters how you load—how you represent the loading state to users. Try opening the Settings on your phone and tapping one of the options (maybe something with a decent amount of loading to do — like the list of all your installed apps). Notice what you don’t see (at least on most recent phones). It’s a spinner.

What I see, on Android, is the option I tapped plays a brief animation to indicate that it registered my intent. Then, for a few milliseconds, nothing happens… until the page I navigated to animates into view, fully loaded.

This is a big thing web developers get wrong, thanks in part to a sort of spinner / “skeleton” obsession among common web learning material. Everyone loves making a fancy loading spinner, but the hard truth is, if done well, the user should almost never see it.

The key is, instead of immediately updating the interface before the data to render it is ready, you instead want to establish this “native” feeling pattern for your interactions:

Immediately and clearly register user intent (with a visual state change)
Keep the current UI intact while you load in the background—including allowing interactions
Only transition when the next view is ready

Now, that’s an ideal world case, but there are a few addendums for extraordinary circumstances:

If the delay in loading is more than a few seconds, show another affordance to assure the user you’re working on their action
If the action the user took implies an immediate change of location, go ahead and transition and show a spinner (I’ll cover those cases in a bit)

Registering intent

I think in part this kind of loading flow isn’t taught because it relies on some design sense, not just technical ability. You have to step back and understand what the user is trying to do, not just what the software is capable of.

Which also means I can’t give you a code sample and banket advice here. What you have to do is think about what this action means to your user. Things like, “I selected a settings menu option, so I want to see that sub-menu,” or, “I entered a new search term, I expect to see different results.” The end-goal of that action (the sub-menu, the new results) is something you can’t do yet (hence the loading). So what can you do in the meantime, besides showing a new blank page with a spinner, to assure the user that they did successfully execute their action? Maybe change the background color of the button, or animate the border of the search bar. It’s fun to get creative with this, and these are the details that really count toward making your app feel high-quality.

Parallel loading

In the meantime, while you’re showing the initial affordance, you want to immediately begin loading the next step. For a well-architected web app, this often means loading a code-split bundle of code which powers the next page. There’s probably also some data you want to load, either from an API or IndexedDB. All of these things are async, they take time, but they don’t block the main thread.

The real trick here is how to capture that loaded data and use it for the next step of the process. Different tools have different ways to do this, and some are ambivalent about how you accomplish it.

How to do it in React (with Suspense)

Since I have a lot of React experience, I’ll note here that this is what React’s Suspense and Concurrent Mode features are designed to tackle. Rather than being responsible for capturing and caching the newly loaded data and getting it to the next view, React lets you directly request that data within the components that power that view like you normally would, but it won’t actually show the new UI until that loading is complete. With Suspense, React will either show a fallback (passed as a prop to your Suspense boundary) or, if you’re using useTransition, it will actually keep rendering your old UI until the Suspense loading is resolved.

That means, once you understand Suspense and useTransition, you can get this parallel loading basically for free—keep writing your app like normal, and sprinkle in these two features as needed to keep transitions smooth. One of the reasons I’m still rooting for React after so many years is that they’ve clearly taken these kinds of details into account as the library has evolved.

How to do it anywhere

React isn’t, and shouldn’t be, the whole web. It’s best to learn these principles from fundamentals, so stepping away from React’s particular approach—what are we trying to accomplish?

It’s simple enough to fire off a fetch when your user clicks a link (and prevent default navigation), wait for that fetch to resolve, and then update the URL. The part that’s a little more ambiguous is how you get your data from that event handler into your new UI state once you’ve transitioned.

This is where it’s helpful to have some centralized app state. For example, if you’re using a Zustand store as your main app state, instead of simply fetching in your click handler, you can integrate that data retrieval into your central store, and cache the resulting data so that it’s ready to use in the upcoming view. This also works out-of-the-box in a higher-level API client like Apollo for GraphQL.

// in pseudo-code...

// a rough sketch of a very simple client
class Client {
  cache = new Map();

  load = async (key) => {
    const data = await query(key);
    this.cache.set(key, data);
  };

  get = (key) => Map.get(key) ?? null;
}
const client = new Client();

// this handler is attached to an <a> which loads the new page
async function onLinkClick(ev) {
  // prevent immediate navigation
  ev.preventDefault();
  // begin the initial affordance to show the user their action is registered.
  // in this case, let's assume that's done with a CSS animation on the link itself,
  // controlled by a class.
  ev.target.classList.add('link-loading');
  // preload necessary data. this assumes the client will cache this data once loaded.
  await client.load(
    '... whatever query / fetch you need for the next page ...',
  );
  // resume navigation
  history.pushState({}, '', ev.target.href);
}

// this code renders the new page
async function renderOtherPage() {
  // suppose our client allows a simple get on the data from the cache. if the
  // data isn't preloaded, this returns null
  let data = client.get(
    '... whatever query / fetch you need for the next page ...',
  );
  if (!data) {
    data = await client.load(
      '... whatever query / fetch you need for the next page ...',
    );
  }
  renderTheUI(data);
}

What you’re really trying to make sure happens here, is that when you move the user to the next UI state, it doesn’t trigger a re-loading of the data. To write your UI in such a way that it can effectively render whether the data is already cached, or if it still has to be fetched from storage or network.

Additional affordances

Sometimes, loading can take a while. In that case, we want to reassure the user that the app is still functioning and processing their action. One way to do this is to queue up another affordance after a set time elapses and our preload hasn’t yet finished. You'll often see this in the form of a progress bar that spans the top of the page.

In React, this can be done by observing the boolean returned from useTransition which indicates a transition is in progress, and a debounced effect to update additional state.

const [isPending, startTransition] = useTransition();
const [isLongTransition, setIsLongTransition] = useState(false);

// this is not ideal use of state but should illustrate the concept.
useEffect(() => {
  if (isPending) {
    const timeout = setTimeout(() => {
      setIsLongTransition(true);
    }, 2000);
    return () => clearTimeout(timeout);
  } else {
    setIsLongTransition(false);
  }
}, [isPending]);

Or, with any or no framework, you can likewise utilize setTimeout to update state after an elapsed period. Just make sure to cancel the timeout once the loading resolves.

async function onLinkClick(ev) {
  ev.preventDefault();

  ev.target.classList.add('link-loading');

  // set a timer for a secondary affordance
  const timeout = setTimeout(() => {
    body.classList.add('long-loading');
  }, 2000);

  await client.load(
    '... whatever query / fetch you need for the next page ...',
  );

  // clear timeout. if timer already fired, also remove secondary affordance.
  clearTimeout(timeout);
  body.classList.remove('long-loading');

  history.pushState({}, '', ev.target.href);
}

Exceptions to pre-loading

Some actions should trigger an immediate transition, even if that means showing a spinner. For example, clicking “Create Note” in a notes app should probably not sit loading on the current page until the new note is ready to edit, as this may result in user confusion depending on the order of loading. For example, in the video below, the new recipe is created and added to the list before the page transition is ready.

A purposefully broken create recipe flow demonstrated in my app, Gnocchi. [Video]

If the loading were to take a second or two longer, the user might be confused and click the card manually. While it’s not the end of the world, this order of events drives user confusion and a sense that the app is not well-designed.

Instead, we omit all of the fancy stuff above in cases like this, and go ahead and navigate to the next page immediately. Loading states on that page will take care of providing proper UX while the data needed to render the UI is being loaded.

You may discover other cases where an immediate transition is needed, like when first typing into a search bar. It’ll depend on how your app functions, how you structure your views, and other factors which only you know!

Styling elements for interaction

The web ships with some fairly good interactive element user-agent styles, but anyone who’s done even a little web development knows the first thing most people do is clear all that away. Each product has its own unique style. Unfortunately, that means re-inventing all those various interaction states for all your elements in your design system. I’ve observed that often, somewhere between design teams and engineers, some of these states get overlooked or misunderstood.

The goal of this article isn’t really to educate on those states (the important ones are here, but read the whole list, you’d be surprised what you can do!). But there are some styling considerations which may not be immediately obvious which you should consider if your goal is making your web app feel native.

`:active` or no?

:active is the button’s “pressed” state, and using it is can make buttons feel responsive to user input. But it’s worth saying here: open up some native apps on your phone and tap some buttons. Very few of them seem to have a pressed state (at least on mine). That seems counter-intuitive! Native apps usually feel snappy and responsive, so what’s up with not using a state that directly responds to user input?

My theory on this is: more visual transitions = more user perception of effort. Native apps feel snappy in large part because they don’t have time to show you an intermediate pressed state on a button. The very millisecond your finger leaves contact with the screen, the UI is already moving. If possible, mimic that snappiness! You may not need a pressed state at all.

However, as noted in the last section, sometimes loading is inevitable. That’s where the initial affordance for loading comes in. This is often attached to the interactive element (link or button) which triggered the loading. Still, if the loading is fast enough, the user may never see that affordance, and that’s a good thing. You may even want to add a transition-delay of a few milliseconds just to see if you can avoid showing it!

Nevertheless, you may want to add a pressed state to your buttons, anyway. Maybe you just like the way it feels. With a warning aside that this may make your app feel less native, my recommendation is to choose something subtle but recognizable—maybe some small motion, like Google’s Material “ink drop” effect, or a little scale-down as if the button is being pushed backward. Just don’t overdo it!

Prefer `:focus-visible` to `:focus`, but DO use it

Perhaps one of the most common lines of CSS is button:focus { outline: none; }. I mean, let’s face it, the built-in browser focus outlines are ugly. They don’t even follow border radius!

But you can’t stop there, because accessibility matters. If you’ve ever tried applying your own focus styles, though (maybe using box-shadow to get that nice border radius curve), you’ll quickly notice that buttons get “stuck” after you press them. Because they remain focused after press!

A demonstration of sticky buttons: [Video]

That’s why :focus-visible exists. It’s only applied when focus is controlled more intentionally, like via keyboard. So put your focus styles in there, and your buttons will feel more springy.

`user-select: none`

When was the last time you accidentally highlighted an image in a native app? Never? That’s because native UIs don’t even allow that (at least, by default). In fact, more often than not, you can’t select most text in native apps… even stuff you really should be able to.

If you’re feeling gutsy, do a * { user-select: none }, then re-enable it for blocks of text you want to let users highlight and copy. If that seems a little too extreme, you can at least safely do it on img and other elements you definitely don't want selected. Avoid the nasty, fourth-wall-breaking effect of accidentally starting text selection when you were just trying to scroll!

Overscroll behavior

This is a sneaky one that a lot of mobile web app makers miss. When you scroll to the end of a webpage on Android, the page stretches and bounces a bit. What this usually means, if you have stuff like an absolute-positioned navigation, is that empty white space becomes visible at the edges of your app. Really breaks the immersion!

Plus, if you scroll up at the top of the page, you’ll get a pull-down-to-refresh experience. Native apps don’t have that (well, if they do, it’s one that they control—not on every single page).

However, you want to be mindful of user expectations here. When viewing your app as a webpage in the browser, users should still be able to use these tools. We just want to remove them in the PWA, to get a more native feel.

This is one thing I can just toss you some code for:

@media (display-mode: standalone) {
  html,
  body {
    overscroll-behavior: none;
  }
}

Turning off overscroll behavior removes both rubberbanding and pull-to-refresh. Now the edges of your scrolled pages will feel nice and solid.

However, if you do want a pull to refresh (like on a home feed), you’re gonna have to figure that out yourself. But anyway, you probably didn’t want the blank-page full-refresh behavior, anyway.

Sheets

If you aren’t familiar, a “sheet” is a term for a dialog that’s anchored to one edge of the screen. On mobile, you see a lot of sheets which are bottom-anchored.

Sheets are simply easier to use with one hand on a phone, since they position controls near the bottom of the screen instead of the center. It’s a little trickier to pull off than just bottom: 0px though.

One big sticking point is the mobile keyboard. If your dialog/sheet features text input, you don’t want the keyboard to overlap the sheet when it pops open. On Android, the touch keyboard doesn’t resize the window, it overlaps the page content. That means you need to position your sheet’s bottom edge to match the height of the keyboard.

The visual viewport height can also change when the user scrolls, if their mobile browser hides its URL bar and other chrome after scrolling.

Not only that, but on iOS, the viewport area extends down underneath the main navigation gesture bar, which can overlap your content. Why can’t anything be simple?

This is a problem I’m still figuring out myself. If you’ve got simple solutions, I’d love to hear them. But here’s what I’ve come up with:

Establish and update CSS vars for the viewport “safe area”

When the virtual keyboard appears or disappears, it will trigger a resize event on window.visualViewport (did you know that was a thing?).

So what I start off with is listening to that event and the window’s scroll event, and triggering a callback to apply some CSS vars to the document which I can use elsewhere in CSS calculations.

const update = () => {
  document.documentElement.style.setProperty(
    '--viewport-bottom-offset',
    `${window.innerHeight - viewport.height}px`,
  );
  document.documentElement.style.setProperty(
    '--viewport-height',
    `${viewport.height}px`,
  );
};

update();

window.addEventListener('scroll', update, { passive: true });
// not all browsers support this.
if (window.visualViewport) {
  viewport.addEventListener('resize', update);
}

Now, I can use the --viewport-bottom-offset var to set the bottom value for a sheet. I add a fallback of 0px just in case.

bottom: var(--viewport-bottom-offset, 0px);

Utilize `safe-area-inset` environment vars

On supported devices, there’s also the built-in safe-area-inset collection of CSS vars which can help you avoid things like the global navigation gesture bar and camera cutouts.

You don’t want to use these to offset the sheet position—otherwise the sheet would ‘hover’ above the navigation bar. Instead, I use it to pad the bottom of the sheet to ensure that content doesn’t get overlapped.

padding-bottom: calc(3rem + env(safe-area-inset-bottom, 0px));

These techniques combined can help to position sheets correctly, but I’m afraid there’s still some instability possible when doing text input with the virtual keyboard, especially if you trigger focus on the text input immediately when showing the dialog. Hopefully I can find some more stable solutions.

Swipe to dismiss

Another native feature of sheets which you can copy is the swipe-to-dismiss gesture. This lets the user swipe downward on the sheet to close it (after a certain threshold).

The GitHub app has great sheet gestures. [Video]

Some important details about this gesture:

There’s usually a visual affordance in the form of a small horizontal bar at the top of the sheet.
Despite that affordance, the user can begin the gesture anywhere on the sheet.
If the sheet has scrolling content, the gesture only triggers when that content is scrolled to the top. Otherwise, swiping downward scrolls up, like normal.
The gesture can be cancelled by either ending before the threshold, or swiping back upward.
Some fancier sheets even let you drag upward to expand the sheet to be larger and show more content.

It’s ambitious to copy all these behaviors, but you could start by adding swipe-to-dismiss starting just from the top edge of the sheet and work from there. Most users probably see the visual affordance and anchor their swipe there, anyways, so you can avoid worrying about scrolling content for an MVP implementation.

Bottom tab navigation

Lots of native apps have settled on a bottom-tab navigation structure. It’s convenient and easy to reach! But just like sheets, there’s a little more to doing this right than meets the eye.

Well, ok, it’s the same problem. You need to make sure the system gesture bar doesn’t overlap your nav. Time to break out env(safe-area-inset-bottom) again! Just pad the bottom of your nav with that value plus a bit extra to make sure users can utilize your nav bar.

That said, there’s one more important rule: don’t put more than 5 items in there (and I think 4 is a better maximum). This is an information architecture problem, and big name apps have teams of designers who have done tons of work on it for their particular use cases. You’ll have to do your best, too: figure out a maximum of 5 categories that encompass the core experiences in your app. All your pages should be structured under these categories.

That’s not to say you can’t cheat a little bit. For example, Spotify doesn’t put user settings in their nav bar, they make it accessible only on the “Home” screen in the top right corner. It’s a good trick for less-frequently-used pages.

But seriously, if mature and multi-featured apps like Spotify and Slack can figure out how to present 5 or fewer top-level navigation options, so can you!

A special note on `select`

Select is a disaster. It’s practically unstylable. But it has one key benefit: natively, it adapts well to phone input. Instead of trying to place a little pop-over somewhere on the already cramped mobile screen, HTML’s Select just drops a full modal over the whole UI for simple, finger-friendly selection.

There are still problems with this, though. You can only represent a simple list of text options. Anything fancier—colors, user avatars, badges, whatever—and you’re out of luck.

Take note of how native apps manage selects like this. For one, they’re not very common. Yet another reason to avoid them! But when you need one, good UX is a little more nuanced than you think.

For just a few options: try a pop-over

The GitHub app uses a simple dropdown for the three-option status selector

Selects should never have fewer than 3 options (if you’ve only got 2, use a different element!). But if you’ve got 3 or 4, and they’re relatively compact labels, a pop-over is fine and gives quick, localized access.

For more: use a sheet

The GitHub app opens a sheet for the long list of labels in the label selector

What’s better than the browser’s native select modal dialog? A sheet positioned at the bottom of the screen for easy reach. In a sheet, you can list as many options as you like, plus include fancy controls for filtering. Think of this as a UX opportunity, not extra work!

Of course, how you approach this in code will be the challenge. Supporting two entirely different interactions on mobile and desktop can be a burden. I’d say it depends on your primary target platform. If you’re mobile-focused, there’s no reason you can’t get by with a sheet interface on desktop, too (maybe give it a maximum width, or even alter its positioning so it shows up as a centered, typical dialog).

Using platform features

You’re a web app, not a website. Why not use some of the available features on your user’s device? While many features are need-based (like location, or the camera), there are some goodies you can sprinkle in to make your experience feel less like a page inside a browser, and more like software running right on the device.

Rumble!

Don’t overdo this! It bears repeating—don’t overdo it! But using haptic feedback can be a very situational but powerful tool for UX. I particularly like to use it when an action triggers something which may happen out of view. For example, in my groceries app, I give your phone a little shake when you add items to your list from a different page, just to confirm that those items really did get added even though you can’t see your list.

Share targets

Did you know you can get your PWA into the system share dialog? I think it’s one of the coolest things PWAs can do! When you register as a share target, users can “Share to” your app, and you get either a POST payload or a set of query parameters (your choice) that include a link or some text they shared.

You don’t need a server to handle a share. Even with the POST version, you can write a handler in your service worker to respond to it on-device for static-only sites.

// in your service worker...

self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);

  // detect a share event from the PWA
  if (event.request.method === 'POST' && url.pathname === '/share') {
    // redirect so the user can refresh without resending data
    event.respondWith(Response.redirect('/'));
    // handle the share!
  }
});

Check out more on how to use share targets here.

The extra mile(s)

I think those things cover the table stakes of creating a good mobile app experience on the web. Now let’s get into the things that will make users forget it’s a website. We're going beyond just making it feel native, we're making it feel like a genuinely good app.

Fair warning: these are even more work!

Follow the OS’ design principles

iOS and Android have different design sensibilities which differ from browser user-agent styling and from each other. Since native apps are often building on the same tools as first-party apps, they often have an easier time looking and feeling like their host OS. The culture around native apps is also different (and, seemingly, different between iOS and Android); there’s more expectation to fit in with the native design system.

On the web, we’re a little unmoored from any native design. There’s no telling what the browser which views your page looks like, and on top of that, the host OS is also variable. Trying to conform website styles to their surroundings is a losing battle, but you can make some tweaks to fit in better on iOS and Android specifically if your focus is mobile. Two customization targets are a little easier to manage than a hundred permutations (although still very… extra).

And, in fact, mobile design is sort of converging a bit at a high level on flat color shapes and simplified elements, so even just adapting your own designs to those common details can help you fit in.

For example, most mobile system UI buttons (right now) have large border radii, often extending across the entire horizontal edges (i.e. border-radius: 100%). They’re also solid-colored. That’s a pretty easy update to make in your CSS to feel more at home.

Don’t want to change your desktop styles, too? As far as I know, this is an imprecise science. You could try using a small media query size, like (max-width: 720px). But desktop windows can get that small, too. Whether you care is up to you.

For a more robust option, you might try using Javascript to check the user-agent for mobile tags, then apply a class on your body which other elements can use to select their own rules, like body.ios button { ... }. Keep in mind that this may result in a flash of different styling, though, unless you’re doing server-side rendering and can pre-populate that class in the initial HTML payload by inspecting headers. This all sounds more trouble than it’s worth to me, though, just riffing.

Disable context menus

This is similar to user-select: none, but a little more… contextual. Especially for links, even if user-select: none is applied, the user can still long-press and get the boring old browser context menu, which offers to copy the link address, open in the browser, etc.

I think sometimes you want to let users do this, especially for inline text links. But for situations like app navigation, probably not! Disable the context menu on those by calling preventDefault on the contextmenu event.

Swipe-based navigation

This is one of those really hard things that lucky native mobile developers get more or less for free. Ever noticed how in some apps with bottom-bar tab navigation, you can often swipe to the left or right to change pages? It's not super common, but I've noticed first-party apps do it more.

Yeah, stop and think about how you’d do that with your web app! Keep in mind it’s not just a binary gesture; you can move your finger around and the whole view moves with it. Move it back to cancel the gesture entirely.

GPay is one of those rare apps that has swipe-based navigation, and it feels great. [Video]

If you really want to show off, try doing this in your app. I did it with Gnocchi, and it was challenging but fun to pull off. I had to create my own client-side routing library! My approach was to create a component which could render the UI for any particular URL, even if that URL doesn’t match the browser’s current location. Then, when the user’s gesture triggers a threshold of movement, I render the page to the left or right of the current one, using CSS transform to control the displacement according to finger position.

My app, Gnocchi, uses swipe-based navigation. It was a pain but it's fun to play with! [Video]

I’m sure there are other ways to approach this without writing your own router. Perhaps you can encapsulate individual pages in their own reusable components more effectively than I did, and just render those components. But using paths seemed relatively simple to me at the time. Your mileage may vary!

Nonetheless, this is a small but difficult thing which adds a ton to the overall user experience feeling ‘native.’ Users take this gesture for granted in apps they use every day. If you want them to really forget it’s a web app, try replicating it!

One caveat, this won't be a good gesture if your app already has horizontal gestures for actions like archiving list items.

Conclusion

Wow, that’s a lot of work just to feel native, right? Are web apps a bad idea?

In my opinion: not at all! For one, a lot of these things are going to benefit your app when running on non-mobile platforms, too. And, at the end of the day, your app can run on other platforms! It may take some effort and intentionality, even a bit of hard work, but I think it’s possible to live the dream of one cross-platform codebase without trading off a good, close-to-native experience. It’s why I love being a web developer.

Here’s to better web apps!

Calm tools

Grant Forrest — Tue, 11 Jul 2023 02:43:05 +0000

My cooking app, Gnocchi, does not help you find recipes.

There's no weekly newsletter, no hub for self-published recipes and comment boxes, no home feed to scroll.

At first, these things were on my roadmap. After all, a lot of cooking is deciding what to cook. Doesn't it make sense that the same app that helps you plan out grocery runs and organize your favorite recipes is also the place you go to discover new ideas? Wouldn't it be cool to have great chefs posting their latest inventions in a foodie social network? Think of all the shares that might generate! User growth, engagement, success!

That progression may seem natural in our current tech product landscape, but it's really just one particular path. A framework, a worldview. And one which I am more and more consciously trying to avoid.

Busy Technology

Nearly everything we interact with online is trying to acquire our attention. Cooking sites are a prime example of the phenomenon. You can't just have a grocery list, or a recipe keeper. It has to bother you to turn on notifications (why?), sign up for the daily newsletter of new recipes, scroll the infinite list of user-created content presented right on the homepage. The website is designed to keep you there, keep you scrolling, and the reason is as straightforward as it is painfully in your face: ads. Again, cooking spaces online excel (read: horrify) here. Instead of spending 10 minutes learning how to prepare the fresh green beans I got from my produce co-op, I'm stuck scrolling through paragraph after paragraph of how you met your spouse at the farmer's market while video after video obstructs half of my phone screen. Now the garlic is burning in the pan but I can't find the next step because the content layout shifted with a new batch of ads.

(Seriously, turn off your adblocker/pihole, open a food blog and watch the network tab of your devtools. The amount of ad traffic is wild.)

It's not at all that I blame the chefs for this, really. This is the way the technological ecosystem they operate in was designed. The incentives are encoded into the way we make websites, do business, and even think about what the internet is.

But as a software developer and a tool maker, I'm grateful I have some power to forge a different path.

Tool vs Lifestyle

The internet and smartphone era has shifted our understanding of software. Now, I'm out on a limb in saying that—I basically came of age on the internet, so I can only infer what it felt like to build and use software before, say, search engines. But my impression is that we began thinking of computers as a tool to help us implement existing life-processes (business procedures, hobbies, chores) more efficiently or effectively. Then, over the course of decades, we began thinking of computers as a medium to re-invent those processes. Computing became a lifestyle.

How did we once connect with friends? Far enough back, it was visiting one another. Then, sending mail. Phones closed the loop even further. Texting, further still. It might be easy to plot social media along that trendline, but I think that somewhere between SMS and message boards, the lifestyle shift began. Communication is no longer an event we initiate mutually with someone we know. Our friends feel 'present' all the time, through their feeds and stories and reels in our pocket. We can scroll endless feeds of communication, often with people we don't know, and join in anytime (think how dead a social network would feel if it were only friends you knew IRL. Only like, a few posts an hour, how would you scroll??). But I think many folks feel that something has been lost for all that we gained.

For my part, I think about how we used to cook compared to how modern recipe websites want us to. There's not a huge difference in the general form of it. You seek out dish ideas, discover some publications you find some rapport with, and clip the recipes you want to try later. For my mom, this meant subscribing to cooking magazines which showed up in her mailbox each month. What does it look like for me? Realistically, it's googling the kind of dish I want to make and "recipe," then looking for a link to Bon Appetit or a food blog I've had good results from before, like Cafe Delites (try the baked honey garlic salmon).

In principle these are fairly similar patterns of behavior, but things begin to diverge in terms of how our digital cooking tools have evolved. I've noticed over the years how a lot of cooking sites have created their own versions of a shopping list. Even on small food blogs, usually they're using a Wordpress plugin which offers to add the recipe ingredients to your grocery list. The problem here is obvious if you spend a lot of time browsing recipe sites: it's not the same list. Every publication or plugin has its own, separate list. The objective (cynically interpreted) is to try to lure you into a walled garden and incentivize you to visit that site more often than the others, since it's where your list is.

I don't know anyone who uses these things. Why would you? Why choose to tie your shopping list to AllRecipes? So what I used to do was just copy-paste things into Google Keep. It worked fine, plus my wife also had access to the list.

But it began to bug me how little software was helping me perform my life tasks more efficiently and effectively. My mom would jot down ingredients she needed on a pad of paper with the Cooking Light magazine open in front of her. Now I was arduously copy-pasting text from one app to another in my phone. Honestly, the notepad is probably easier. Recipe sites don't want to help me plan groceries like I want to, but better—they want me to adopt their lifestyle for how I cook and shop.

I'm not saying this is a malicious thing. Yes, there's the ad impressions incentive, but I don't think the kinds of people who painstakingly take beautiful photos of each step of a recipe are consciously doing it to lock me into their ecosystem and collect ad revenue. But that's the way the internet works these days, that's how you do business. They have to—right?

Reclaiming Software as Tool

So I thought, maybe I can do this differently. I've built up a lot of skills I need to launch a web app over the years, and I love cooking and have some opinions about how I want to go about it. And since I've observed this anti-pattern at play, I also have a good shot at avoiding it if I'm careful about how I proceed.

That process eventually lead to Gnocchi, but first I had to create Verdant, my local-first web toolkit. To reinvent how web products work on a business level, I had to do a little re-invention of the technical level, too. Local-first is a burgeoning space with a lot of talented and creative builders, I'd recommend taking a look.

I go into this more at length elsewhere, but one of the core motivators for me going to local-first was sustainable "free trials" — software runs on the user's device, not my servers, so I can let people use it for free without running a deficit. This aligns the incentives for paying (access to server-powered features like sync and multiplayer) with my incentives as a maker (I don't have to buy server time unless people are paying me for it). Compare that to traditional cloud models, where every free user costs you money. It's a little simplistic, but I think that misalignment is the source of a lot of the web's problems, and drives the ad- (or data)-economy dysfunction which leads product managers to distort perfectly usable tools into lifestyle products and ecosystems that keep your attention captive.

Meanwhile, I know two things:

If you're using the app for free, that's great, keep doing that forever. No issue for me.
If you're paying for more features, that's also great. One or two subscriptions keep the server online.

It might be harder for me to "scale" with this kind of model, but it puts me in a very nice spot for focusing on solving real user problems, because I'm not under existential pressure to pay cloud bills or raise the next round of funding.

It also means I am not in the attention economy. I gain nothing if you have my app open for hours at a time. Which is good, because this is a grocery list; the goal is efficiency! I don't want to have an incentive to keep the user in my app when what they're trying to do is get through the grocery store or finish preparing a weeknight dinner. That would tempt me to make my product worse for my own gain.

Turning Away from Engagement Addiction

When my incentives and my user's incentives are more aligned, I am empowered to respect their goals and process more—to adapt my tool to them, not try to adapt their behavior to my product.

In this case, I'm my own user. We have a lot of cookbooks in our house, full of a lot of recipes I've never tried. I want to cook some of them! So every once in a while I'll open one up and find something that sounds delicious. My problem really wasn't not being able to discover new recipes; they're everywhere! It was just getting them all in one place and pulling a grocery list together.

So, while it might increase 'engagement' to build that recipe social hub into my app, I eventually realized this was my "web as lifestyle" training speaking. Did I, the guy cooking dinner, really want a recipe social hub? Or was that just me, the guy who thinks "user engagement" is important for his app? I had to remind myself: I can keep this app going indefinitely. Nobody really needs to spend their attention on it. It can just be a good tool, used when needed, invisible when not.

Will people find that worth paying for? I'm not really sure yet, but I suppose I'll find out. Either way, I'm happy with what I've created, and I use it every week. That feels great.

Tools are Calm

Think about a hammer. Nothing about its appearance really grabs your attention. It doesn't have a notification chime to remind you to pick it up. There's no LCD screen to keep track of your total number of swings and award badges. The tool is there when you need it, crafted solely for its task. When we need a tool, we reach for it. And, as it happens, the more we value a process, the more we invest in our tools.

Tools like that are an example of a Calm Technology. Fit to their purpose, respectful of your objective, and demanding nothing else of you but to use them well. I hope as we continue to grapple with the busy, disruptive, demanding experiences we have created in this era of software, we can begin to reclaim a bit of that calm.